Re: [Groff] Nesting font macros in man pages

[John Gardner]

Chained commands are easier to follow with syntax highlighting:

[image: Inline images 1]

But I'm still in agreement with Ralph here, at least with regards to
complex formatting. Lines like `.It Ar radius` are fine, but the Ns and No
commands... ugh. Even when formatting with mdoc, I find it beneficial to
include a few wrapper macros to reduce clutter:

Although I *always* keep this one handy:

.de XR
> . Xr \\fB\\$1\\fP \\$2
> ..


Seeing manpage references without *bold*(1) just looks unnatural to me. ;-)

On 30 April 2017 at 22:27, Ralph Corderoy <address@hidden> wrote:

> Hi Ingo,
>
> > > > .Fl S Ar var Ns Op Pf = Ar value
> > >
> > > This has reminded me of one reason I didn't get on with mdoc.  Only
> > > the `Fl' is obviously mdoc's, due to the `.' invocation.  The rest
> > > are a mix of command and data, but without any sigil one's left
> > > guessing unless the command set has been memoised.
> ...
> > > If, in some made up syntax, it was
> > >
> > >     .Fl S .Ar var .Ns .Op .Pf = .Ar value
> > >
> > > that might be more grokable,
> >
> > Remebering the above very simple rule about Xx-style words, it is
> > about the same; maybe the shorter version is even easier to read.
>
> No, the `dot-less' version, though shorter, isn't easier since there's
> too little to distinguish command and data and the /^[A-Z][a-z]$/ rule
> is slower to apply when reading than /^\./.
>
> > > though still long-winded for `-S var[=value]'.
> >
> > It is not long-winded at all.  Even in man(7), which has no sematic
> > annotation, it is
> >
> > .B -S
> > .IR var [= value ]
>
> But with that -man, I can quickly see that "-S var [= value ]" is the
> useful information being presented by the page.  If I'm reading for
> formatting then I can look back to the start of the line that I've
> skipped over, see the .IR, and apply it to the arguments.  But if I
> don't, and most of the time when editing a man page I'm not doing a
> careful format check, then I want the plain-text content, and it's -man
> that gives it.
>
> > That's 33 bytes (long-winded!?) in mdoc(7) vs. 25 bytes in man(7),
>
> It's long winded because one reads words and then has to parse the
> non-English ones, and mdoc makes parsing for humans too slow and
> awkward.
>
>     10  .Fl S Ar var Ns Op Pf = Ar value
>
>      2  .B -S
>      5  .IR var [= value ]
>
> > The basic concept of mdoc(7) is extremely close to the theoretical
> > optimum.
>
> That's not what's wanted; redundancy for a reader would improve mdoc,
> e.g. a `.' sigil, or `[]' still being present even though `Op' doesn't
> need them.
>
> --
> Cheers, Ralph.
> https://plus.google.com/+RalphCorderoy
>
>