.Xr references to ports in man pages

[Ruslan Ermilov]

Just a clarification.  Simon contacted me privately with this
issue, and I asked him to re-open this discussion here.

In particular, I'm interested in others' opinions on how this
should be rendered.

[Please don't drop me from the Cc: line, as I'm not subscribed
to this mailing list.]

On Fri, Apr 25, 2003 at 01:37:04AM +0200, Simon L. Nielsen wrote:
> Hello
> 
> I have been looking at fixing bad man references (.Xr) in the FreeBSD man
> pages.
> 
> Several system man pages references man pages from ports which of course
> might not be available.  This was also brought up in Oct 2001 by Murray
> Stokely where Ruslan Ermilov made a patch to support this in the
> standard .Xr macro.  The patch extends .Xr to handled port references
> like this :
> 
> .Xr smb.conf 5 net samba
> 
> which would be rendered as
> 
> .Xr smb.conf 5
> .Bq Pa ports/net/samba
> 
> and look like (except that the path is underlined)
> 
> smb.conf(5) [ports/net/samba]
> 
> What do people think about handling it like this?
> 
> It could perhaps be rendered diffently but I personally think that the
> way it is handled in the current patch is fine.  Mainly because I think
> it is rather clear what is meant and it doesn't "conflict" with other
> "rendering" that I have seen.
> 
> I would be happy to go through the system man pages and add the
> apropriate references (I already have a perl script for detecting bad
> references).
> 
> The mail from Ruslan with the patch can be found at
> http://www.freebsd.org/cgi/mid.cgi?id=20011008191058.B13684@sunbay.com .
> 
> I have extracted the patch if anyone wants to try it (it works at least
> againt a recent CURRENT) :
> http://simon.nitro.dk/freebsd/files/misc/ru-mdoc-ports.patch .
> 
> Hope somebody has an opinion about this.


-- 
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/07e0cb00/attachment.sig>