Paths with replaceable components

Paths with replaceable components

[Warren Block]

Because no good deed goes unpunished, I have another markup question. 
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?

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

Re: Paths with replaceable components

[Ingo Schwarze]

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 /

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?

Yours,
  Ingo
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

Re: Paths with replaceable components

[Warren Block]

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

Re: Paths with replaceable components

[Ingo Schwarze]

Hi Warren,

Warren Block wrote on Tue, Dec 16, 2014 at 09:41:02AM -0700:
> On Tue, 16 Dec 2014, Ingo Schwarze wrote:
>> 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!

Heh, i feared you would consider that "splitting up the path".
All the better you don't.

>> 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.

Yikes!  Indeed, splitting it up in that sense adds nothing
but verbosity.

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

Indeed.

> Thanks!

You are welcome.

Yours,
  Ingo
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv