man pages

[Little Girl]

Hey there,

Lars Noodén wrote:

> Little Girl wrote:
 
> > 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.

Not a problem. It gave me something to learn, which is a good thing.
(:

> 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.

Very nice! Thanks! I've wondered how you get to those numbered pages
for years and never looked into it. This is now added to my
ever-growing cheat sheet on How To Do Things. (:
 
> 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.

The categories look like a great method of organization for the
different types of information.

> 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.

Agreed. The reason man pages are vital is that not every machine is
on the internet, and that man page may be all a user has, so the
more sense it makes, the better.

> Back to the question,

> to hold up two examples of how manual pages should ideally be, see
> ssh(1) and ssh_config(5)

Very thorough and detailed, and I have no doubt I could get help from
these if I needed it.

> 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.

Good heavens!

> Some pages seem to be missing all together, tar(1) points to tar(5)
> but the latter does not even exist.

Interesting. In Kubuntu Precise I have tar(1) and not tar(5), so
maybe you have a bug in whatever release you're using.
 
> 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.

And that's been sorted nicely by Elizabeth and Stephen, so we should
be all set to at least give it a try. (:

-- 
Little Girl

There is no spoon.