Manual Reference Pages  - genmanstub (1)


NAME

genmanstub - generates man page stubs from the contents of the specified shell script(s).

CONTENTS

Arguments
Author
Bugs
Calls
Description
Diagnostics
Documented Version
Exit Status
Hints
Options
Output
Output Used By
Permissions
Rcs Information
Rcs.sh Version
Restrictions
See Also
Synopsis
Warning(s)

DOCUMENTED VERSION

1.21 - 2012/09/04 18:41:25

SYNOPSIS

genmanstub [-d] [-h] [-o] [-t] [-x]* [-X]* [-Z n]* {scriptfile}+

DESCRIPTION

A script to generate a man page stub from the contents of a shell script.
It depends on a standardized series of comments at the beginning of
the script being processed as well as some details from $USAGE.
Note that the script name includes "stub" to suggest it is the starting point
for a man page and that the generated man page should be manually updated for
completeness (or correctness due to bugs in this script or formatting that isn’t
done properly by this script; and hence the need for the -o flag before overwriting
the file), however, I’ve found that all the sections in the comment header are
sufficient for a complete man page and also the easiest way to mantain the man pages
since only individual scripts need to be updated, and then the man page regenerated
as opposed to maintaining both the script and the man page.

ARGUMENTS

    {scriptfilel} one or more script filenames to generate manpage stubs for

OPTIONS

-d diff script output in a temp file with an existing manpage file
-h after man pages is generated, create an HTML version using manserver
-o overwrite existing manpage file (default=no overwrite)
-t enable trace file output to /tmp
-x does ’set -x’ (may be used in functions and external script calls) (see DIAGNOSTICS below)
-X sets debugging level--the number of times -X is specified (see DIAGNOSTICS below)
-Z n specify debugging flag ’n’ (see DIAGNOSTICS below)

OUTPUT

    An nroff man page for each input file is written to $ejadir/manpages/man1/<scriptname>.1.
    If the -h flag is specified, manserver is called and it writes the HTML file to /Library/WebServer/Documents/man/<scriptname>.1.html.

OUTPUT USED BY

    The man command to view the generated documentation.
    The script $ejadir/bin/manserver to generate HTML versions of the manpages.

HINTS

As noted in RESTRICTIONS certain nroff tags are known to be supported in the comment header.
1) \fB - bold (tty-not visible, printed-overstrike, HTML-bold)
2) \fI - italic (tty-underline, printed-underline, HTML-italic)
3) \fP - plain (shift out of bold or italic)

RESTRICTIONS

1) This script depends on a bunch of specific formatting. In particular, the comment header must
have #space to mark section headings and non-section headings must not have a space as the character
after the #. Since the comment header has evolved over time, it doesn’t handle old information very
well, so it is probably better to modify the script being processed than to add special handling
to this script.
2) There are a couple of specific instances where nroff commands can be included in
the comment header, but not very many.
3) Since this script can be run on itself, care must be taken to ensure comments that document the
script don’t also match anything in the comment header. A useful means is to use "##" instead
"#" for comments in this script that match section headings.

BUGS

1) The code scanning section of WARNING CODES and ERROR CODES will fail if the filename being processed
contain a separator character. There may be other instances where a space character in a filename isn’t handle correctly.
2) The line breaks in the comment header are retained, but this can result in ugly output. Specifically
most text sections keep the existing line breaks by adding potentially unnecessary break codes. This means
that nroff and/or HTML can smartly wrap the text. If the window is narrow, line wrapping will occur randomly
interspersed with the forced line breaks. However, some times (e.g. base64decode) the formatting is intentional
and shouldn’t be messed with. Not sure how to fix this. Perhaps remove line breaks if there are no leading
tabs (i.e. more than the 1 usual one).

Also, processing of RESTRICTIONS (and others) have substr(x,3) instead of substr(x,2) to delete a leading tab, but other sections do not.
Keeping the tab allows nroff to wrap long lines, but indent the first element due to the tab.
3) Parsing the USAGE string fails to handle multi-line entries. The extra lines after the first are dumped into the ARGUMENTS section.
* perhaps the indent level can be tracked
* also, each occurance of $basename... should be a separate synopsis entry
4) The code that figures out the real name of a symbolic link can’t handles spaces in either name.

RCS.SH VERSION

00014

RCS INFORMATION

$Id: genmanstub,v 1.21 2012/09/04 18:41:25 earneson Exp $
$Author: earneson $
$Date: 2012/09/04 18:41:25 $
$Revision: 1.21 $
$Source: /Users/cvs/scripts/all/Users/earneson/bin/genmanstub,v $
$State: Exp $

PERMISSIONS

rwxr-xr-x userUID staff

WARNING(S)

40 - The localize script could not be found. Global machine settings can not be set.
41 - Man page stub ($mandir/$f) already exists.
        Use -o option to overwrite it, or remove it manually.
        Use -d to diff script output of this script with the existing manpage file, then rerun script with -o if desired.
42 - Can not read the file >$f<. Continuing with the next file (if specified).
43 - A -d flag (diff) was specified but there is no existing man page file ($defoutfile). Continuing with the next file (if specified).
44 - The argument >$f< is a directory. Continuing with the next file (if specified).

EXIT STATUS

51 - An unknown option was passed to the script, or syntax of the parameters is wrong.
51 - Unknown option >$errflag<
52 - You must specify at least one shell script file to process.
53 - Can not find a writable man1 directory to write the manpage file(s) to.
54 - Can not find the manserver command for converting the man page to HTML.
56 - The USAGE was requested using -z or -?.

CALLS

awk (to do the heaving lifting), perl
$ejadir/bin/manserver (to generate an HTML version from the nroff version)

SEE ALSO

dumpcommentheadersection(1)

AUTHOR

Edwin Arneson

DIAGNOSTICS

-X output "while getopts" processing;
 
-XX ditto
 
-XXX ditto plus prints the fields associated with some arrays.
 
-XXXX ditto plus prints all the input lines to the second awk command (not including some getline commands that process specific sections).
  The main entries are marked DEBUG4>>>.
Some subsidiary getline entries are marked DEBUG4>>> and some are marked DEBUG4>tag>.
-Z10.0 call fflush a bunch of times in the second awk command to display tracing/debugging information to allow tracking down awk hanging.
 


\\$4  genmanstub (1) EJA UTILITY
Generated by manServer 1.07 from genmanstub.1 using man macros. With tweaks by Edwin Arneson.