From owner-cvs-all Wed Aug 15 18:13:17 2001 Delivered-To: cvs-all@freebsd.org Received: from wantadilla.lemis.com (wantadilla.lemis.com [192.109.197.80]) by hub.freebsd.org (Postfix) with ESMTP id C959F37B407; Wed, 15 Aug 2001 18:13:04 -0700 (PDT) (envelope-from grog@lemis.com) Received: by wantadilla.lemis.com (Postfix, from userid 1004) id 6CCFB6ACC1; Thu, 16 Aug 2001 10:43:02 +0930 (CST) Date: Thu, 16 Aug 2001 10:43:02 +0930 From: Greg Lehey To: Ruslan Ermilov Cc: Alexander Langer , cvs-committers@FreeBSD.org, cvs-all@FreeBSD.org, Bruce Evans Subject: "Rules" in documentation (was: cvs commit: src/bin/pwd pwd.1 src/bin/sh sh.1 src/gnu/usr.bin/man/manpath manpath.man src/lib/libc/db/man mpool.3 src/lib/libc/net getaddrinfo.3 getipnodebyname.3 src/lib/libc/posix1e acl.3 cap.3 cap_get_proc.3 posix1e.3 ...) Message-ID: <20010816104302.I49989@wantadilla.lemis.com> References: <20010815100157.C47417@sunbay.com> <20010815180724.A19209-100000@besplex.bde.org> <20010815114633.A61889@sunbay.com> <200107061646.f66Gkmf53701@freefall.freebsd.org> <20010814204826.A22531@zerogravity.kawo2.rwth-aachen.d> <20010815100157.C47417@sunbay.com> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline User-Agent: Mutt/1.2.5i In-Reply-To: <20010815100157.C47417@sunbay.com>; from ru@FreeBSD.org on Wed, Aug 15, 2001 at 10:01:57AM +0300 Organization: The FreeBSD Project Phone: +61-8-8388-8286 Fax: +61-8-8388-8725 Mobile: +61-418-838-708 WWW-Home-Page: http://www.FreeBSD.org/ X-PGP-Fingerprint: 6B 7B C3 8C 61 CD 54 AF 13 24 52 F8 6D A4 95 EF Sender: owner-cvs-all@FreeBSD.ORG Precedence: bulk List-ID: List-Archive: (Web Archive) List-Help: (List Instructions) List-Subscribe: List-Unsubscribe: X-Loop: FreeBSD.ORG On Wednesday, 15 August 2001 at 10:01:57 +0300, Ruslan Ermilov wrote: > On Tue, Aug 14, 2001 at 08:48:26PM +0200, Alexander Langer wrote: >> Thus spake Ruslan Ermilov (ru@FreeBSD.org): >> >>> share/man/man9 DECLARE_MODULE.9 DEVICE_IDENTIFY.9 >>> DEV_MODULE.9 DRIVER_MODULE.9 >>> MODULE_DEPEND.9 MODULE_VERSION.9 >>> mdoc(7) police: sort SEE ALSO xrefs (sort -b -f +2 -3 +1 -2). >> >> The xref's have been sorted _logically_. >> Especially DEVICE_IDENTIFY(9)'s SEE ALSO section is unhandsome now. >> >> And I still think MODULE* comes before module*, which is the usual >> UNIX sort method. >> > We have a rule for this, in mdoc(7): > >> It is recommended that the cross references are sorted >> on the section number, then alphabetically on the >> names within a section, and placed in that order and >> comma separated. I don't see a rule here, only a recommendation. > "Alphabetically" means that the case is unimportant. > Think of the SEE ALSO as of a book's Index. All folded-case alphabetical sorting I have seen has kept a consistent style. Not doing so would look really messy. On Wednesday, 15 August 2001 at 11:46:33 +0300, Ruslan Ermilov wrote: > On Wed, Aug 15, 2001 at 06:13:49PM +1000, Bruce Evans wrote: >> On Wed, 15 Aug 2001, Ruslan Ermilov wrote: >> >>> On Tue, Aug 14, 2001 at 08:48:26PM +0200, Alexander Langer wrote: >>>> The xref's have been sorted _logically_. >>>> Especially DEVICE_IDENTIFY(9)'s SEE ALSO section is unhandsome now. >>>> >>>> And I still think MODULE* comes before module*, which is the usual >>>> UNIX sort method. >>>> >>> We have a rule for this, in mdoc(7): >>> >>>> It is recommended that the cross references are sorted >>>> on the section number, then alphabetically on the >>>> names within a section, and placed in that order and >>>> comma separated. >>> >>> "Alphabetically" means that the case is unimportant. >>> Think of the SEE ALSO as of a book's Index. >> >> I think case is important. It just doesn't make much difference for >> man pages because most man pages don't have unhandsome upper case names Unfortunately, they now do. This is another "rule". > Well, I looked at the several of my books, including "TCP/IP > Illustrated" by Stevens and "The Design and Implementation of the > 4.4BSD Operating System" by McKusick (both books published by AWL), > and they had their Index sorted alphabetically, not > lexicographically. Well, that could be the publisher's guideline. The correct place to look would be a style guide. But I don't think that the index in a book has very much in common with SEE ALSO in man pages. If a man page writer has a particular reason for a specific sequence, I don't think other people should go in and change it. And I think we should have fewer rules and more guidelines. Greg -- See complete headers for address and phone numbers To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe cvs-all" in the body of the message