Re: [Groff] Nesting font macros in man pages

[James K. Lowden]

On Wed, 26 Apr 2017 09:46:43 -0400
"G. Branden Robinson" <address@hidden> wrote:

> 1. The slavish devotion to two-letter names for things, which like the
>    man macro package and the oldest parts of *roff itself, make it
>    self-anti-documenting.  

Having written one user guide in DocBook, I have to disagree.  

The troff system was designed to be typed at a keyboard.  The
dot-on-the-left rule might be ugly, and the requests/macros terse,
but the benefit to the user is relatively few keystrokes above those
needed for the text.  The nearest modern cousin might be HTML, with its
single-letter tags. 

Most SGML derivatives, on the other hand, presupposed Interleaf-like
tools that would shield users from the markup syntax. That "assume a can
opener" design theory freed them to be verbose. When the tools never
materialized, users started looking for a way to avoid their verbosity
tax.  Markdown is only the latest product of that search.  

Short names are actually *easier* to use than long ones!  Why?  

        Brevity rewards experience.  

If .SH or .Sx is hard to read, they're also easy to write, and easy to
remember when transferring them from the manpage to the document at
hand.  If it's hard to remember what the "next page" request is, .bp is
no harder than remembering whether it's .BreakPage or .PageBreak.  

Stroustrup has an interesting observation about language brevity based
on the evolution of C++.  Users, he says, want novel features to be
"loud" and well-understood paradigms to be terse.  Trouble is, today's
novel is tomorrow's obvious.  As a result, C++ has been losing syntax,
making implicit that which 20 years ago was explicit.  But, of course,
the new language features recently added are "loud".  

In today's world, to most programmers troff is 100% novel, and they find
its terseness inscrutable and off-putting.  Too hard to understand!  

Ah.  But so easy to use.  

--jkl