Re: Convert README.org to plain text README while installing package

[Jean Louis <bugs@gnu.support>]

* Tim Cross <theophilusx@gmail.com> [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: <a href="https://www.gnu.org/software/emacs/"><img alt="GNU Emacs" src="https://github.com/minad/corfu/blob/screenshots/emacs.svg?raw=true"/></a>
> #+html: <a href="http://elpa.gnu.org/packages/corfu.html"><img alt="GNU ELPA" src="https://elpa.gnu.org/packages/corfu.svg"/></a>
> #+html: <a href="http://elpa.gnu.org/devel/corfu.html"><img
> #alt="GNU-devel ELPA"
> #src="https://elpa.gnu.org/devel/corfu.svg"/></a

- package crdt -- pretty confusing when reading that Org, something
  like this:

> =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/