Re: [Groff] [PATCH] Expand portable escape section of groff_man(7).

[G. Branden Robinson]

At 2017-10-28T17:33:55-0500, Dave Kemper wrote:
> On 10/25/17, Ingo Schwarze <address@hidden> wrote:
> > it is never useful to
> > show how something renders.  Users can easily try for themselves.
> 
> I am grateful that the authors of the groff documentation do not
> subscribe to this view.  Groff's numerous examples of how input gets
> transformed to output have been extremely useful to me.  While it's
> certainly possible to try things out for yourself, when you're looking
> through the docs to find the right solution to the problem you're
> trying to solve, having numerous examples with output saves a lot of
> time over having to run a bunch of snippets to see which request or
> macro most closely matches what you need.

People have different ways of learning.  When I'm reading math I prefer
to see both a theorem (with proof, if proof is possible at my level of
preparation) and examples.  When an example is not available I have to
stop and try thinking of some[1].

Not long after reading Ingo's mail I reviewed and noted the differences
between groff_me(7) and groff_ms(7).

I think both tutorials and terse references (e.g., in the style of the
tables in CSTR #54) have their place, and I particularly feel that the
former can perfectly well be written in roff, not necessarily Texinfo.

That said, a document that frequently lurches back and forth between
index-like reference and hand-holding tutorial is incomplete and/or
poorly organized.  Both are bugs.

[1] (_Counterexamples in Analysis_ by Gelbaum and Olmstead is a favorite
of mine.  It should be subtitled "Everything They Taught You in Freshman
Calculus Is a Lie". :D )

-- 
Regards,
Branden

signature.asc
Description: PGP signature