Updated manual and regenerated docs

picocom.1

@@ -1,7 +1,8 @@
 .\" Automatically generated by Pandoc 1.16.0.2
 .\"
-.TH "PICOCOM" "1" "2017-12-20" "Picocom 2.3a" "User Commands"
-.hy
+.ad l
+.TH "PICOCOM" "1" "2017-12-21" "Picocom 3.0a" "User Commands"
+.nh \" Turn off hyphenation by default.
 .SH NAME
 .PP
 picocom \- minimal dumb\-terminal emulation program
@@ -62,15 +63,24 @@ Exit the program.
 If the \f[B]\-\-noreset\f[] option is \f[I]not\f[] given, then the
 serial port is reset to its original settings before exiting, and the
 modem control lines (typically DTR and RTS) are cleared (lowered)
-signaling a modem hangup; if \f[B]\-\-noreset\f[] is given, then the
-serial port settings are not reset, and the modem control lines remain
-unaffected.
+signaling a modem hangup.
+If \f[B]\-\-noreset\f[] is given (and \f[B]\-\-hangup\f[] is not), then
+the serial port settings are not reset, and the modem control lines
+remain unaffected.
+If both \f[B]\-\-noreset\f[] and \f[B]\-\-hangup\f[] are given, then the
+serial port settings are not reset, but the modem\-control lines
+\f[I]are\f[] cleared.
 .RS
 .RE
 .TP
 .B \f[B]C\-q\f[]
-Quit the program \f[I]without\f[] resetting the serial port, exactly as
+Quit the program \f[I]without\f[] resetting the serial port to its
+original settings.
+Terminating with the Quit command, picocom behaves \f[I]exactly\f[] as
 if the \f[B]\-\-noreset\f[] option was given.
+The serial port is \f[I]not\f[] reset to its original settings, and the
+modem control lines remain unaffected or are cleared, subject to the
+\f[B]\-\-hangup\f[] option.
 .RS
 .RE
 .TP
@@ -246,9 +256,9 @@ See also the \f[B]\-\-no\-escape\f[] option.
 .TP
 .B \f[B]\-\-no\-escape\f[] | \f[B]\-n\f[]
 Disables the escape character.
-Picocom will never enter command\-mode if this option is enabled.
-To exit picocom, you must either close its standard input, or send it
-the TERM or INT signal.
+Picocom will never enter command\-mode if this option is given.
+To exit picocom, in this case, you must either close its standard input,
+or send it the TERM or INT signal.
 (Default: Disabled).
 .RS
 .RE
@@ -263,15 +273,15 @@ configuration (see \f[B]\-\-emap\f[] option).
 .RE
 .TP
 .B \f[B]\-\-noinit\f[] | \f[B]\-i\f[]
-If given, picocom will not initialize, configure, or otherwise meddle
-with the serial port at start\-up.
+If given, picocom will not initialize, configure, or otherwise mess with
+the serial port at start\-up.
 It will just open it.
 This is useful, for example, for connecting picocom to
 already\-connected modems, or already configured ports without
 terminating the connection, or altering their settings.
 If required, serial port parameters can then be adjusted at run\-time by
 commands.
-See also the \f[B]\-\-noreset\f[] option.
+See also the \f[B]\-\-noreset\f[] and \f[B]\-\-hangup\f[] options.
 (Default: Disabled)
 .RS
 .RE
@@ -280,29 +290,43 @@ See also the \f[B]\-\-noreset\f[] option.
 If given, picocom will not reset the serial port when exiting.
 It will just close the respective file descriptor and do nothing more.
 The serial port settings will \f[I]not\f[] be restored to their original
-values and the modem\-control lines will \f[I]not\f[] be affected.
+values and, unless the \f[B]\-\-hangup\f[] option is also given, the
+modem\-control lines will \f[I]not\f[] be affected.
 This is useful, for example, for leaving modems connected when exiting
 picocom.
 Regardless whether the \f[B]\-\-noreset\f[] option is given, the user
 can exit picocom using the "Quit" command (instead of "Exit"), which
-never resets the serial port (i.e makes picocom behave exactly as if
-\f[B]\-\-noreset\f[] was given).
-If \f[B]\-\-noreset\f[] is given then "Quit" and "Exit" behave
-essentially the same.
+makes picocom behave \f[I]exactly\f[] as if \f[B]\-\-noreset\f[] was
+given.
+See also the \f[B]\-\-hangup\f[] option.
 (Default: Disabled)
 .RS
 .PP
 NOTICE: Picocom will always set the HUPCL control bit of the serial
