manpage overhaul

diff --git a/ust.1 b/ust.1
index 5e481499ee836568b5b099b5869f15378c7a3410..9d7e694bf3ac68fca950c157f78d36b1dc8ec5d6 100644 (file)
--- a/ust.1
+++ b/ust.1
@@ -6,91 +6,85 @@
 .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
+.Op Fl bcehorRsSvX
+.Op Fl l Ar line
+.Op Fl s Ar # | Ar \-#
+.Op Fl i Ar #
+.Op Fl D Ar #
+.Op Fl d Ar #
+.Op Fl m Ar #
+.Op Fl t Ar option
+.Op Fl 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 
+So running ust without any arguments 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.
+This way the user might set the program up for a specific device without any additional shell scripts or aliases, or just set a different default for a few options according to their preferences.
+
+.Nm
+relies on the parent terminal emulator for the actual terminal handling and does not open a secondary buffer, so it may overwrite data in the scrollback buffer.
+All messages sent by the program itself (verbose mode info, error messages, exit messages) are directed to stderr (fd 2), this way, one may easily filter the data recieved from the line and messages from the program.
 .Sh OPTIONS
-.Bl -tag -width ".Fl \-line|\-l Ar line"
-.It Fl \-line|\-l Ar line
+.Bl -tag -width ".Fl l , \-line Ar line"
+.It Fl l , \-line 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 #
+.It Fl s , \-speed Ar # | Ar \-#
+Baud rate set by this flag also applies to RX baud rate if that wasn't explicitly set.
+.It Fl i , \-rx\-speed Ar #
+Separate baud rate for RX line.
+.It Fl D , \-data\-bits 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 
+.It Fl S , \-stop\-bits
+.Ar 2
+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
+data bits, it's 
+.Ar 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
+.Ar 1
+stop bit is set in every case.
+.It Fl e , \-even
 Toggle even parity.
-.It Fl \-odd|\-o
+.It Fl o , \-odd
 Toggle odd parity (toggling both on disables parity entirely).
-.It Fl \-hardware\-rts\-cts|\-r
+.It Fl r , \-hardware\-rts\-cts
 Toggle RTS/CTS flow control.
-.It Fl \-hardware\-dtr\-dsr|\-R
+.It Fl R , \-hardware\-dtr\-dsr
 Toggle DTR/DSR flow control (setting both hardware flow control options will enable DCD flow control).
-.It Fl \-software|\-X
+.It Fl X , \-software
 Toggle XON/XOFF software flow control (can be enabled with hardware flow control simultaneously).
-.It Fl \-delay|\-d Ar #
+.It Fl d , \-delay Ar #
 Delay between sending multiple characters (when redirecting stdin or writing a file) to the line in nanoseconds.
-.It Fl \-min\-chars|\-m Ar #
+.It Fl m , \-min\-chars Ar #
 The minimum of characters to input before they get sent to the line.
-.It Fl \-canonical|\-c
+.It Fl c , \-canonical
 Toggle canonical mode (the ability to edit the input locally before sending it to the line).
-.It Fl \-echo|\-h
+.It Fl h , \-echo
 Toggle local echo (half\-duplex mode).
-.It Fl \-backspace|\-b
+.It Fl b , \-backspace
 Toggle the backspace key character between
 .Ar \&^H
 and
 .Ar \&^? .
-.It Fl \-verbose|\-v
+.It Fl v , \-verbose
 Toggle verbose output printed to stderr.
-.It Fl \-translation|\-t Ar option
+.It Fl t , \-translation 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
+.It Fl T , \-input\-translation Ar option
 Toggle translation options (from the line) for CR an LF, the options are:
 .Pp
 .Ar cr\-to\-lf
@@ -108,17 +102,17 @@ it will be escaped and the next character may run a command.
 .It Ar \&. No or Ar \&^D
 Drop the connection and exit.
 .It Ar s
-Set new speed (both TX and RX).
+Set new baud rate (both TX and RX).
 .It Ar d
-Set new character delay.
+Set new character transmission delay.
 .It Ar b
-Toggle the backspace key character
+Toggle the backspace key character.
 .It Ar t No | Ar T
 Toggle a translation option (output|input).
 .It Ar c
-Toggle canonical mode
+Toggle canonical mode.
 .It Ar h
-Toggle echo.
+Toggle local echo.
 .It Ar w
 Write a file to the line.
 .It Ar p
@@ -126,13 +120,14 @@ Send a DCD pulse.
 .Sh EXIT STATUS
 .Pp
 .Nm 
-exits 2 if some of the user\-set options were invalid (errors caused by trying to aply unsupported options to hardware, eg., setting unsupported baud, are considered as such) and exits 1 on general errors.
+exits 2 if some of the user\-set options were invalid (errors caused by trying to aply unsupported options to hardware, eg., setting unsupported baud rate, are considered as such) 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
+[EOF]
 $ cat wozmon.out
 00,78,FFFF
 
@@ -144,6 +139,14 @@ FFFF: 00
 
 45: 9A
 
+.Ed
+.Pp
+.Ed
+.Ed
+.Pp
+Write all output to a single file with keyboard input and no terminal output:
+.Bd -literal -offset indent
+$ ust > test.log 2>&1
 .Ed
 .Pp
 .Ed