From owner-freebsd-doc@FreeBSD.ORG  Fri Apr 25 16:46:18 2003
Return-Path: <owner-freebsd-doc@FreeBSD.ORG>
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 29C8837B401; Fri, 25 Apr 2003 16:46:18 -0700 (PDT)
Received: from rwcrmhc53.attbi.com (rwcrmhc53.attbi.com [204.127.198.39])
	by mx1.FreeBSD.org (Postfix) with ESMTP
	id 49C0443FBD; Fri, 25 Apr 2003 16:46:13 -0700 (PDT)
	(envelope-from swear@attbi.com)
Received: from localhost.localdomain (unknown[12.242.158.67])
          by rwcrmhc53.attbi.com (rwcrmhc53) with ESMTP
          id <20030425234612053001as4be>; Fri, 25 Apr 2003 23:46:12 +0000
Received: from localhost.localdomain (localhost [127.0.0.1])
	by localhost.localdomain (8.12.6/8.12.5) with ESMTP id h3PNkPsg054033;
	Fri, 25 Apr 2003 16:46:30 -0700 (PDT)
	(envelope-from swear@attbi.com)
Received: (from jojo@localhost)
	by localhost.localdomain (8.12.6/8.12.5/Submit) id h3PNkI3L054030;
	Fri, 25 Apr 2003 16:46:18 -0700 (PDT)
	(envelope-from swear@attbi.com)
X-Authentication-Warning: localhost.localdomain: jojo set sender to
	swear@attbi.com using -f
To: Ruslan Ermilov <ru@freebsd.org>
References: <20030424233703.GB48527@nitro.dk>
	<ien0ie9z21.0ie@localhost.localdomain>
	<20030425202427.GC28920@sunbay.com>
From: swear@attbi.com (Gary W. Swearingen)
Date: 25 Apr 2003 16:46:18 -0700
In-Reply-To: <20030425202427.GC28920@sunbay.com>
Message-ID: <t2ist29m45.st2@localhost.localdomain>
Lines: 20
User-Agent: Gnus/5.0808 (Gnus v5.8.8) XEmacs/21.1 (Cuyahoga Valley)
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
cc: "Simon L. Nielsen" <simon@nitro.dk>
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 <freebsd-doc.freebsd.org>
List-Unsubscribe: <http://lists.freebsd.org/mailman/listinfo/freebsd-doc>,
	<mailto:freebsd-doc-request@freebsd.org?subject=unsubscribe>
List-Archive: <http://lists.freebsd.org/pipermail/freebsd-doc>
List-Post: <mailto:freebsd-doc@freebsd.org>
List-Help: <mailto:freebsd-doc-request@freebsd.org?subject=help>
List-Subscribe: <http://lists.freebsd.org/mailman/listinfo/freebsd-doc>,
	<mailto:freebsd-doc-request@freebsd.org?subject=subscribe>
X-List-Received-Date: Fri, 25 Apr 2003 23:46:18 -0000

Ruslan Ermilov <ru@freebsd.org> writes:

> Throughout the SGML documentation, they are referred as
> 
> <filename role="package">CATEGORY/PORTNAME</filename>
> 
> Why the manpages should be different?

To avoid having erroneous information in the manpages before someone
discovers that the category has been changed without the changer
remembering and/or bothering to search all the manpages and fix all the
unnecessary category references which have gone bad.  That's too much to
expect to happen, methinks.  Also, to avoid the need to handle the
PRs that will then be (eventually) written after nearly every change.

As for the SGML, the same thing applies, but I suspect it's too hard to
fix in the SGML processing, but I recommend easing SGML maintenance by
omitting the "CATEGORY/".  There's too much more useful stuff to
maintain, as it is, and "whereis" easily gives the category to anyone
who can't guess it.