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

[Gary W. Swearingen]

The following reply was made to PR docs/84956; it has been noted by GNATS.

From: garys at opusnet.com (Gary W. Swearingen)
To: Giorgos Keramidas <keramida at freebsd.org>
Cc: bug-followup at 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 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?
 
 "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.)