"Fossies" - the Fresh Open Source Software Archive 
Member "brlcad-7.32.4/misc/auto-man-page/README.auto-man-page-handling" (29 Jul 2021, 6091 Bytes) of package /linux/misc/brlcad-7.32.4.tar.bz2:
As a special service "Fossies" has tried to format the requested text file into HTML format (style:
standard) with prefixed line numbers.
Alternatively you can here
view or
download the uninterpreted source code file.
1 Rules:
2 =====
3
4 + Provide a version-controlled list of all bin programs to be
5 processed for the "auto-man" documentation feature:
6
7 auto-man-progs.txt
8
9 + In the auto-man list each bin program name will be listed followed
10 on the same line by the source file which provides it, e.g.,
11
12 burst ./src/burst/burst.c
13
14 + Each bin source file must have one instance each of the following
15 string variables:
16
17 const char usage[] = "...."; /* mandatory: used for the SYNOPSIS
18 section of the man page */
19 const char optstring[] = ""; /* mandatory for use with bu_getopt
20 (if it is used) */
21
22 Note the strings must either (1) be fully contained on one line or
23 (2) adhere to the following format:
24
25 const char usage[] =
26 "Usage: %s ... first line...\n"
27 " ... second line...\n"
28 "... more lines if needed\n";
29
30 The ending semicolon may follow on a line by itself.
31
32 There must be no embedded newlines nor may the end-of-line escape be
33 used. An ending newline is required for each line.
34
35 There must be nothing preceding the variable on its
36 beginning line (except a 'static' qualifier is allowed).
37
38 The program name may be manually entered or one string format
39 specification ('%s') entered for print statement use in the program.
40
41 Valid examples:
42 --------------
43
44 static const char usage[] = "Usage: %s input.g\n";
45
46 const char usage[] =
47 "Usage: fbserv port_num\n"
48 " (for a stand-alone daemon)\n"
49 ;
50
51 Invalid example:
52 ---------------
53
54 const char usage[] = "\
55 Usage: %s port_num\n\
56 (for a stand-alone daemon)\n\
57 ";
58
59 + Other man page inputs come from one or more specially-formatted
60 ordinary C-style comment blocks (Doxygen-style comments beginning
61 with '/**' or '/*!' are completely ignored).
62
63 Each such block is divided into one or more parts beginning with a
64 unique keyword ending with a colon ('partname:'; but see 'opt:' later)
65 which identifies a section to appear in the man page.
66
67 The block must begin with the following format or it will be ignored:
68
69 - Immediately following the opening '/*' must be one or more white
70 space characters (newlines allowed) followed by one keyword
71 followed by on or more white-space characters followed by its
72 description (its 'value'). Note the description must exist (i.e.,
73 its value must be at least one printable character).
74
75 - A blank line inside a part description results in a new paragraph.
76
77 - The part name must be lower-case alpha characters, and it may have
78 underscores. The part name will be translated into upper case and
79 underscores into spaces in the man page.
80
81 - Following the mandatory first part may be more unique parts.
82
83 - A description ends when the next part keyword is found or the the
84 comment block ends.
85
86 - Embedded asterisks surrounded by white space are ignored (to allow
87 for the decorated comment style).
88
89 - All the part descriptions may use valid DocBook code.
90
91 Some part names are mandatory and some parts have default values.
92 All part names must be unique except the 'opt:' part which may
93 appear as many times as there are options. Note option names follow
94 the 'opt:' keyword and they must be unique. Furthermore, the list
95 of options in the comment blocks must exactly match the option in
96 the optstring if it appears in the file.
97
98 Each option (keyword 'opt:') must be described in one of three
99 possible formats:
100
101 opt: -c [N] description of this option and its optional arg N
102 opt: -a <Z> description of this option and its mandatory arg Z
103 opt: -d description of this option which has no args
104
105 'opt:' note: there must be no spaces inside the brackets ([] and
106 <>). If spaces are needed, use underscores which will then be
107 translated to spaces in the man page.
108
109 Following is an example of such a comment block (partially
110 decorated):
111
112 /*
113 * section1: description
114 *
115 * more description but this follows a blank line so it begins a
116 new para
117
118 another_section: description ...
119
120 ...
121
122 opt: optiona description
123
124 another para for optiona
125
126 opt: optiond ...
127
128 */
129
130 + Mandatory parts:
131
132 purpose: ...brief description for NAME section...
133
134 description: some words, should give user a good idea of how and why
135 to use the program
136
137 ...this will appear in the DESCRIPTION section
138
139 opt: option
140
141 ... one for each option (if any), all will be put in an OPTIONS
142 section
143
144 + Default parts (user may override by explicitly providing them):
145
146 copyright: YYYY
147
148 where YYYY is the beginning copyright year (default is 1984).
149
150 diagnostics:
151
152 default: Error messages are intended to be self-explanatory.
153
154 authors:
155
156 default: BRL-CAD Team
157
158 bug_reports:
159
160 default: Reports of bugs or problems should be submitted via
161 electronic mail to <devs@brlcad.org>.
162
163 + Optional but desirable parts:
164
165 see_also:
166
167 ...list of man pages only (with sections),
168 semicolon- or white-space-separated, no other embellishments...
169
170 other_refs:
171
172 ...list of other references, if any,
173 semicolon-separated, no other embellishments...
174
175 ...both lists will go in the SEE ALSO section...
176
177 Processing:
178 ==========
179
180 A C++ program (version controlled) will be used to parse the source
181 files (defined in the file 'auto-man-progs.txt') and, after successful
182 parsing, a complete docbook file in man format will be written to file
183 "progname.xml" in directory:
184
185 ./doc/docbook/system/man1/en/
186
187 Assumptions:
188 ===========
189
190 + C++-style comments are ignored unless they are inside a C-style
191 comment in which case they are treated as ordinary text.
192
193 + No more than one C-style comment or partial comment is on a line.
194
195 + Mandatory string variables ('usage' and 'optstring') begin and
196 end on a line with no other C/C++ objects.
197
198 Working example:
199 ===============
200
201 See file "${BRLCAD_SOURCE_ROOT}/src/util/fix_polysolids.c" for an
202 example of some of the features described above.