man pages - was: wiki vs documentation

[Lars Noodén]

On 09/21/2013 12:48 AM, Little Girl wrote:
> Hey there,
> 
> Lars Noodén wrote:
>> Little Girl wrote:
> 
>>> Are there guidelines for how they should be constructed?
>  
>> The man pages use a very simple markup but are significantly harder
>> to get at than a wiki.  See man(7) for the format and document
>> structure.
> 
> Thanks! I found that here:
> 
> http://manpages.ubuntu.com/manpages/precise/man7/
> 
> I also found it by typing this in a terminal:
> 
> man man-pages
> 
> It took me a little while to figure that last one out. (:

Sorry.  I should have mentioned that.  I'm too used to it.
man(7) would be the equivalent to

	man 7 man

If you leave the number off, it takes the first one even if there are
others.

The number 1 - 8 is the category for the page.  So some pages can have
pages in several categories.  passwd, for example, has one page for the
program and one for the file format.   So these would be passwd(1) and
passwd(5), for the program and the password data file, respectively:

	man 1 passwd
	man 5 passwd

These pages should be simple, clear and concise.  They are the first
line of support for everyone except beginners.  And even beginners
should be able look at one and see the value even if they move on to a
forum or mailing list for closer guidance.

Back to the question,

to hold up two examples of how manual pages should ideally be, see
ssh(1) and ssh_config(5)  To hold up one that could use a lot of work,
see thunderbird(1), which doesn't even cover all the runtime parameters.
 In fact, the Thunderbird manual page includes only a single one option,
the dozens of others are missing.  Some pages seem to be missing all
together, tar(1) points to tar(5) but the latter does not even exist.

The manual pages really only need to get written once.  When functions
are added or removed from the program, updating the manual page is
simple.  It is just a marked up text file.  The difficulty here is
mostly administrative, getting coordinated with the upstream project.

Regards,
/Lars