From owner-freebsd-doc@FreeBSD.ORG Wed Aug 17 00:40:28 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 0930316A41F for ; Wed, 17 Aug 2005 00:40:28 +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 AFF9143D48 for ; Wed, 17 Aug 2005 00:40:27 +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 j7H0eRm2022301 for ; Wed, 17 Aug 2005 00:40:27 GMT (envelope-from gnats@freefall.freebsd.org) Received: (from gnats@localhost) by freefall.freebsd.org (8.13.3/8.13.1/Submit) id j7H0eRL5022300; Wed, 17 Aug 2005 00:40:27 GMT (envelope-from gnats) Date: Wed, 17 Aug 2005 00:40:27 GMT Message-Id: <200508170040.j7H0eRL5022300@freefall.freebsd.org> To: freebsd-doc@FreeBSD.org From: garys@opusnet.com (Gary W. Swearingen) 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: "Gary W. Swearingen" List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 17 Aug 2005 00:40:28 -0000 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 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 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.)