[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Groff] [PATCH] Expand portable escape section of groff_man(7).
From: |
G. Branden Robinson |
Subject: |
Re: [Groff] [PATCH] Expand portable escape section of groff_man(7). |
Date: |
Sat, 28 Oct 2017 19:03:10 -0400 |
User-agent: |
NeoMutt/20170113 (1.7.2) |
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