bug#8275: [PATCH] Re: bug#8275: 24.0.50; Intro to Emacs Lisp Issue

[Richard Stallman <rms@gnu.org>]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > > The goal of this manual is not to
  > > show actual code used by Emacs, it's to teach programming in Emacs
  > > Lisp.

That is basically true, but perhaps a little too strongly put.
Teaching programming in Emacs Lisp is the primary goal.

  > Currently, the manual promises (and often does) to show actual code
  > usage. Citing `(eintr) On Reading this Text':

That is also true.  That is another nice thing that the manual does
"along the way."

It is fine to say "this is the code of function foo in Emacs 22", in
case years later someone reads that text when Emacs 32 is current, so
perse will understand why this example does not show the current Emacs
code.

Would it be better to update the manual to use the Emacs 32 code as an
example?  Maybe.

The advantage is, that it will show the code of the current Emacs.
The disadvantages are,

(1) updating the explanation is work, and needs a good writer,

(2) the newer code may be longer and more complex, so that it will be
more work to understand, and thus not as good for the manual's primary
goal,

(3) the newer code might be changed so much that it is no longer an
example of the feature to be illustrated.

When that last happens, it is possible to find and use a different
piece of code in Emacs.  But that's even more work.  Maybe the best
choice is to keep the Emacs 22 code as the example.

This partly depends on whether a good writer is available.  We don't
have anyone now who writes as well as Bob Chassell.

If you want to aim to develop your skills, by all means do -- but that
calls for getting lots of careful feedback from thoughtful readers
willing to spend time critiquing your writing.  Almost nobody gets to
be that good without doihg lots of writing and getting lots if
critiques.  On manuals I've written, I have generally got dozens of
people to read them carefully to report small points that were not
entirely clear.

Sometimes I would ask what makes a certain piece of text unclear, and
discuss possible improvements.

From each critique I addressed, I learned.  If you take this path,
you'll keep getting gradually better at writing.  But the path is long.

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)