From owner-cvs-all Thu Aug 16 17:39: 3 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 C1E1D37B40C; Thu, 16 Aug 2001 17:38:57 -0700 (PDT) (envelope-from grog@lemis.com) Received: by wantadilla.lemis.com (Postfix, from userid 1004) id 654D86ACBC; Fri, 17 Aug 2001 10:08:55 +0930 (CST) Date: Fri, 17 Aug 2001 10:08:55 +0930 From: Greg Lehey To: Warner Losh Cc: Sheldon Hearn , Ruslan Ermilov , Alexander Langer , cvs-committers@FreeBSD.org, cvs-all@FreeBSD.org, Bruce Evans Subject: Re: "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: <20010817100855.A50416@wantadilla.lemis.com> References: <7507.997953894@axl.seasidesoftware.co.za> <200108161547.f7GFlmW33386@harmony.village.org> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline User-Agent: Mutt/1.2.5i In-Reply-To: <200108161547.f7GFlmW33386@harmony.village.org>; from imp@harmony.village.org on Thu, Aug 16, 2001 at 09:47:48AM -0600 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 Thursday, 16 August 2001 at 9:47:48 -0600, Warner Losh wrote: > In message <7507.997953894@axl.seasidesoftware.co.za> Sheldon Hearn writes: >>> 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. >> >> As both a reader and writer of manual pages, I don't like that. I like >> consistency in the SEE ALSO section so that I don't have to think as >> much when I scan it for something I suspect might be there. At some point we'll get down to personal preferences, of course. As you know, there's a lot that I don't like about the current layout. > I'd like to see things in alphabetical order, unless there's a real > compelling reason not to. And if there is a reason, it should be > documented. Otherwise, how do you tell the sloppy manual writer(s) > from the clever, but obscure? Agreed. Otherwise we'll end up with another thread like this one. But the documentation should probably be in comments. 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