docs/84956: [patch] intro(5) manpage doesn't mention API coverage
keramida at freebsd.org
Tue Aug 16 19:20:10 UTC 2005
The following reply was made to PR docs/84956; it has been noted by GNATS.
From: Giorgos Keramidas <keramida at freebsd.org>
To: "Gary W. Swearingen" <garys at opusnet.com>
Cc: bug-followup at freebsd.org
Subject: Re: docs/84956: [patch] intro(5) manpage doesn't mention API coverage
Date: Tue, 16 Aug 2005 22:25:16 +0300
On 2005-08-16 12:09, "Gary W. Swearingen" <garys at opusnet.com> wrote:
> Giorgos Keramidas <keramida at freebsd.org> writes:
> > Ouch! The link(5) and acct(5) manpages seem a bit misplaced. They
> > don't describe a "file format", so they shouldn't be in section (5)
> > IMHO. There are a few other manpages in ``/usr/share/man/man5''
> > that I am not sure about either.
> If you want me to do something, let me know. I could do more research
> and maybe ask ask on one or more lists whether people have objections
> to moving each seemingly-misplaced manpage to a newly-proposed section.
> > My intuition says that anyone who is reading intro(X) manpages should be
> > able to find out about all the other intro(Y) manpages. So, it seems
> > that inter-linking from any intro(X) manpage to the other intro(Y)
> > manpages, where X != Y, seems reasonable.
> Are you saying they should each reference all the others?
> OK by me, but I think it would better to have them all reference only
> intro(1), which already references all the others (except "intro(n)"
> because it does not exist).
I guess that's ok too. I opted for the first option (of adding SEE ALSO
entries for all the intro(x) manpages) because when a reader sees a
reference to intro(1) in one of the others it's not entirely obvious
that there also exist intro(2), intro(3), etc. manpages. Saving one
level of indirection, by pointing to all the intro(x) manpages from all
the rest, makes it more obvious that there exist manpage ``sections''
and that they are those linked from SEE ALSO.
I'm ok with just pointing to intro(1) too though. As long as it's
consistent (i.e. done in all the intro(x) manpages, like you proposed).
> Manpage intro(1) probably also should have a section explaining the
> manual in general. I'll write PRs on the last two problems.
Good idea. It always made me feel a bit weird that to find a list of
all the manpage sections I should go to groff_mdoc(7) and scroll several
> But intro(5) should not reference only intro(1) and intro(8).
More information about the freebsd-doc