-port, according to the \f[B]\-\-noreset\f[] option.
-If \f[B]\-\-noreset\f[] is given, then HUPCL for the port is cleared,
-and will remain so after exiting picocom.
-If \f[B]\-\-noreset\f[] is \f[I]not\f[] given, then HUPCL is set for the
-port, and will remain so after exiting picocom.
+port, according to the \f[B]\-\-noreset\f[] and \f[B]\-\-hangup\f[]
+options.
+If \f[B]\-\-noreset\f[] is given and \f[B]\-\-hangup\f[] is not, then
+HUPCL for the port is cleared and will remain so after exiting picocom.
+If \f[B]\-\-noreset\f[] is \f[I]not\f[] given, or if both
+\f[B]\-\-noreset\f[] and \f[B]\-\-hangup\f[] are given, then HUPCL is
+set for the port, and will remain so after exiting picocom.
 This is true, regardless of the way picocom terminates (command, read
 zero\-bytes from standard input, killed by signal, fatal error, etc),
 and regardless of the \f[B]\-\-noinit\f[] option.
 .RE
 .TP
+.B \f[B]\-\-hangup\f[] | \f[B]\-u\f[]
+If given together with \f[B]\-\-noreset\f[], picocom will not reset the
+serial port to it\[aq]s original settings on exit, but it \f[I]will\f[]
+clear the modem control lines (typically DTR and RTS) to signal a modem
+hangup.
+Without the \f[B]\-\-noreset\f[] option (explicitly given, or implied by
+extiting with the "Quit" command) \f[B]\-\-hangup\f[] has no effect
+(without \f[B]\-\-noreset\f[] picocom always clears the modem control
+lines on exit, anyway).
+.RS
+.RE
+.TP
 .B \f[B]\-\-nolock\f[] | \f[B]\-l\f[]
 If given, picocom will \f[I]not\f[] attempt to lock the serial port
 before opening it.
@@ -393,11 +417,11 @@ Example:
 .IP
 .nf
 \f[C]
-picocom\ \-t\ "$(echo\ \-e\ \[aq]AAATZ\\r\\n\[aq])"\ /dev/ttyS0
+picocom\ \-t\ "$(echo\ \-ne\ \[aq]AAATZ\\r\\n\[aq])"\ /dev/ttyS0
 \f[]
 .fi
 .PP
-Note, that the init string is not sent if \f[B]\-\-noinit\f[] is set.
+Note, that the init string is not sent if \f[B]\-\-noinit\f[] is given.
 (Default: empty).
 .RE
 .TP
@@ -425,12 +449,13 @@ serial port, AND there is nothing to write (send) to the serial port,
 AND nothing is read from the standard input (terminal).
 If \f[B]\-\-exit\-after\f[] is set to zero, then picocom exits after
 opening and configuring the serial port, after sending the init string
-(if any, see option \f[B]\-\-initstring\f[]), and imediatelly when it
+(if any, see option \f[B]\-\-initstring\f[]) and imediatelly when it
 becomes idle.
 When exiting after being idle, picocom drains the O/S serial port ouput
 buffer (i.e.
 waits for data already written to the port to be transmitted) and
-observes the \f[B]\-\-noreset\f[] setting as usual.
+observes the \f[B]\-\-noreset\f[] and \f[B]\-\-hangup\f[] options as
+usual.
 (Default: not set).
 .RS
 .PP
@@ -449,15 +474,15 @@ its output queue have been transmitted.
 Exit picocom immediatelly after opening and configuring the serial port.
 Do \f[I]not\f[] read \f[I]anything\f[] from the standard input or from
 the serial port.
-When exiting the \f[B]\-\-noreset\f[] option is observed as usual.
-With \f[B]\-\-exit\f[] and \f[B]\-\-noreset\f[] picocom can be used as a
-very crude replacement of \f[B]stty(1)\f[].
+When exiting the \f[B]\-\-noreset\f[] and \f[B]\-\-hangup\f[] options
+are observed as usual.
+With \f[B]\-\-exit\f[] and \f[B]\-\-noreset\f[] (and possibly
+\f[B]\-\-hangup\f[]) picocom can be used as a very crude replacement of
+\f[B]stty(1)\f[].
 If an init string is also given (see \f[B]\-\-initstring\f[] option),
 picocom exits imediatelly after sending (writing) the init string to the
-serial port.
-In this case, before exiting, picocom drains the O/S serial port output
-buffer (i.e.
-waits for data written to the port to be transmitted).
+serial port and draining the O/S serial port output buffer (i.e.
+waiting for data written to the port to be transmitted).
 Again, nothing is read from the standard input, or from the serial port.
 The \f[B]\-\-exit\f[] option, overrides the \f[B]\-\-exit\-after\f[]
 option.
