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 <ra...@inputplus.co.uk> 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 > >
