Date: Wed, 17 Aug 2005 00:40:27 GMT From: garys@opusnet.com (Gary W. Swearingen) To: freebsd-doc@FreeBSD.org Subject: Re: docs/84956: [patch] intro(5) manpage doesn't mention API coverage Message-ID: <200508170040.j7H0eRL5022300@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: 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.)
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200508170040.j7H0eRL5022300>