.Xr references to ports in man pages

[Ruslan Ermilov]

On Fri, Apr 25, 2003 at 12:06:46PM -0700, Gary W. Swearingen wrote:
> "Simon L. Nielsen" <simon at nitro.dk> writes:
> 
> > Hope somebody has an opinion about this.
> 
> I can't think of a better way to render the information, but I have a
> suggestion regarding the ease of manpage source maintenance.
> 
> 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.
> 
Throughout the SGML documentation, they are referred as

<filename role="package">CATEGORY/PORTNAME</filename>

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.
> 
> 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,
-- 
Ruslan Ermilov		Sysadmin and DBA,
ru at sunbay.com		Sunbay Software AG,
ru at 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
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 187 bytes
Desc: not available
URL: <http://lists.freebsd.org/pipermail/freebsd-doc/attachments/20030425/e3af00dc/attachment.sig>