Re: RE: Auto Fill Comments

[Jean Louis]

* Drew Adams <drew.adams@oracle.com> [2020-11-27 05:19]:
> > The manuals should be rewritten because they are
> > incomprehensible.  Perhaps it was good in the eighties.
> 
> Maybe.  Or maybe programmers in the eighties
> read more? or better?
> 
> Would you like to contribute to rewriting or
> otherwise improving the manuals?  The job's
> open.
> 
> > It continues forever.
> 
> Yep, Emacs gives you a lifetime of learning,
> if you let it.
> 
> > Consider "face customisation" for instance,
> > which just means font.  
> 
> Bzzzzzzt!  Nope.  But thanks for playing.
> 
> > Nobody fuckin reads a manual with 17 nodes.
> 
> I do.  I'm not nobody.

The essential problem there in the manual is that there are many words
and new terminology that cannot be easily understood. That is why I
have proposed to have dictionary.el to be built in into Emacs, and
also much better integration and hyperlinking with the glossary.

Readers of books may know that sometimes one can read pages and pages
just to realize that nothing remained in the memory and this all can
come from misunderstood words. Same is for manuals or any text.

One could see that effect if one makes few examples from extreme
understandable text over medium understandable to extreme not
understandable text.

Something written in Klingon language would most probably be very
extremely not understandable for majority of people.

Sample text in Klingon

tlhIngan Hol yejHaD jInmol chu' 'oH Qo'noS QonoS'e'. tlhIngan Hol
jatlhwI'pu'vaD wIcherpu'. naDev vuDmey Daj lutmey Sagh je DalaDlaH,
'ach tlhIngan Hol DayajnIS. Hoch jar chovnatlh chu'
wImuch. yIlaD. yIqeq. tugh bIpo'choH.

Thus if manual would be written in Klingon, as extreme example of not
understandable text, English readers would have no use of it.

If manual would be written in the form of a well hyperlinked document
such would bring greater understanding to users. This requires
agreement among many people and is questionable if it becomes such
ever. Yet hyperlinks would enable user to quickly reference various
terms that helps in understanding.

Example of such well hyperlinked document is the Common Lisp
Hyperspec:
http://www.lispworks.com/documentation/HyperSpec/Body/03_dd.htm

Documentation of the Common Lisp Hyperspec if very complex but with
finely grained references hyperlinks it becomes pleasure to learn and
programmers can orient themselves easier in the apparently complex
document. That is example of complex instructions well prepared for
easier understanding.

Emacs TUTORIAL is good for beginners and without actually doing the
Tutorial one cannot easily understand the manual. By going through the
Tutorial also manual becomes easier to understand. Often I reference
to staff members to do the Emacs tutorial and so far I have not heard
complaints. But I also did not ask. What makes sense is that person
demonstrates that person can open file, work with it, save file and
send it by email. That is for me good indicator that Emacs Tutorial
was read and could be followed by person who is not programmer.

The Emacs manual compared to some other Emacs Manuals may not be
easiest to read and understand. It is comprehensible, it has glossary
and majority of references. And yet it is not proper for every group
of people.

Before reading the Emacs Lisp manual it is advisable to read
Emacs Lisp Introdution. Something similar to Emacs Lisp Intro to Emacs
could be Emacs Introduction, but I do not have reference and do not
know if that exists.

Books such as Mastering Emacs or O'Reilly book on Emacs are
proprietary, yet copies can be found online. 

Good way to start is also to analyze the reference card:
https://www.gnu.org/software/emacs/refcards/pdf/refcard.pdf

We speak of complex software here and in itself any manual will bring
easily misunderstood words and may block user's understanding. That is
why is advisable to use dictionaries, computer dictionaries, glossary
and to ask people for specific meanings which user cannot find.

If you have specific questions or you get stuck, please ask.

References to some simplified instructions on Emacs:

http://www.jesshamrick.com/2012/09/10/absolute-beginners-guide-to-emacs/

https://masteringemacs.org/article/beginners-guide-to-emacs

https://zoo.cs.yale.edu/classes/cs210/help/emacs.html

https://www.ozgurozkok.com/emacs-for-the-dummies/