Issue #1204 has been updated by micah -. Status changed from Accepted to Needs design decision Assignee deleted (micah -)
I'm not sure why this ticket was assigned to me, so I am unassigning it. The man pages are still a wreck, the reason is because they are being auto-translated from some other markup that utterly fails at the translation process. I know that a while back people were thinking the right way forward would be to fix that translator so it output good man pages. In my humble opinion, now that it has been over 2 years since I filed this ticket, is that the man pages should just be fixed and shipped as man pages. I know you dont want to have to update the documentation in multiple places, because that is annoying and the ideal scenario would be to have this translator work properly so that you can do this. However, I think the axiom "dont let the perfect be the enemy of the good" applies here. Lets have functional man pages, even if it is a little bit of annoying work because things are duplicated. Maybe that will serve as motivation to fix the translator. :) ---------------------------------------- Bug #1204: Man page issues https://projects.puppetlabs.com/issues/1204 Author: micah - Status: Needs design decision Priority: Normal Assignee: 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.
