groff
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [Groff] Nesting font macros in man pages


From: G. Branden Robinson
Subject: Re: [Groff] Nesting font macros in man pages
Date: Fri, 28 Apr 2017 01:15:05 -0400
User-agent: NeoMutt/20170113 (1.7.2)

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

Attachment: signature.asc
Description: PGP signature


reply via email to

[Prev in Thread] Current Thread [Next in Thread]