Re: [Groff] Nesting font macros in man pages

[Ralph Corderoy]

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