Date: Tue, 16 Aug 2005 19:20:10 GMT From: Giorgos Keramidas <keramida@freebsd.org> To: freebsd-doc@FreeBSD.org Subject: Re: docs/84956: [patch] intro(5) manpage doesn't mention API coverage Message-ID: <200508161920.j7GJKArw080830@freefall.freebsd.org>
next in thread | raw e-mail | index | archive | help
The following reply was made to PR docs/84956; it has been noted by GNATS. From: Giorgos Keramidas <keramida@freebsd.org> To: "Gary W. Swearingen" <garys@opusnet.com> Cc: bug-followup@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@opusnet.com> wrote: > Giorgos Keramidas <keramida@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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200508161920.j7GJKArw080830>