From garys@opusnet.com  Mon Aug 15 15:37:37 2005
Return-Path: <garys@opusnet.com>
Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125])
	by hub.freebsd.org (Postfix) with ESMTP id 87BE016A41F
	for <FreeBSD-gnats-submit@freebsd.org>; Mon, 15 Aug 2005 15:37:37 +0000 (GMT)
	(envelope-from garys@opusnet.com)
Received: from opusnet.com (mail.opusnet.com [209.210.200.6])
	by mx1.FreeBSD.org (Postfix) with ESMTP id 416A343D45
	for <FreeBSD-gnats-submit@freebsd.org>; Mon, 15 Aug 2005 15:37:37 +0000 (GMT)
	(envelope-from garys@opusnet.com)
Received: from localhost.localhost [70.98.246.232] by opusnet.com with ESMTP
  (SMTPD32-8.05) id A6BF390D00A0; Mon, 15 Aug 2005 08:37:35 -0700
Received: from localhost.localhost (localhost.localhost [127.0.0.1])
	by localhost.localhost (8.13.3/8.13.3) with ESMTP id j7FFcIJs026333
	for <FreeBSD-gnats-submit@freebsd.org>; Mon, 15 Aug 2005 08:38:18 -0700 (PDT)
	(envelope-from garys@opusnet.com)
Received: (from jojo@localhost)
	by localhost.localhost (8.13.3/8.13.3/Submit) id j7FFcDn3026332;
	Mon, 15 Aug 2005 08:38:13 -0700 (PDT)
	(envelope-from garys@opusnet.com)
Message-Id: <ink6inxlay.6in@mail.opusnet.com>
Date: Mon, 15 Aug 2005 08:38:13 -0700
From: "Gary W. Swearingen" <garys@opusnet.com>
Reply-To: garys@opusnet.com
To: FreeBSD-gnats-submit@freebsd.org
Subject: [patch] intro(5) manpage doesn't mention API coverage
X-GNATS-Notify:

>Number:         84956
>Category:       docs
>Synopsis:       [patch] intro(5) manpage doesn't mention API coverage
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Mon Aug 15 15:40:09 GMT 2005
>Closed-Date:    
>Last-Modified:  Wed Aug 17 14:40:21 GMT 2005
>Originator:     Gary W. Swearingen
>Release:        FreeBSD 5.4-RELEASE i386
>Organization:
none
>Environment:
n/a
>Description:

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

>Fix:

--- 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
>Release-Note:
>Audit-Trail:

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 18:56:40 +0300

 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
 

From: garys@opusnet.com (Gary W. Swearingen)
To: Giorgos Keramidas <keramida@freebsd.org>
Cc: bug-followup@freebsd.org
Subject: Re: docs/84956: [patch] intro(5) manpage doesn't mention API
 coverage
Date: Tue, 16 Aug 2005 12:09:19 -0700

 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).

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
 

From: garys@opusnet.com (Gary W. Swearingen)
To: Giorgos Keramidas <keramida@freebsd.org>
Cc: bug-followup@freebsd.org
Subject: Re: docs/84956: [patch] intro(5) manpage doesn't mention API
 coverage
Date: Tue, 16 Aug 2005 14:15:10 -0700

 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.

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: Wed, 17 Aug 2005 00:44:49 +0300

 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

From: garys@opusnet.com (Gary W. Swearingen)
To: Giorgos Keramidas <keramida@freebsd.org>
Cc: bug-followup@freebsd.org
Subject: Re: docs/84956: [patch] intro(5) manpage doesn't mention API
 coverage
Date: Tue, 16 Aug 2005 17:40:01 -0700

 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.)

From: Giorgos Keramidas <keramida@ceid.upatras.gr>
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: Wed, 17 Aug 2005 15:24:53 +0300

 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.)

From: garys@opusnet.com (Gary W. Swearingen)
To: Giorgos Keramidas <keramida@ceid.upatras.gr>
Cc: bug-followup@freebsd.org
Subject: Re: docs/84956: [patch] intro(5) manpage doesn't mention API
 coverage
Date: Wed, 17 Aug 2005 07:34:27 -0700

 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.
>Unformatted:
