[groff] 09/35: groff(1): Add "Exit status" section.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 42c2de802928aedd12220838048881a075376e01
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sat Oct 23 12:15:25 2021 +1100

    groff(1): Add "Exit status" section.
    
    Explain how groff's exit status actually works.
    
    I'm temped to left-shift all the 'ret |=' operations in pipeline.c by
    one bit so that exit status 1 is not ambiguous, at least on conventional
    Unix-like systems.  I see no guarantee in POSIX[1] or N2176 (the ISO C17
    final draft[2]) that EXIT_FAILURE is 1.  ¯\_(ツ)_/¯
    
    [1] https://pubs.opengroup.org/onlinepubs/9699919799/functions/exit.html
    [2] https://files.lhmouse.com/standards/ISO%20C%20N2176.pdf
---
 src/roff/groff/groff.1.man | 40 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/src/roff/groff/groff.1.man b/src/roff/groff/groff.1.man
index 00992b0..865f723 100644
--- a/src/roff/groff/groff.1.man
+++ b/src/roff/groff/groff.1.man
@@ -1554,6 +1554,46 @@ the databases.
 .
 .
 .\" ====================================================================
+.SH "Exit status"
+.\" ====================================================================
+.
+.I groff
+exits with a failure status if there was a problem parsing its arguments
+and a successful status if either of the options
+.B \-h
+or
+.B \-\-help
+was specified.
+.
+Otherwise,
+.I groff
+runs a pipeline to process its input;
+if all commands within the pipeline exit successfully,
+.I groff
+does likewise.
+.
+If not,
+.IR groff 's
+exit status encodes a summary of problems encountered,
+setting bit\~0 if a command exited with a failure status,
+bit\~1 if a command was terminated with a signal,
+and bit\~2 if a command could not be executed.
+.
+(Thus,
+if all three misfortunes befell one's pipeline,
+.I groff
+would exit with status 2\[ha]0 + 2\[ha]1 + 2\[ha]2 = 1+2+4 = 7.)
+.
+To troubleshoot pipeline problems,
+you may wish to re-run the
+.I groff
+command with the
+.B \-V
+option and break the reported pipeline down into separate stages,
+inspecting the exit status and any diagnostic messages of each command.
+.
+.
+.\" ====================================================================
 .SH Environment
 .\" ====================================================================
 .