Date: Wed, 17 Aug 2005 12:20:25 GMT From: Giorgos Keramidas <keramida@ceid.upatras.gr> To: freebsd-doc@FreeBSD.org Subject: Re: docs/84956: [patch] intro(5) manpage doesn't mention API coverage Message-ID: <200508171220.j7HCKPkI018278@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: 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.)
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200508171220.j7HCKPkI018278>