Issue #1204 has been updated by Nigel Kersten. Status changed from Needs design decision to Accepted Assignee set to Nigel Kersten
I concur Micah. Man pages are important. If we can't get the translator fixed, we have to deal with manual maintenance until it is. ---------------------------------------- Bug #1204: Man page issues https://projects.puppetlabs.com/issues/1204 Author: micah - Status: Accepted Priority: Normal Assignee: Nigel Kersten Category: documentation Target version: Patch: None Affected Puppet version: 0.25.4 Keywords: Branch: 1. bad whatis entry and mangled 'NAME' section Each manual page should start with a @NAME' section, which lists the name and a brief description of the page seperated by '\-'. These sections are parsed by @mandb' and stored in a database for the use of @apropos' and @whatis', so they must be in a certain format. This manual page apparently uses the wrong format and cannot be parsed by @mandb'. For information on how @NAME' sections should be written see lexgrog(1). All the puppet man pages just have: <pre> .SH NAME \- .\" Man page generated from reStructeredText. .SH SYNOPSIS </pre> A traditional man page has this: <pre> .SH NAME ls \- list directory contents .SH SYNOPSIS </pre> All the puppet man pages have bad whatis and mangled NAME sections 2. binaries not referenced in man pages: Every binary that gets installed in /usr/bin, /usr/sbin, /bin, /sbin or /usr/games should have a proper manual page. If a man page exists for a particular binary, it has to list the program name in the NAMES section, otherwise it doesn't properly reference the man page (various programs such as xman, tkman and others can't handle things at all in this case). The following manpages are not properly referencing binaries: puppetca.8 puppetrun.8 3. syntax errors: Man pages shouldn't provoke warnings or errors from the 'man' program. warnings are often formatting typos, like missing quotes around string arguments to .IP, these usually result in lost of malformed output. The following man page exhibited errors when 'man --warnings' was issued (this enables groff warnings that catch common mistakes, such as putting . or ' characters at the start of a line when they are intended as literal text rather than groff commands. puppet.conf.8 (81: warning: @As' not defined) 4. manpage section mismatch and headers mangled A man page usually should contain a .TH header, specifying the section. If the section in the .TH header doesn't match with the section in the filename, then a section mismatch is generated. The following man page has a section mismatch: puppet.conf.8 (8 != Reference) A typical man page has a header which has the command it is referencing in uppercase, and the manpage section in parethesis with the section header in the middle. For example, the 'ls' command has the following: <pre> LS(1) User Commands LS(1) </pre> This comes from the .TH header in the raw groff: <pre> .TH LS "1" "April 2008" "GNU coreutils 6.10" "User Commands" </pre> The puppet man pages have headers like this: <pre> () () </pre> Thats because their .TH headers look like this: <pre> .TH "" "" "" </pre> All the puppet man pages have this problem. -- You have received this notification because you have either subscribed to it, or are involved in it. To change your notification preferences, please click here: http://projects.puppetlabs.com/my/account -- You received this message because you are subscribed to the Google Groups "Puppet Bugs" group. To post to this group, send email to [email protected]. To unsubscribe from this group, send email to [email protected]. For more options, visit this group at http://groups.google.com/group/puppet-bugs?hl=en.