@@ -644,8 +669,8 @@ Replace every CR character with CR and LF when echoing to the terminal
 (if local\-echo is enabled).
 .SH EXITING PICOCOM
 .PP
-This section summarizes the conditions under which picocom terminates
-its operation and what happens on each such condition:
+This section summarizes the conditions in which picocom terminates its
+operation and what happens in each such condition:
 .IP \[bu] 2
 The exit command is seen in the standard input.
 That is, the escape character is seen (default \f[B]C\-a\f[]), followed
@@ -654,13 +679,10 @@ In this case: The contents of the output queue (data read from the
 standard input, but not yet written to the port) as well as the contents
 of the O/S serial port output buffer (data already written to the port,
 but not yet transmitted) are discarded (flushed).
-Then, if the \f[B]\-\-noreset\f[] option is \f[I]not\f[] given, the
-serial port is reset to the settings it had when picocom started, and
-the modem control lines (typically DTR and RTS) are cleared (lowered),
-signaling a modem hangup.
-Picocom then exits.
-If \f[B]\-\-noreset\f[] is given, then picocom exits without reseting
-the serial port and without affecting the modem control lines.
+Then the serial port is reset to it\[aq]s original settings, and the
+modem\-control lines are cleared signaling a modem reset, subject to the
+\f[B]\-\-noreset\f[] and the \f[B]\-\-hangup\f[] options.
+After that picocom exits with a success status.
 .IP \[bu] 2
 The quit command is seen in the standard input.
 That is, the escape character is seen (default \f[B]C\-a\f[]), followed
@@ -672,40 +694,40 @@ given (regardless if it actualy is, or not).
 The \f[B]\-\-exit\f[] option is given.
 See the documentation of this option for a description of what exactly
 happens in this case.
+Picocom exits with a success exit status.
 .IP \[bu] 2
 The \f[B]\-\-exit\-after\f[] option is given.
 See the documentation of this option for a description of what exactly
 happens in this case.
+Picocom exits with a success exit status.
 .IP \[bu] 2
 Zero bytes are read from the standard input.
 This usually means that whatever was connected to picocom\[aq]s standard
-input has been closed or, if a file was connected, that picocom has read
+input has been closed or, if a file was connected, then picocom has read
 up to the end of the file.
 In this case, if the \f[B]\-\-exit\-after\f[] option is \f[I]not\f[]
 given, picocom stops reading from the standard input, and keeps
 operating normally (i.e.
-writing to, and reading from, the serial port) until its output queue is
-emptied.
+writing to, and reading from, the serial port) until its output queue
+empties.
 When this happens, picocom waits for the O/S serial port output buffer
-to drain and then (subject to the \f[B]\-\-noreset\f[] option) resets
-the serial port to it\[aq]s initial settings, clears the modem\-control
-lines, and exits.
+to drain and then (subject to the \f[B]\-\-noreset\f[] and
+\f[B]\-\-hangup\f[] options) resets the serial port to it\[aq]s initial
+settings, clears the modem\-control lines, and exits.
 If the \f[B]\-\-exit\-after\f[] option is given then, again, picocom
 stops reading from the standard input and continues operating normally
 but, in this case, it does so until it becomes idle for the specified
-amount of time.
-It then waits for the O/S serial port output buffer to drain and exits,
-observing the \f[B]\-\-noreset\f[] option as usual.
+amount of time, before exiting.
+Picocom exits with a success exit status.
 .IP \[bu] 2
-Picocom is killed by the TERM or INT signal.
+Picocom is killed by the TERM or INT signal, or an unrecoverable error
+occurs.
 In this case picocom behaves as if it had received the exit command,
 that is: The contents of the output queue and the contents of the O/S
 serial port output buffer are discarded (flushed).
-Then, if the \f[B]\-\-noreset\f[] option is \f[I]not\f[] given, the
-serial port is reset to the settings it had when picocom started, the
-modem control lines are cleared, and picocom exits.
-If \f[B]\-\-noreset\f[] is given, then picocom exits without reseting
-the serial port or affecting the modem control lines.
+Then, subject to the \f[B]\-\-noreset\f[] and \f[B]\-\-hangup\f[]
+options, the serial port is reset to its original settings, the modem
+control lines are cleared, and picocom exits with a failure status.
 .SH AUTHOR
 .PP
 Written by Nick Patavalis <npat@efault.net>