Re: [Groff] Nesting font macros in man pages

[James K. Lowden]

On Fri, 28 Apr 2017 01:15:05 -0400
"G. Branden Robinson" <address@hidden> wrote:

> the benefit to the user is relatively few keystrokes above those
> > needed for the text.
> 
> Did you write your DocBook-based user guide in ed?
> 
> Nothing has come close to saving me more keystrokes than <TAB> at the
> shell prompt and CTRL-N in Vim.

At the time I used nedit.  Today I would use emacs.  There's no package
for docbook-mode that closes tags for you.  The xml modes I've used are
lame and wouldn't perform well on a large manual.  

DocBook is a complex beast.  It would be great if the editor could do
tab-completion for valid tags for the current parent and valid parents
for a selected region, and jump from beginning to end of a tag.  If
such a tool exists, that would be news to me.  

Meanwhile, what could be simpler than having the editor supply "tool
tip" text to explain .Sx or an "mdoc apropos" feature derived from
keywords in the manual?  The only reason there isn't better editor
facilitation for man and mdoc is ... lack of interest.  The problem is
technically much simpler.  

> We have ludicrously more processor horsepower and memory

Yes, and my contention is that we nevertheless have not developed a
system that is easier to use or learn.  troff macro packages are
simpler and impose less on the author than any alternative of similar
capacity.   The facilitation promised 2 decades ago to deal with the
verbosity and complexity of more recent designs never materialized,
leaving authors with a variety of lousy options. 

> They're programmers.  Some of them are difficult to coerce into
> writing documentation _at all_.

There is no evidence that programmers disinclined to write
documentation do a better job of it if it's made easier to do.  Good
documentation takes effort, and that effort is different from the
programming effort.  

The impetus for Markdown and Doxygen and the like is that good
documentation will emerge by lowering the bar.  It's simply not true.

The problem of writing documentation isn't in opening another file
(Doxygen) or understanding the markup system (Markdown).  It's in
capturing the syntax and semantics from the point of view of the user.
And, as you say, some people have the additional burden of caring
enough to bother.  

I have yet to see good documentation produced by those systems unless
great care was taken.  Having used Doxygen for C library with a 100
functions, I wouldn't use it again.  For equivalent time invested, I
get better results from mdoc, albeit without the pretty diagrams. 

>> when transferring them from the manpage

I was afraid that might not be clear.  What I meant is that as I'm
writing documentation, I'm refering to the mdoc manpage (say).  I've
never done that kind of work for a living.  I'm just another occasional
mdoc hacker, so I quite often have to relearn parts of it.  By
"transfer", I meant putting to use what I'm reading in my writing.  Two
letters aren't hard to remember, and most of the pairs carry some
mnemonic weight.  (That said, better editor facilitation would make the
work less tedious.)  

> C adopted designated initializers, a sop to those who can't recall
> what order a struct's fields come in. 

I guess you're implying that designated initializers, while verbose,
are easier to use, even for aficionados of a terse language like C.
As it happens, my current work is in C, and I adopted C11 as a
baseline, partly so I could use them.  

With today's machines, the compiler can do more than was feasible in
1978.  I'd argue we have bigger structures now, too.  Designated
initializers aren't so much a sop to the lazy as they are a gift of
clarity, because otherwise the programmer has to count structure
elements and supply any zeros preceding the elements to be
initialized.  Designated initializers also support re-initialization of
existing structures, something that otherwise required error-prone
member-by-member assignment.  

All to say that at least one fan of short macro names finds explicit
structure initialization useful.  

--jkl