#1204: Man page issues
---------------------------+------------------------------------------------
Reporter: micah | Owner: community
Type: defect | Status: new
Priority: normal | Component: documentation
Version: 0.24.4 | Severity: normal
Keywords: man groff reST | Stage: Unreviewed
Patch: None | Complexity: Unknown
---------------------------+------------------------------------------------
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:
{{{
.SH NAME
\-
.\" Man page generated from reStructeredText.
.SH SYNOPSIS
}}}
A traditional man page has this:
{{{
.SH NAME
ls \- list directory contents
.SH SYNOPSIS
}}}
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:
{{{
LS(1) User Commands
LS(1)
}}}
This comes from the .TH header in the raw groff:
{{{
.TH LS "1" "April 2008" "GNU coreutils 6.10" "User Commands"
}}}
The puppet man pages have headers like this:
{{{
()
()
}}}
Thats because their .TH headers look like this:
{{{
.TH "" "" ""
}}}
All the puppet man pages have this problem.
--
Ticket URL: <http://reductivelabs.com/trac/puppet/ticket/1204>
puppet <http://reductivelabs.com>
Puppet - Portable System Automation
--~--~---------~--~----~------------~-------~--~----~
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
-~----------~----~----~----~------~----~------~--~---
