Re: Paths with replaceable components

[Warren Block <wblock@wonkity.com>]

On Tue, 16 Dec 2014, Ingo Schwarze wrote:

> Hi Warren,
>
> Warren Block wrote on Mon, Dec 15, 2014 at 05:19:44PM -0700:
>
>> We have another man page for the new autofs.
>> One of the associated pages refers to this path:
>>
>> .Pa /net/nfs-server-ip/share-name/
>>
>> "net" is a literal there, but "nfs-server-ip" and "share-name" are not.
>>
>> In DocBook, I'd mark them up as <replaceable>, to indicate to the
>> reader that they are not literal.  Is there a preferred mdoc way to
>> do that in a path without splitting up the path components?
>
> I would mark up the path like this:
>
>  .Pf /net/ Ar nfs-server-ip Ns / Ns Ar share-name Ns /

Nice!

> Making it clear which parts need replacements is probably more
> important than marking up the whole thing as a path, and you can't
> do both at the same time since mdoc(7) inline macros don't nest.
>
> Why do you want to avoid splitting up the path components?

I tried it, and it just seemed to make it longer.  More interpretation 
was required by the reader, and it was just unwieldy.  One version:

Access to files on a remote NFS server is provided through the
.Pa /net
directory.
Inside that directory are subdirectories for each NFS server IP address 
and the exported directories.
For example, files in the
.Pa artwork
directory on the NFS server at 192.168.1.202 will appear in the
.Pa /net/192.168.1.202/artwork
directory without any additional configuration.

Certainly that can be improved, but I prefer the clarity of having one 
full path shown with replaceable arguments.

Thanks!
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv