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

[Ihor Radchenko]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Ihor Radchenko <yantar92@gmail.com>
>> Cc: theophilusx@gmail.com,  acm@muc.de,  emacs-devel@gnu.org
>> Date: Thu, 09 Jun 2022 17:15:05 +0800
>> 
>> > Are you sure this is always true?  There are several dozens of
>> > remapped commands; did you audit all of them?
>> 
>> I have audited a couple of them and relied on a good faith to other Org
>> devs + absence of bug reports relevant to the raised concern.
>> Rather then re-checking the remapped functions, I'd rather just fix any
>> concrete bug reports about misbehavior, if such reports arise.
>
> Didn't this discussion raise such "bug reports"?  Why not consider
> what several people here said as such a bug report?  The difference is
> that these reports come from people who use Org rarely, so the
> concerns are different.  But if the Org developers want to have Org
> adopted more widely, I think they should listen to these concerns, not
> reject them.

To clarify, it is metally difficult to process bug reports raised in
such discussions because they are often entangled with quite negative
attitude and much more broad claims.

What I have summarised so far from the discussions:

1. Org mode shadows default C-S-<up>/C-S-<down> bindings.

   This can be solved in two ways:
   a. Change org-support-shift-select to t by default + fix the fact
      that org-support-shift-select is actually ignored by
      C-S-<up>/<down>.
   b. Disable Org mode arrow bindings by default and move them to a
      dedicated minor-mode / setting.
      (This will make existing Org users angry)

   Note that I do not see C-c / and C-c C-s as a bug. The first one is
   not recommended for major-mode but allowed. C-c C-s is dedicated to
   major modes.

2. Org mode binds too many keys

   The solution can be disabling those keys and moving them to dedicated
   minor modes / settings.

   After thinking, I do not like the idea of enabling some keys
   depending on the presence absense of tables/source blocks inside the
   Org file. This will not solve the issue in the files actually
   containing all those and may surprise users.

3. Some of the context-dependent Org command names are confusing as they
   do not reveal what the command does.

   The solution is to rename those commands to something more
   meaningful. Totally doable.
      
4. Org remaps some of the default commands.
   I can see how it can be confusing, but do not see it as a critical
   issue. See my response below.

5. Org mode is too slow to load.
   I do not see an easy way to resolve this apart from general
   refactoring and modularizing. Profiling is not very helpful in this
   specific case, unfortunately. At least, my profiling skills are not
   good enough.

>> While I understand the possible fear of unexpected or unnatural
>> behavior of the remapped command, I'd like to point out that command
>> behavior can span over quite a significant range even without remapping.
>> Just the fact that some major mode does not use remapping, does not mean
>> that you are guaranteed to get the normal command behavior.
>
> Most major modes don't remap global and frequently-used commands.
> Those that do are problematic, and should be fixed rather than be used
> as examples of what's "kosher".

Let's take one example: org-forward-paragraph that is remapping
forward-paragraph.

The docstring is:

Move forward by a paragraph, or equivalent, unit.
...
The function moves point between two structural
elements (paragraphs, tables, lists, etc.).

It also provides the following special moves for convenience:

  - on a table or a property drawer, move to its beginning;
  - on comment, example, export, source and verse blocks, stop
    at blank lines;
  - skip consecutive clocks, diary S-exps, and keywords.

In Org mode, there is no single definition of a paragraph. The
paragraphs or equivalent syntax elements are context-depended and we
have to use parser to know where to move.

The default forward-paragraph can only be controlled by paragraph-start
and paragraph-separate regexps. Both are not sufficient to cater Org
mode. Regexps do not cut it for Org mode.

Hence, the built-in version of forward-paragraph is not usable in Org
mode. If we did not remap it, forward-paragraph would not really move by
paragraph, as it is understood by human. It would be more confusing than
org version of the command.

If you know a better way to resolve the described limitation, please let
me know.

Similar limitations motivated
<remap> <backward-paragraph>    org-backward-paragraph
<remap> <backward-sentence>     org-backward-sentence
<remap> <comment-dwim>          org-comment-dwim
<remap> <forward-paragraph>     org-forward-paragraph
<remap> <forward-sentence>      org-forward-sentence
<remap> <move-beginning-of-line> org-beginning-of-line
<remap> <move-end-of-line>      org-end-of-line
<remap> <delete-indentation>    org-delete-indentation

The following functions have a natural fallback to default behavior and
might be moved to minor-modes enabled by default. However, their default
behavior is context dependent and motivated by the lack of flexibility
of the built-in equivalents. Similar to the above functions.

<remap> <open-line>             org-open-line
<remap> <move-beginning-of-line> org-beginning-of-line
<remap> <move-end-of-line>      org-end-of-line

The following functions might be implemented using built-in Emacs
functionality:

<remap> <transpose-words>       org-transpose-words
could use find-word-boundary-function-table

<remap> <fill-paragraph>        org-fill-paragraph
appears to be redundant as we do set fill-paragraph-function


<remap> <yank>                  org-yank
may be instead implemented using yank-handler property (it takes care
about adjusting level of the inserted headlines), but not completely. We
cannot control properties of text from outside of Org mode and thus the
functionality cannot be fully implemented using built-in Emacs features

The following commands are providing convenience self-alignment
functionality and protect from accidental editing of invisible text
(AFAIK, this issue is not addressed by Emacs):
<remap> <kill-line>             org-kill-line
<remap> <delete-backward-char>  org-delete-backward-char
<remap> <delete-char>           org-delete-char
<remap> <self-insert-command>   org-self-insert-command

I am not sure how to achieve equivalent functionality using built-in
Emacs customisations.

The following functions are convenience building for prople coming from
outline mode. I do not see any problem here.

<remap> <outline-backward-same-level> org-backward-heading-same-level
<remap> <outline-demote>        org-demote-subtree
<remap> <outline-forward-same-level> org-forward-heading-same-level
<remap> <outline-insert-heading> org-ctrl-c-ret
<remap> <outline-mark-subtree>  org-mark-subtree
<remap> <outline-next-visible-heading> org-next-visible-heading
<remap> <outline-previous-visible-heading> org-previous-visible-heading
<remap> <outline-promote>       org-promote-subtree
<remap> <outline-show-branches> org-kill-note-or-show-branches
<remap> <outline-show-children> org-fold-show-children
<remap> <outline-show-subtree>  org-fold-show-subtree

>> Some major modes rely on post-command-hook instead of remapping, which
>> not only modifies the original command behavior in unspecified ways, but
>> is also not directly visible from the mode bindings. Or consider changes
>> in filter-buffer-substring-function and how it can modify killing text.
>
> And that is in your opinion a Good Thing?  I don't think it is, and
> therefore don't consider such problematic behavior a good example for
> development.

Maybe. But then we need a more "appropriate" way to implement the
functionality Org provides. See the above.

>> So, I'd say that your concern is not really justified.
>
> ??? Just because "others do that"?

>> There is generally no reliable way to tell if an arbitrary major
>> mode modifies standard command behavior just by looking at its key
>> bindings. You have to rely on faith and report bugs if you stumble
>> upon them.
>
> I don't see how this solves the concerns.  We should still try to
> minimize such problematic behaviors as much as possible.

I'd like you to focus on the last example with
filter-buffer-substring-function or on the ability for major mode to
customise fill-paragraph-function or paragraph-separate, etc. Those
changes can alter the default commands drastically. Yet, they will not
be noticeable by users from looking at the M-x describe-bindings.

I do not say that major modes should change the default behavior in
unexpected ways. Rather the opposite - major modes should adjust the
default commands to behave more expectedly within the major mode
context. However, remapping is by no means an indication that a major
mode is going to change things unexpectedly. Its neither sufficient nor
required condition.

>> > No, not IME.  Show me another general-purpose editing mode that
>> > defines so many key bindings.  The only modes that get close are those
>> > where text is read-only, so normal editing is impossible anyway.
>> ...
>> Auctex binds a decent number of key-bindings. VHDL mode binds even
>> more (I just looked into one of the largest mode built-in prog
>> modes). markdown-mode binds over 100 keys not counting prefix maps.
>
> Two of these aren't part of Emacs, and VHDL is an example of
> programming language, where text is not really for human consumption.

I get your point on VHDL. However, I am not sure why you reject the
non-built-in examples. Are you implying that text modes outside Emacs
core are worse than built-in? At least Auctex is largely popular among
users and yet I have never seen as many complaints about Auctex
complexity as I do for Org (I may be biased).

Auctex and markdown-mode deal with similar editing tasks with Org mode.
The fact that they also use large number of key bindings is an
indication that they are really needed for editing complex documents.

>> >   And even those leave alone basic movement commands, like C-S-<up>
>> > which Alan mentioned.
>> 
>> C-S-<up> is not a basic movement command.
>
> Of course, it is: it moves by paragraphs.

Nope. It is unbound command working because of key translation:

C-<down> (translated from C-S-<down>) runs the command
forward-paragraph (found in global-map), which is an interactive
native compiled Lisp function in ‘paragraphs.el’.

>> By default, it is activating
>> region. Without shift-select-mode, it is not bound to anything.
>
> But shift-select-mode is on by default.

Fair point.

Best,
Ihor