Re: [Groff] Nesting font macros in man pages

[John Gardner]

This touches on something I experienced recently. I wanted to write a
JavaScript module that would help developers generate manual-pages for
their projects (because there's a searing lack of manpages in the Node
community...).

I ended up ditching that idea when I realised developers would still be
asking for the possibility of converting Markdown into Roff commands... and
I realised I'd be going through endless effort to spoon-feed close-minded
devs who can't be bothered making an attempt to learn even basic manpage
authoring. I laughed at how complex a JavaScript-based documentation
generator would become when compared to the simplicity and power of a
simple, plain, correctly-written manpage.

As Branden said: you can lead a horse to its troff, but you can't make them
drink.

(I know it's pronounced "tee-roff", not "trough", but c'mon, that pun was
unavoidable...)

On 28 April 2017 at 15:15, G. Branden Robinson <address@hidden
> wrote:

> At 2017-04-27T23:38:23-0400, James K. Lowden wrote:
> > 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.
>
> 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.
>
> We have powerful, robust, and programmable text-completion systems these
> days.
>
> I have second-hand nostalgia for the early Bell Labs Unix days (too?),
> but we don't live in those times.  We have ludicrously more processor
> horsepower and memory, and we've even, occasionally, found some good
> applications for the surfeit.
>
> > 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.
>
> Well, that's part of the problem.  Few people are full-time *roff or
> macro package users.  They're programmers.  Some of them are difficult
> to coerce into writing documentation _at all_.
>
> A lot of people hate Fortran, but I don't.  In the 20+ years since I
> first saw it I've come to recognize a huge virtue in its insistence on
> unabbreviated English words for its keywords; they're more ergonomic for
> the scientists and (non-software) engineers who have been off doing
> science or engineering for several months and only occasionally have to
> do code maintenance or development.
>
> That's the analogy I recommend for macro packages targeting
> documentation of software systems.  You can even lead the horses to
> literate programming, as Knuth tried to do decades ago, and most of them
> will stubbornly spend the great bulk of their time in the part that gets
> tangled rather then the part that gets woven.
>
> It doesn't matter for our discussion why that is--it's a fact and the
> state of our discipline.  Maybe they're snooty elitists or code cowboys
> or rock stars or maybe they simply spend their time where the problems
> are.
>
> The competing models of "recognition" vs. "recall" have occupied a lot
> of writing on user experience.
>
> I submit to you that for most of its users, the man macro package needs
> to work the "recognition" side of the street.
>
> > 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.
>
> I don't understand this claim.  Section headings would be pretty obvious
> most of the time even if they weren't marked up at all.  You're not
> transferring the macros, surely, but rather their parameters, right?  Do
> you remember off the top of your head in what order the 6 arguments to
> .TH get placed at header-left, header-middle, header-right, footer-left,
> footer-middle, and footer-right?
>
> Even the ne plus ultra of terseness among successful languages, C,
> adopted designated initializers, a sop to those who can't recall what
> order a struct's fields come in.  (Though I wouldn't bet on whether
> Ritchie would have thought it was a good idea.)
>
> > 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.
>
> ...and yet again so hard to use correctly.
>
> Regards,
> Branden
>