From owner-freebsd-doc@FreeBSD.ORG Fri Apr 25 13:24:55 2003 Return-Path: Delivered-To: freebsd-doc@freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id ACA8037B401 for ; Fri, 25 Apr 2003 13:24:55 -0700 (PDT) Received: from whale.sunbay.crimea.ua (whale.sunbay.crimea.ua [212.110.138.65]) by mx1.FreeBSD.org (Postfix) with ESMTP id 38D6043FDD for ; Fri, 25 Apr 2003 13:24:52 -0700 (PDT) (envelope-from ru@whale.sunbay.crimea.ua) Received: from whale.sunbay.crimea.ua (ru@localhost [127.0.0.1]) h3PKOR62032392 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Fri, 25 Apr 2003 23:24:28 +0300 (EEST) (envelope-from ru@whale.sunbay.crimea.ua) Received: (from ru@localhost) by whale.sunbay.crimea.ua (8.12.9/8.12.8/Submit) id h3PKORSV032387; Fri, 25 Apr 2003 23:24:27 +0300 (EEST) (envelope-from ru) Date: Fri, 25 Apr 2003 23:24:27 +0300 From: Ruslan Ermilov To: "Gary W. Swearingen" Message-ID: <20030425202427.GC28920@sunbay.com> References: <20030424233703.GB48527@nitro.dk> Mime-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha1; protocol="application/pgp-signature"; boundary="kfjH4zxOES6UT95V" Content-Disposition: inline In-Reply-To: User-Agent: Mutt/1.5.4i cc: "Simon L. Nielsen" cc: freebsd-doc@freebsd.org Subject: Re: .Xr references to ports in man pages X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.1 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 25 Apr 2003 20:24:56 -0000 --kfjH4zxOES6UT95V Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable On Fri, Apr 25, 2003 at 12:06:46PM -0700, Gary W. Swearingen wrote: > "Simon L. Nielsen" writes: >=20 > > Hope somebody has an opinion about this. >=20 > I can't think of a better way to render the information, but I have a > suggestion regarding the ease of manpage source maintenance. >=20 > Unless port names require their category name to be unique (and they > don't, AFAIK), then the inclusion of the port category within the man > pages introduces an unnecessary need to search man pages and make > corrections whenever port categorization is changed, as happens > occasionally. >=20 Throughout the SGML documentation, they are referred as CATEGORY/PORTNAME Why the manpages should be different? > Two "solutions" are obvious: 1) Omit the category altogether and expect > users to know how to use the "whereis" command. 2) Make the macro smart > enough to figure out the category name from the port name. This would > still require maintenance, but would localize it to one file. >=20 > I think that all users should know how to use "whereis" and requiring > them to use it is not unreasonable. The rendering would need to be > changed to something like: smb.conf(5) [port "samba"] Cheers, --=20 Ruslan Ermilov Sysadmin and DBA, ru@sunbay.com Sunbay Software AG, ru@FreeBSD.org FreeBSD committer, +380.652.512.251 Simferopol, Ukraine http://www.FreeBSD.org The Power To Serve http://www.oracle.com Enabling The Information Age --kfjH4zxOES6UT95V Content-Type: application/pgp-signature Content-Disposition: inline -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.2.1 (FreeBSD) iD8DBQE+qZl7Ukv4P6juNwoRAo6JAJ4mbTqTtiJ6XOQJF7ZhBGcaneWG6gCcDb4h 2p2dy+NpPeO9KSRI/mW8Gm0= =wW3H -----END PGP SIGNATURE----- --kfjH4zxOES6UT95V--