Date: Wed, 3 Jan 2001 14:29:26 -0500 From: Tim McMillen <timcm@umich.edu> To: freebsd-doc@freebsd.org Subject: various man page additions Message-ID: <0101031429260A.00440@tim.elnsng1.mi.home.com>
next in thread | raw e-mail | index | archive | help
Hi, I'm new to the doc project and want to help. I'm currently reading
the doc-proj primer, but I'm swamped. I'll get there, but please
permit this message as a description of the fix. If I'm way off base
in sending this message this way, let me know.
When talking to Greg Lehey about some vinum issues he noted that "Vinum
*is* vinum(4)" but I noticed man vinum pointed to vinum(8)
I looked in man man and it does not say what the default search order
is. He found it.
>> man man does not seem to say what the default is.
> Agreed. That should be fixed. It appears that the sequence is (from
> /usr/src/gnu/usr.bin/man/lib/config.h_dist):
>
> static char *std_sections[] =
> {
> "1", "1aout", "8", "2", "3", "n", "4", "5", "6", "7", "9", "l",
> NULL
> };
>
> This doesn't match FreeBSD's man section naming, so we should probably
> fix that first.
More from the discussion:
>> As an aside, I also think man man should list a number of
>> things about how to list the commands in a given section and get the
>> command summaries. The whatis manpage doesn't say either.
> Why not try fixing those pages and submitting the patches? If nobody
> else wants to look at it, I will.
As I said I don't know how to do this properly yet. I'm learning.
Part of the problem is I don't know the conventions for what is and
isn't included in a manpage.
So some proposed fixes.
--have man(1) state what the default manpage search order is.
a decent spot is: (but it is not perfectly correct, it needs help)
old:
You may also specify the order to search the sections for entries and
which preprocessors to run on the source files via command line options
or environment variables. If enabled by the system administrator,
formatted man pages will also be compressed with the `/usr/bin/gzip -c'
command to save space.
new:
You may also specify the order to search the sections for entries and
which preprocessors to run on the source files via command line options
or environment variables. The default search order is sections "1",
"1aout", "8", "2", "3", "n", "4", "5", "6", "7", "9", "l". If enabled
by the system administrator, formatted man pages will also be
compressed with the `/usr/bin/gzip -c' command to save space.
--man(1) should state what the different man section names are.
And perhaps should include the intro pages in the SEE ALSO section. As
intro(1) does, though it skips 1aout since it doesn't have an intro
page.
--in either man(1) or whatis(1) or probably both, should have something
like:
Ex. To get a list of the commands in a given section try
whatis 1 or whatis 8
the output can be somewhat ugly, but useful. A better command would be
well, better.
This should probably also be in each intro page.
--help should be a basic command and should be mentioned in the default
motd.
it could display a quick tutorial on how to use the basic resources
available. The FAQ, handbook and manpages. And how to install the
documentation locally if they don't have net access set up yet. I will
write the text and facilitate getting it made into an executeble. I
could just write it as a shell script, but there may be better ways.
I will post what I write on my website for comments.
Thank you for your time,
Tim
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?0101031429260A.00440>