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