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.devel Subject: Re: Convert README.org to plain text README while installing package Date: Sat, 11 Jun 2022 09:40:44 +0300 Message-ID: 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; charset=utf-8 Content-Transfer-Encoding: 7bit Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="38320"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Mutt/+ () (2022-05-21) Cc: emacs-devel@gnu.org To: Tim Cross Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Sat Jun 11 08:47:14 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 1nzutt-0009lC-Rm for ged-emacs-devel@m.gmane-mx.org; Sat, 11 Jun 2022 08:47:13 +0200 Original-Received: from localhost ([::1]:55330 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1nzuts-0007WH-C6 for ged-emacs-devel@m.gmane-mx.org; Sat, 11 Jun 2022 02:47:12 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:47650) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nzurW-0005Nm-VN for emacs-devel@gnu.org; Sat, 11 Jun 2022 02:44:47 -0400 Original-Received: from stw1.rcdrun.com ([217.170.207.13]:47331) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nzurU-0008Dh-Cu for emacs-devel@gnu.org; Sat, 11 Jun 2022 02:44:46 -0400 Original-Received: from localhost ([::ffff:102.81.237.245]) (AUTH: PLAIN admin, TLS: TLS1.3,256bits,ECDHE_RSA_AES_256_GCM_SHA384) by stw1.rcdrun.com with ESMTPSA id 0000000000083D5D.0000000062A439B8.00005812; Fri, 10 Jun 2022 23:44:08 -0700 Mail-Followup-To: Tim Cross , emacs-devel@gnu.org Content-Disposition: inline In-Reply-To: <87ilpbzlq5.fsf@gmail.com> Received-SPF: pass client-ip=217.170.207.13; envelope-from=bugs@gnu.support; helo=stw1.rcdrun.com X-Spam_score_int: -18 X-Spam_score: -1.9 X-Spam_bar: - X-Spam_report: (-1.9 / 5.0 requ) BAYES_00=-1.9, SPF_HELO_PASS=-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:291019 Archived-At: * 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: - adoc-mode -- it uses Markdown to display descriptions, this is similar case to using Org. However, it is pretty human readable. In any case, both Markdown or Org formats should be converted to plain text. - ample-theme -- uses Org for package description, I consider this description not human readable. It is Emacs package theme. It is not even related to Org mode, but user has to look into following: > * ample-theme.el > - A Light and Dark pair of themes for Emacs. > - Full colored gui and 256 color support only for now > ** Installation > If MELPA is set up: > #+BEGIN_SRC emacs-lisp > (package-install 'ample-theme) > (load-theme 'ample t) > #+END_SRC > ** If you get ugly colors in terminal: > #+BEGIN_SRC shell-script > # throw this in your ~/.bash_profile > export TERM="xterm-256color" > #+END_SRC > ** Ample-light-theme vs Ample-theme > [[http://i.imgur.com/86VLSV9.png]] In the above Org type of a description, author does not have a sense even to separate headings with the blank space. And how does "#+BEGIN_SRC emacs-lisp" help user to install the theme? Can we understand that user simply wants to install the theme and that "#+BEGIN_SRC emacs-lisp" is there not in right place, it is confusing. Author expects of the user to know what is Org mode in addition to installation of a theme, that is not proportional. Users installing themes may not need to know nothing about Org. 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/ More reviews: - 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 > #+html: GNU Emacs > #+html: GNU ELPA > #+html: #alt="GNU-devel ELPA" > #src="https://elpa.gnu.org/devel/corfu.svg"/> =M-x crdt-list-sessions= lists all sessions. it expects user to know that "=" is markup. It cannot help to full understanding. Users of CRDT need not be Org users. Even many Org users do not know full Org markup. - package ftable > #+TITLE: ftable.el > This package provides some convenient commands for filling a table, i.e., adjusting the layout of the table so it can fit in n columns. > [[./ftable.gif]] How is that tag "#+TITLE: ftable.el" helping user? We cannot assume that users will know about the meaning of "#+" and why shall package description again repeat the title of the package, that is already in the header of the package. And how am I supposed to know what is "[[./ftable.gif]]" and where it is? I have no access to it. It communicates zero information to user. It confuses user. Usability would be greatly improved if there would be simple link to the image, as the package description is anyway showing links correctly. - package leaf -- this one completely expects user to know about Org markup. It has terrible readibility score. - package logos -- until user comes to read anything about description, must go through this garbage: > #+title: logos.el: simple focus mode for Emacs with page breaks or outlines > #+author: Protesilaos Stavrou > #+email: info@protesilaos.com > #+language: en > #+options: ':t toc:nil author:t email:t num:t > #+startup: content > #+macro: stable-version 0.3.0 > #+macro: release-date 2022-03-30 > #+macro: development-version 0.4.0-dev > #+macro: file @@texinfo:@file{@@$1@@texinfo:}@@ > #+macro: space @@texinfo:@: @@ > #+macro: kbd @@texinfo:@kbd{@@$1@@texinfo:}@@ > #+export_file_name: logos.texi > #+texinfo_filename: logos.info > #+texinfo_dir_category: Emacs misc features > #+texinfo_dir_title: Logos: (logos) > #+texinfo_dir_desc: Simple focus mode with page breaks or outlines > #+texinfo_header: @set MAINTAINERSITE @uref{https://protesilaos.com,maintainer webpage} > #+texinfo_header: @set MAINTAINER Protesilaos Stavrou > #+texinfo_header: @set MAINTAINEREMAIL @email{info@protesilaos.com} > #+texinfo_header: @set MAINTAINERCONTACT @uref{mailto:info@protesilaos.com,contact the maintainer} > #+texinfo: @insertcopying - package org-modern -- author did not check if those links work. Example communication by author: > The screenshots shows [[file:example.org][example.org]] with > =org-modern-mode= turned on and off Links appear there, however, the file example.org is not clickable, it could easily be made properly clickable. - package osm -- not readable due to Org settings in package description. Those settings do not belong to package description. - package pdf-tools -- same thing, user is supposed to read description. Things like below are confusing: > :PROPERTIES: > :CREATED: [2021-12-29 Wed 18:34] > :ID: 5a884389-6aec-498a-90d5-f37168809b4f > :EXPORT_FILE_NAME: index > :END: Those tags are by no means relevant to package description. User wants PDF tools, and what is user supposed to mean about the ID hashes and what else... - package posframe -- readability is minimized due to usage of heavier Org markup - package svg-lib -- user cannot click on provided screenshots in Org markup. Why do that? Provide correct links. - package system-packages -- Org markup degrades human readability I have reviewed just some of packages installed on my side. There may be many others. Readability and usability is greatest issue in computing and helping user with understanding. One shall compare Org package descriptions to so many other packages without Org and find out how Org greatly degrades readability and thus understanding on what that package is about and how to use it. -- Jean Take action in Free Software Foundation campaigns: https://www.fsf.org/campaigns In support of Richard M. Stallman https://stallmansupport.org/