From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Jean Louis Newsgroups: gmane.emacs.help Subject: Re: RE: Auto Fill Comments Date: Fri, 27 Nov 2020 06:32:22 +0300 Message-ID: References: <20201126160013.GD28931@tuxteam.de> <20201126182734.GA5175@tuxteam.de> <54331aa0-6a9a-4809-9f2d-88deee31558b@default> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 7bit Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="5790"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Mutt/2.0 (3d08634) (2020-11-07) Cc: Christopher Dimech , help-gnu-emacs@gnu.org To: Drew Adams Original-X-From: help-gnu-emacs-bounces+geh-help-gnu-emacs=m.gmane-mx.org@gnu.org Fri Nov 27 04:33:37 2020 Return-path: Envelope-to: geh-help-gnu-emacs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1kiUVt-0001P8-Jn for geh-help-gnu-emacs@m.gmane-mx.org; Fri, 27 Nov 2020 04:33:37 +0100 Original-Received: from localhost ([::1]:56368 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kiUVs-0008HN-MP for geh-help-gnu-emacs@m.gmane-mx.org; Thu, 26 Nov 2020 22:33:36 -0500 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:36070) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kiUVH-0008H5-2L for help-gnu-emacs@gnu.org; Thu, 26 Nov 2020 22:33:00 -0500 Original-Received: from static.rcdrun.com ([95.85.24.50]:43269) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kiUVF-0007JZ-1Y for help-gnu-emacs@gnu.org; Thu, 26 Nov 2020 22:32:58 -0500 Original-Received: from localhost ([::ffff:41.202.241.56]) (AUTH: PLAIN admin, TLS: TLS1.2,256bits,ECDHE_RSA_AES_256_GCM_SHA384) by static.rcdrun.com with ESMTPSA id 00000000002C000B.000000005FC07366.000033EB; Fri, 27 Nov 2020 03:32:53 +0000 Content-Disposition: inline In-Reply-To: Received-SPF: pass client-ip=95.85.24.50; envelope-from=bugs@gnu.support; helo=static.rcdrun.com X-Spam_score_int: -8 X-Spam_score: -0.9 X-Spam_bar: / X-Spam_report: (-0.9 / 5.0 requ) BAYES_00=-1.9, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001, URI_DOTEDU=1 autolearn=no autolearn_force=no X-Spam_action: no action X-BeenThere: help-gnu-emacs@gnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: Users list for the GNU Emacs text editor List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: help-gnu-emacs-bounces+geh-help-gnu-emacs=m.gmane-mx.org@gnu.org Original-Sender: "help-gnu-emacs" Xref: news.gmane.io gmane.emacs.help:125613 Archived-At: * Drew Adams [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/