Re: SGML tools aren't so great

[Joe Cooper <joe@swelltech.com>]

Gary Preckshot wrote:
>
> It's certainly the most obvious defect of the emacs help system. I want to quit. What
> I want to know is how to quit. If I knew how to quit, I wouldn't be asking the "help"
> system how to quit. Emacs help could use reorientation - deal with the basics of
> editing and make them findable by terms ordinary human beings use to describe them,
> like quit, find, save, delete, cursor, move, insert, you know, simple terms.
> 
> The HOWTO HOWTO should maybe address this issue. HOWTO authors would be more helpful
> if they addressed how to first and why in later chapters. Instead, they follow the
> usual nerd practice (there's that word again) of explaining everything adnauseum and
> finally getting to the point. Maybe there should be a style manual.

I totally agree with this assessment of the Emacs documentation.  Maybe
you should forward this email to the GNU info writers! ;-)  I HATE the
GNU 'info' pages (man pages stripped of useful content and with an
atrocious user interface is more like it).  One would think from reading
the info pages that examples are a sin.  There must be some provision of
the GNU bylaws that disallows examples.  "Any GNU member found providing
a useful example shall be drawn, quartered, and forced to single task
for all eternity under MSDOS V2.0."

I agree that perhaps HOWTOs should nearly always focus on how to do
something first in plain terms and then move on to theory and a complete
explanation of what the examples provided earlier are doing and how. 
Sort of:

1.  Build frog.  Include good diagrams and directions.
2.  Make it hop.  
3.  Chop it up and talk about its guts.
4.  Put it back together and hopefully make frog hop higher and faster.

Optional step 5.  Sweep excess frog parts under carpet and walk away
whistling trying to avoid looking guilty.

I think there are quite a few good HOWTO's out there that do just that,
while others beat the bush and all surrounding terrain to a bloody pulp
before finally getting to the roots.

Just call me Mr. States The Obvious.
                                 -- 
                    Joe Cooper <joe@swelltech.com>
                Affordable Web Caching Proxy Appliances
                       http://www.swelltech.com


--  
To UNSUBSCRIBE, email to ldp-discuss-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org