At 2017-10-28T17:33:55-0500, Dave Kemper wrote: > On 10/25/17, Ingo Schwarze <[email protected]> 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
