docs/84956: [patch] intro(5) manpage doesn't mention API coverage

[Giorgos Keramidas]

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?
 
 Exactly.
 
 > 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
 pages down.
 
 > But intro(5) should not reference only intro(1) and intro(8).
 
 Sounds reasonable.
 
 Thanks,
 Giorgos