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

 On 2005-08-16 17:40, "Gary W. Swearingen" <garys at opusnet.com> wrote:
 >Giorgos Keramidas <keramida at 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.)