added manpage

diff --git a/Makefile b/Makefile
index 94e4831e6b2baa9cb79c8b7874fd7b4a773c4fb3..068f0fa3914f81318f2f559ddc71ce9421099830 100644 (file)
--- a/Makefile
+++ b/Makefile
@@ -18,8 +18,11 @@ install: all
        mkdir -p ${PREFIX}/bin
        cp -f ${TARGET} ${PREFIX}/bin
        chmod 755 ${PREFIX}/bin/${TARGET}
+       mkdir -p ${MANPREFIX}/man1
+       sed "s/VERSION/${VERSION}/" < ${TARGET}.1 > ${MANPREFIX}/man1/${TARGET}.1
+       chmod 644 ${MANPREFIX}/man1/ust.1
 
 uninstall:
-       rm -f ${PREFIX}/bin/${TARGET}
+       rm -f ${PREFIX}/bin/${TARGET} ${MANPREFIX}/man1/${TARGET}.1
 
 .PHONY: all clean install uninstall 

diff --git a/README.md b/README.md
index ed51c114753192da7c336fa13303348f8c33cde0..5810f7e6842e6fa328d945860e166adf0a74e6bb 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,56 +1,9 @@
-## Flags
+## Installation
 
-All flags can have their default values set by modifying `config.h`, additional info and configuration options are also available in the file
+Before installing, check config.mk - inside the file the installation directories can be set.
 
- * `--line|-l line` - line (device) to open, can be specified with `/dev/` or as just the device name
- * `--verbose|-v` - toggle verbose output
- * `--speed|-s # | -#` - set baudrate
- * `--rx-speed|-i` - set separate baudrate for RX line, same as TX if not set explicitly
- * `--data|-D bits` - set data bits
- * `--stop-bits|-S bits` - set stop bits 
- * `--software|-X` - toggle XON/XOFF flow control
- * `--delay|-d delay` - delay between sending characters (in nanoseconds)
- * `--min-chars|-m` - the minimal number of characters to start sending to the line
- * `--backspace|-b` - toggle between ASCII `DELETE` and `BACKSPACE` characters for backspace key
- * `--echo|-h` - toggle local echo (half-duplex mode)
- * `--canonical|-c` - toggle canonical mode (text can be edited locally before sending it to the line)
+To install, simply run:
 
-> If both even and odd parity flags are set, parity is disabled
-
- * `--odd|-o` - toggle odd parity
- * `--even|-e` - toggle even parity
-
-> If both hardware flow control flags are set, DCD flow control is enabled
-
- * `--hardware-rts-cts|-R` - toggle RTS/CTS flow control
- * `--hardware-dtr-dsr|-r` - toggle DTR/DSR flow control
-
-> Multiple translation options should be specified with multiple flags, e.g., `-t no-cr -t no-lf`  
-
- * `--translation|-t option` - CR and LF translation for data sent
- * `--input-translation|-T option` - CR and LF translation for data read
-
-### Options:
-
- * `cr-to-lf`
- * `cr-in-lf` - CR to CRLF
- * `no-cr`
- * `lf-to-cr`
- * `lf-in-cr` - LF to CRLF
- * `no-lf`
-
-## Interactive use
-
-Special character (`~` by default, may be set in `config.h`) will be escaped if it's the first one in the buffer.
-
-### Commands
-
- * `.` - drop connection and exit
- * `b` - toggle backspace character between the two
- * `h` - toggle local echo
- * `c` - toggle canonical mode
- * `s` - set new baudrate
- * `d` - set new character delay
- * `t|T` - toggle a translation option for output|input
- * `w` - write file contents to the line
- * `p` - send a DCD pulse
+```
+make install
+```

diff --git a/ust.1 b/ust.1
new file mode 100644 (file)
index 0000000..fd7c0e2
--- /dev/null
+++ b/ust.1
@@ -0,0 +1,155 @@
+.Dd ust\-VERSION
+.Dt UST 1
+.Os
+.Sh NAME
+.Nm ust
+.Nd uncomplicated serial terminal
+.Sh SYNOPSIS
+.Nm
+.Op Fl \-line|\-l Ar line
+.Op Fl \-speed|\-s Ar # | Ar \-#
+.Op Fl \-rx\-speed|\-i Ar #
+.Op Fl \-data\-bits|\-D Ar #
+.Op Fl \-stop\-bits|\-S
+.Op Fl \-even|\-e
+.Op Fl \-odd|\-o
+.Op Fl \-hardware\-rts\-cts|\-r
+.Op Fl \-hardware\-dtr\-dsr|\-R
+.Op Fl \-software|\-X
+.Op Fl \-delay|\-d Ar #
+.Op Fl \-min\-chars|\-m Ar #
+.Op Fl \-canonical|\-c
+.Op Fl \-echo|\-h
+.Op Fl \-backspace|\-b
+.Op Fl \-verbose|\-v
+.Op Fl \-translation|\-t Ar option
+.Op Fl \-input\-translation|\-T Ar option
+.Sh DESCRIPTION
+.Nm
+is a simple, highly configurable serial terminal with stdin/stdout redirection support.
+Unlike other utilities of it's kind,
+.Nm
+always has all options set \- even the line (device name).
+So running ust without any arguments:
+.Pp
+.Bd -literal -offset indent
+$ ust
+.Ed
+.Pp
+Will make it try to open the line specified in 
+.Ar config.h .
+This way the user might set a default config for a specific device without any additional sh scripts or aliases, or just set a different default for a few options as their preference.
+.Sh OPTIONS
+.Bl -tag -width ".Fl \-line|\-l Ar line"
+.It Fl \-line|\-l Ar line
+The device name can be input in two formats:
+.Ar '/dev/cua00'
+or
+.Ar `cua00` .
+.It Fl \-speed|\-s Ar # | Ar \-#
+Baudrate set by this flag also applies to RX baud if that wasn't explicitly set.
+.It Fl \-rx\-speed|\-i Ar #
+Separate baudrate for RX line.
+.It Fl \-data\-bits|\-D Ar #
+Data bits, may be set to:
+.Ar 8 ,
+.Ar 7 ,
+.Ar 6
+or
+.Ar 5 .
+.It Fl \-stop\-bits|\-S
+Two stop bits are set if the flag is toggled on (in case of 
+.Ar 5
+data bits, it's 1,5, which just means that the line is in marking state for the duration equal to 1,5 times the standard bit period)
+when toggle is off 1 stop bit is set in every case.
+.It Fl \-even|\-e
+Toggle even parity.
+.It Fl \-odd|\-o
+Toggle odd parity (toggling both on disables parity entirely).
+.It Fl \-hardware\-rts\-cts|\-r
+Toggle RTS/CTS flow control.
+.It Fl \-hardware\-dtr\-dsr|\-R
+Toggle DTR/DSR flow control (setting both hardware flow control options will enable DCD flow control).
+.It Fl \-software|\-X
+Toggle XON/XOFF software flow control (can be enabled with hardware flow control simultaneously).
+.It Fl \-delay|\-d Ar #
+Delay between sending multiple characters (when redirecting stdin or writing a file) to the line in nanoseconds.
+.It Fl \-min\-chars|\-m Ar #
+The minimum of characters to input before they get sent to the line.
+.It Fl \-canonical|\-c
+Toggle canonical mode (the ability to edit the input locally before sending it to the line).
+.It Fl \-echo|\-h
+Toggle local echo (half\-duplex mode).
+.It Fl \-backspace|\-b
+Toggle the backspace key character between
+.Ar \&^H
+and
+.Ar \&^? .
+.It Fl \-verbose|\-v
+Toggle verbose output printed to stderr.
+.It Fl \-translation|\-t Ar option
+Toggle translation options (to the line) for CR and LF, toggling multiple should be done like so:
+.Fl t Ar no\-cr Fl t Ar no\-lf .
+.It Fl \-input\-translation|\-T Ar option
+Toggle translation options (from the line) for CR an LF, the options are:
+.Pp
+.Ar cr\-to\-lf
+.Ar cr\-in\-lf
+.Ar no\-cr
+.Ar lf\-to\-cr
+.Ar lf\-in\-cr
+.Ar no\-lf
+.Pp
+.Sh USAGE
+If the first character in the input buffer is the special character (tilde by default, can be changed in 
+.Ar config.h )
+it will be escaped and the next character may run a command.
+.Bl -tag -width ".Fl \&. No or Ar \&^D"
+.It Ar \&. No or Ar \&^D
+Drop the connection and exit.
+.It Ar s
+Set new speed (both TX and RX).
+.It Ar d
+Set new character delay.
+.It Ar b
+Toggle backspace character
+.It Ar t No | Ar T
+Toggle a translation option (output|input).
+.It Ar c
+Toggle canonical mode
+.It Ar h
+Toggle echo.
+.It Ar w
+Write a file to the line.
+.It Ar p
+Send a DCD pulse.
+.Sh EXIT STATUS
+.Pp
+.Nm 
+exits 2 if some of the user\-set options were invalid and exits 1 on general errors.
+.Sh EXAMPLES
+.Ed
+.Pp
+Pipe the utility and write output to a file.
+.Bd -literal -offset indent
+$ printf "00,78,FFFF\\r45\\r" | ust \-19200 \-d 9000000 > wozmon.out
+$ cat wozmon.out
+00,78,FFFF
+
+00: 54
+78: CE
+FFFF: 00
+
+45
+
+45: 9A
+
+.Ed
+.Pp
+.Ed
+.Sh SEE ALSO
+.Xr stty 1 ,
+.Xr cu 1 ,
+.Xr tip 1
+.Sh BUGS
+The program is still in development, if you are reading this, know that a lot of functionality does not work or work as expected.