From owner-freebsd-doc@FreeBSD.ORG Wed Aug 17 12:20:26 2005 Return-Path: X-Original-To: freebsd-doc@hub.freebsd.org Delivered-To: freebsd-doc@hub.freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 5723116A41F for ; Wed, 17 Aug 2005 12:20:26 +0000 (GMT) (envelope-from gnats@FreeBSD.org) Received: from freefall.freebsd.org (freefall.freebsd.org [216.136.204.21]) by mx1.FreeBSD.org (Postfix) with ESMTP id 1911243D46 for ; Wed, 17 Aug 2005 12:20:26 +0000 (GMT) (envelope-from gnats@FreeBSD.org) Received: from freefall.freebsd.org (gnats@localhost [127.0.0.1]) by freefall.freebsd.org (8.13.3/8.13.3) with ESMTP id j7HCKPQR018279 for ; Wed, 17 Aug 2005 12:20:25 GMT (envelope-from gnats@freefall.freebsd.org) Received: (from gnats@localhost) by freefall.freebsd.org (8.13.3/8.13.1/Submit) id j7HCKPkI018278; Wed, 17 Aug 2005 12:20:25 GMT (envelope-from gnats) Date: Wed, 17 Aug 2005 12:20:25 GMT Message-Id: <200508171220.j7HCKPkI018278@freefall.freebsd.org> To: freebsd-doc@FreeBSD.org From: Giorgos Keramidas Cc: Subject: Re: docs/84956: [patch] intro(5) manpage doesn't mention API coverage X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list Reply-To: Giorgos Keramidas List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 17 Aug 2005 12:20:26 -0000 The following reply was made to PR docs/84956; it has been noted by GNATS. From: Giorgos Keramidas To: "Gary W. Swearingen" 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" wrote: >Giorgos Keramidas 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.)