From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Tim Cross Newsgroups: gmane.emacs.devel Subject: Re: Convert README.org to plain text README while installing package Date: Sun, 12 Jun 2022 12:23:57 +1000 Message-ID: <87sfoawp1u.fsf@gmail.com> References: <87h74ztshe.fsf@gmx.de> <871qw31ois.fsf@yahoo.com> <8735gj4ceo.fsf@gnu.org> <87ee038ipt.fsf@gmx.de> <87o7z61v59.fsf@gmail.com> <87ilpbzlq5.fsf@gmail.com> Mime-Version: 1.0 Content-Type: text/plain Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="20178"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: mu4e 1.7.27; emacs 28.1.50 Cc: emacs-devel@gnu.org To: Jean Louis Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Sun Jun 12 05:15:35 2022 Return-path: Envelope-to: ged-emacs-devel@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 1o0E4d-00054f-JK for ged-emacs-devel@m.gmane-mx.org; Sun, 12 Jun 2022 05:15:35 +0200 Original-Received: from localhost ([::1]:39456 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1o0E4c-0005SY-2G for ged-emacs-devel@m.gmane-mx.org; Sat, 11 Jun 2022 23:15:34 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:41746) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1o0E3p-0004lo-UW for emacs-devel@gnu.org; Sat, 11 Jun 2022 23:14:46 -0400 Original-Received: from mail-pj1-x102a.google.com ([2607:f8b0:4864:20::102a]:39789) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1o0E3o-0000ZU-41 for emacs-devel@gnu.org; Sat, 11 Jun 2022 23:14:45 -0400 Original-Received: by mail-pj1-x102a.google.com with SMTP id q12-20020a17090a304c00b001e2d4fb0eb4so5750428pjl.4 for ; Sat, 11 Jun 2022 20:14:43 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=references:user-agent:from:to:cc:subject:date:in-reply-to :message-id:mime-version; bh=8Z7fSWBa8g6PATHO0whV0RKsWsponbB/FfpuKoqmD1E=; b=H20XimJV+r8h56lT7G8Jn5Fp/Oq1Hx/kgGHJnIjTDrey9+VlNvupPiHaKcwUxx9RYA VZXFuTWD3tcAcfcLx1FzTrxtNgwQ5x/q2lWYjpCoI5L5hs+u51kUHTozH1/O4Fne7yBU JvicI0kDbGPIgankmd7fLqt4+t6k83uRheen9wLT/kyAxgtjWQEsNLF+x5uVh53COZSe 1OIh7iR5ODriOEoIMMBz5AZwrggXIFQnMob1FOHtR10YjoJFbmOe5TnakE1x0METV890 PYt6IqpFRcjco54irFR6UtG0lrfIawRNOn4+RcRoE/FCSZ4WXdoNReFcgpA1plmE0HgH hyOg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:references:user-agent:from:to:cc:subject:date :in-reply-to:message-id:mime-version; bh=8Z7fSWBa8g6PATHO0whV0RKsWsponbB/FfpuKoqmD1E=; b=qSEAOv0BYM2LmVXI/vuXQ7A+gii9od4jBr4pohXDK45G76rHmuKILAXvcIhRrrmdY5 3jj7+tvk1iVXzBsVe96Oxis5AAFuCDOJvI0nf8GjtvQvRZJqRqfDSHY9fsZgs5Z6KVBe XBdxiflxrwIy0XHg2ySCxOcjLDOp4J3TAqrhPTTazT+FbyHBznIB4NA2ffmdWNL7CiVo WJ7ym43YbSbRaUNv/0pvceD39VHta1YWYWB/qDjKF1cm5B/bbvp/+CxYYdQzyqQ/zWUi D1QK1WyKaWClcGzwR+6R90NBMf7ScbFvz9jIrc4mz/fnTqOPuTFDk9QT49acKkGXSzHS keoA== X-Gm-Message-State: AOAM531573C6MG+ui+anYNdmDdjJXQSu8CcSWN5BHjjvp8ScEYNCSo1g 8PT04utgPNjCBgAX6+iq1mJ7D8UKGAo= X-Google-Smtp-Source: ABdhPJySStPmhYpLxin3qAR1+ELr6ge8wPSlcyp5L6yEsAl7Ic+9/6o+DFEzerCo+Qb5Parm/NwuuQ== X-Received: by 2002:a17:902:d592:b0:161:3bf4:9047 with SMTP id k18-20020a170902d59200b001613bf49047mr44954140plh.137.1655003682555; Sat, 11 Jun 2022 20:14:42 -0700 (PDT) Original-Received: from dingbat (2001-44b8-31f2-bb00-63fa-329c-dbc6-d47e.static.ipv6.internode.on.net. [2001:44b8:31f2:bb00:63fa:329c:dbc6:d47e]) by smtp.gmail.com with ESMTPSA id y2-20020a17090a600200b001cd4989feebsm4255153pji.55.2022.06.11.20.14.41 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sat, 11 Jun 2022 20:14:42 -0700 (PDT) In-reply-to: Received-SPF: pass client-ip=2607:f8b0:4864:20::102a; envelope-from=theophilusx@gmail.com; helo=mail-pj1-x102a.google.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, FREEMAIL_FROM=0.001, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.io gmane.emacs.devel:291058 Archived-At: Jean Louis writes: > * Tim Cross [2022-06-08 09:57]: >> Please give me an example of org mode 'not make space where it would be >> otherwise required'. Can you provide a single example of org mode >> syntax which is not readable in any text editor. There are quite a few >> projects on Github/Gitlab which have readme.org files - can you point to >> one which cannot be read with a plain text editor? > > Hello Tim, > > my response time is not so fast. > > I am now reviewing package descriptions: > > Recommended for everybody to read: > > Usability 101: Introduction to Usability > https://www.nngroup.com/articles/usability-101-introduction-to-usability/ > > Usability Testing 101 > https://www.nngroup.com/articles/usability-testing-101/ > I gues sour differences here are that you have conflated issues of readabiity and usability into the definition of plain text. Few of the criticisms you have raised IMO are specific to org mode or due to org modes syntax. Many of them are due to the individual author's layout and not the result of org mode syntax. You can also write documents which are very difficult to read using just plain ASCII. They are both plain text. I also think you are over-stating the difficulty of reading the raw org file contents. While I would agree they are asier to read when correctly formatted, they are not impossible to understand without it. For example, to say something like > package corfu, totally not human readable as it begins with: > #+title: corfu.el - Completion Overlay Region FUnction > #+author: Daniel Mendler > #+language: en > #+export_file_name: corfu.texi > #+texinfo_dir_category: Emacs > #+texinfo_dir_title: Corfu: (corfu). > #+texinfo_dir_desc: Completion Overlay Region FUnction is I think totally over stating the situation. I showed the above to someone who is not a technical person and only uses computers for email, web and office work and they were able to understand it perfectly well. They didn't know what the texinfo lines meant, but they understood what the title was, who the author was, the language and even the texinfo_dir_desc being a description. I think most people are far more capable at reading such information than you assert. They might not understand all of it, but then again, I often read documents where I don't understand all of it. The point is, there is a big difference betrween being able to read contents and understand them. As a comparison, consider some RFCs which you mentioned previously. I've read RFCs which perfectly comply with the formatting you referenced that were (to me) totally unintelligible. Sometimes this is because the writing is poor or the concepts are too alien or it is simply too complicated for my limited understanding. However, this is still a plain text document. For me, a file is plain text if you can edit and save it using just a plain text editor and the file will still be valid. I also consider HTML files to be plain text, (but far less readable than org files). On the other hand, *.docx are not plain text and cannot be edited with a plain text editor, saved and still be valid. Likewise, other formats which use non-printable control characters are not plain text. I will try to be clearer when I say something is plain text. Readability and useability are separate from file formats - they are a higher, but related, concern. Plain text does not imply anything about readability or usability other than a plain text file can be opened and physically read using a plain text editor or a utility like 'cat'. The ability of the individual to interpret that information does not affect whether it is plain text. If, for example, you write lots of HTML, an HTML file is easily understood when displayed with cat. Of course, appropriate formatting within a plain text document can affect how easily the document can be read and I think it is good to try and format the document to be as easy to read as possible. However, for org mode, this is really under the control of the author. Org data files can be formatted in a way which makes them easier to read and there are various Emacs settings which can be used which affects this (wrap, visual line mode, adding blank lines at the end of sections etc). The point is, many of your criticisms are not due to org syntax or org enforced forrmatting, which is one reason I disagree with assertions that org files are not plain text. I'm sure this is apoint we will never agree on, so happy to leave it there.