The intro(5) manpage doesn't mention that some APIs are documented in section 5 too. E.g., link(5) & acct(5) It also has an seemingly-extraneous reference to intro(8). How-To-Repeat: n/a
On 2005-08-15 08:38, "Gary W. Swearingen" <garys@opusnet.com> wrote: > The intro(5) manpage doesn't mention that some APIs are > documented in section 5 too. E.g., link(5) & acct(5) 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. > --- intro..orig.5 Sun Aug 7 21:58:11 2005 > +++ intro.5 Sun Aug 7 22:07:22 2005 > @@ -38,11 +38,11 @@ > .Nm intro > .Nd "introduction to file formats" > .Sh DESCRIPTION > -This section contains information about file formats. > +This section contains information about file formats > +and some system Application Programming Interfaces (API .h files). > .Sh SEE ALSO > .Xr apropos 1 , > -.Xr intro 1 , > -.Xr intro 8 > +.Xr intro 1 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. - Giorgos
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? 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). Manpage intro(1) probably also should have a section explaining the manual in general. I'll write PRs on the last two problems. But intro(5) should not reference only intro(1) and intro(8).
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
Let's drop the intro(8) problem from this PR, leaving the subject problem. I'll write another PR for expanding all the "SEE ALSO"s. (I'll credit you for the idea. I'm not sure how popular it will be, for example, in intro(4). :) Please let me know if you want the multiple patches in the PR or not. I don't know if you'd rather just edit the files than apply patches and check the results.
On 2005-08-15 08:38, "Gary W. Swearingen" <garys@opusnet.com> wrote: > --- intro..orig.5 Sun Aug 7 21:58:11 2005 > +++ intro.5 Sun Aug 7 22:07:22 2005 > @@ -38,11 +38,11 @@ > .Nm intro > .Nd "introduction to file formats" > .Sh DESCRIPTION > -This section contains information about file formats. > +This section contains information about file formats > +and some system Application Programming Interfaces (API .h files). > .Sh SEE ALSO > .Xr apropos 1 , > -.Xr intro 1 , > -.Xr intro 8 > +.Xr intro 1 > .Sh FILES > .Bl -tag -width /etc/shells -compact > .It Pa /etc I've been trying to find a good way to write down the same information without the inline parentheses and the need to quote ".h" with something like: .Dq Li \&.h Does this look ok to you Gary? I've removed the reference to ".h" files only because people who know enough about C already don't need to know this and people who don't know enough about C aren't (usually) interested in what the specific meaning of "API .h files" is. Here's the diff: % Index: intro.5 % =================================================================== % RCS file: /home/ncvs/src/share/man/man5/intro.5,v % retrieving revision 1.7 % diff -u -r1.7 intro.5 % --- intro.5 21 Jan 2005 08:36:39 -0000 1.7 % +++ intro.5 16 Aug 2005 21:39:15 -0000 % @@ -38,7 +38,10 @@ % .Nm intro % .Nd "introduction to file formats" % .Sh DESCRIPTION % -This section contains information about file formats. % +This section contains information about file formats and some system % +Application Programming Interface % +.Pq API % +files. % .Sh FILES % .Bl -tag -width /etc/shells -compact % .It Pa /etc If this looks ok to you, I'll commit it. Otherwise, I'll have to let other, more mdoc-savvy people handle this. - Giorgos
Giorgos Keramidas <keramida@freebsd.org> writes: > I've been trying to find a good way to write down the same information > without the inline parentheses and the need to quote ".h" with something > like: > > .Dq Li \&.h Why use "\&"? It's unneeded, AFAICT. Are single-character macros even allowed? "Pa" ("Path") might be more appropriate than "Li" and removes the need for "Dq". I assume that your use of a macro for ".h" necessitates a macro for parentheses; if there's a general problem with in-line parentheses, please let me know. > Does this look ok to you Gary? I've removed the reference to ".h" files > only because people who know enough about C already don't need to know > this and people who don't know enough about C aren't (usually) > interested in what the specific meaning of "API .h files" is. First off, I'm wondering why you want to change the manpage at all, since I thought that you didn't want the API/.h manpages in the section. Without thinking much about link(5), acct(5), and others, I thought that you were probably right and the intro(5) manpage didn't need to be changed because the others would be moved out of the section. But maybe you've come to the same conclusion I now have, after thinking more about link(5) and acct(5): that there is no better place for them. Furthermore, in a way, they are manpages for .h "file formats", if you stretch the meaning. Note that these .h files have no direct affiliation with programs or libraries or other things covered by other manual sections. So while I prefer some change to the manpage (only if acct(5), etc, are not moving), I'm OK if you'd rather not change it at all. As for my parenthetical phrase, you're right: readers probably only need to know that the section also covers XXX, where the meaning of "XXX" (.h files) doesn't matter as long as it obviously means something other than "file formats". So I would recommend something like this: +This section contains information about file formats +and about a few +.Pa .h +files not appropriate for other manual sections. (I repeated "about" to avoid an ambiguous meaning.)
On 2005-08-16 17:40, "Gary W. Swearingen" <garys@opusnet.com> wrote: >Giorgos Keramidas <keramida@freebsd.org> writes: >> I've been trying to find a good way to write down the same information >> without the inline parentheses and the need to quote ".h" with something >> like: >> >> .Dq Li \&.h > > Why use "\&"? It's unneeded, AFAICT. Are single-character macros > even allowed? I'm not guarding only against groff expanding .h as a macro. groff may automatically choose to break inline text whenever a punctuation mark appears or insert whitespace before, after or even both before and after such characters. This is why I used \& to protect the space before the dot. > "Pa" ("Path") might be more appropriate than "Li" and removes the need > for "Dq". It's not a path name though. It's a filename extension that is quoted literally as part of the running text. I prefer to use .Pa for complete filenames (like ``.Pa fstab'') or for path names with more components (like ``../foo'' or ``/etc/ttys''). > I assume that your use of a macro for ".h" necessitates a macro for > parentheses; if there's a general problem with in-line parentheses, > please let me know. Not really. I'm not sure if inline parentheses are preferred over more explicit markup. I tend to prefer the style of the left column shown below, but the definitive source for making an informed decision on this matter is Ruslan: GOOD STYLE BAD STYLE OUTPUT .Pq bar (bar) (bar) .Po (This text is (This text is This text is parenthesized). parenthesized). parenthesized .Pc . The extra markup is not only a matter of "having the right output format", but it's also (ala SGML) a matter of making the structure of the text apparent. > First off, I'm wondering why you want to change the manpage at all, > since I thought that you didn't want the API/.h manpages in the > section. Because its description section is incomplete right now. When we get approval from CVS meisters about a repo-move of the manpages to other sections and *if* we do get an approval for moving all of them, then the extra text can be removed. > Without thinking much about link(5), acct(5), and others, I thought > that you were probably right and the intro(5) manpage didn't need to > be changed because the others would be moved out of the section. This may take some time. > But maybe you've come to the same conclusion I now have, after > thinking more about link(5) and acct(5): that there is no better place > for them. It did cross my mind. So you think we have no good place for them, and the change should be done to intro(5)? > Furthermore, in a way, they are manpages for .h "file formats", if you > stretch the meaning. Note that these .h files have no direct > affiliation with programs or libraries or other things covered by > other manual sections. More or less. I've began thinking think they were put in section 5 because ``there isn't a section that may match their intent better than section 5 right now''. > So while I prefer some change to the manpage (only if acct(5), etc, > are not moving), I'm OK if you'd rather not change it at all. I'll make the change. The other manpages may take a long time to be moved into a more appropriate section, or they may never get moved at all. Fixing the description right now instead of waiting for what may never happen is better :) > +This section contains information about file formats > +and about a few > +.Pa .h > +files not appropriate for other manual sections. > > (I repeated "about" to avoid an ambiguous meaning.)
Giorgos Keramidas <keramida@ceid.upatras.gr> writes: > such characters. This is why I used \& to protect the space before the > dot. You wanted "``.h''", so there is no space. But I can believe it is sometimes needed and maybe should be a habit within macros. > The extra markup is not only a matter of "having the right output > format", but it's also (ala SGML) a matter of making the structure of > the text apparent. The structure of "(something)" is more apparent than ".Pq something", IMO. BTW, the mdoc(7) source is loaded with in-line parens. > It did cross my mind. So you think we have no good place for them, and > the change should be done to intro(5)? If moving was fast and easy, I'd probably move them to section 7, but it's not, so yes.
For bugs matching the following criteria: Status: In Progress Changed: (is less than) 2014-06-01 Reset to default assignee and clear in-progress tags. Mail being skipped
Keyword: patch or patch-ready – in lieu of summary line prefix: [patch] * bulk change for the keyword * summary lines may be edited manually (not in bulk). Keyword descriptions and search interface: <https://bugs.freebsd.org/bugzilla/describekeywords.cgi>
(In reply to Gary W. Swearingen from comment #4) > … I'll write another PR for expanding all the "SEE ALSO"s. (I'll > credit you for the idea. I'm not sure how popular it will be, > for example, in intro(4). :) … I am entirely certain that it will be no less popular, tomorrow, than it would have been when the idea was shared seventeen years ago. To Gary, and to any of his FreeBSD-loving descendants who may have been born during the era: * permission to proceed.