Hi Chris, On Fri, Jun 24, 2011 at 10:10 PM, Křištof Želechovski <giecrilj@xxxxxxxxxxxx> wrote: > * The code sample given for the NAME section is incomplete because the actual content sample is not given. > * Additionally, the description assumes that the item described is a command, which need not be the case. > * The command makewhatis is not present on my system; the documented tool to create the whatis database is called mandb. > * The reference to man(7) in man-pages(7) with respect to the NAME section should be replaced by lexgrog(1), since it is the authoritative page for whatis. > * The description on .SH NAME in man(7) should either copy the relevant paragraph of lexgrog(1) or refer to it. > > Please fix, > Chris > > Is: > > The only mandatory heading is NAME, which should be the first section and be fol‐ > lowed on the next line by a one line description of the program: > > .SH NAME > > It is extremely important that this format is followed, and that there is a back‐ > slash before the single dash which follows the command name. This syntax is used > by the makewhatis(8) program to create a database of short command descriptions > for the whatis(1) and apropos(1) commands. > > Let: > > The only mandatory heading is NAME, which should be the first section and be fol‐ > lowed on the next line by a one line description of the program: > > .SH NAME > item \- description > > It is extremely important that this format is followed, and that there is a back‐ > slash before the single dash which follows the item name. This syntax is used > by the mandb(8) program to create a database of short command descriptions > for the whatis(1) and apropos(1) commands. Thanks for the detailed report. One thing that would have made it even better is a patch, since trying to scan for diffs in the above text is error-prone. I applied the patch below for man-pages-3.36. Cheers, Michael --- a/man7/man.7 +++ b/man7/man.7 @@ -102,22 +102,26 @@ followed by the heading name. .\" then place the heading in double quotes. The only mandatory heading is NAME, which should be the first section and -be followed on the next line by a one line description of the program: +be followed on the next line by a one-line description of the program: .RS .sp \&.SH NAME .br +item \\- description .sp .RE It is extremely important that this format is followed, and that there is a -backslash before the single dash which follows the command name. +backslash before the single dash which follows the item name. This syntax is used by the -.BR makewhatis (8) -program to create a database of short command descriptions for the +.BR mandb (8) +program to create a database of short descriptions for the .BR whatis (1) and .BR apropos (1) commands. +(See +.BR lexgrog (1) +for further details on the syntax of the NAME section.) .PP For a list of other sections that might appear in a manual page, see .BR man-pages (7). @@ -551,6 +555,7 @@ is not implemented. .SH "SEE ALSO" .BR apropos (1), .BR groff (1), +.BR lexgrog (1), .BR man (1), .BR man2html (1), .BR whatis (1), -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Author of "The Linux Programming Interface"; http://man7.org/tlpi/ -- To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
