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

[Eli Zaretskii <eliz@gnu.org>]

> From: Ihor Radchenko <yantar92@gmail.com>
> Cc: theophilusx@gmail.com,  acm@muc.de,  emacs-devel@gnu.org
> Date: Sat, 11 Jun 2022 11:52:05 +0800
> 
> > 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.

Thank you, I think this is a very good summary.  I hope some of these
issues could be worked on and improved in the future.

> > 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.

For a serious discussion of this example, I'd need more detail about
the aspects you mentioned above (it is not trivial to deduce them from
looking at the top levels of org-forward-paragraph).  Specifically:

  . how does paragraph definition depend on context in Org, and what
    are the possible definitions in the existing contexts?
  . why don't paragraph-start and paragraph-separate fit Org, and can
    we come up with a small number of additional variables that would
    augment these two so that the built-in forward-paragraph could be
    extended to cover Org?

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

The better way, IMO, is this:

  . try to find a way of extending the built-in forward-paragraph to
    cover the Org use cases, by adding variables in addition to the 2
    existing ones (I don't yet understand why "regexps do not cut it
    for Org mode -- it sounds like a very strong assertion)
  . if the above doesn't work, make forward-paragraph work through
    forward-paragraph-function, so that Org could define its own
    function
  . in any case, the add-on convenience features of
    org-forward-paragraph should be provided as options that the user
    can control

My main concern is that forward-paragraph is used when editing the
purely textual parts of an Org document, and when used there, casual
users of Org will expect it to behave as the command behaves in plain
text.  Any deviation from the behavior of the built-in command will
confuse such users when they edit the plain-text parts, and should
therefore be avoided.

> 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

Each of these (and other examples you provided) should require a
separate serious discussion.  Let's take open-line as an example.  It
is basically the built-in open-line, unless org-special-ctrl-o is
non-nil.  A trivial extension of the built-in command could have
prevented the need to remap.  (And why does the support for tables in
org-open-line need to be turned on outside of orgtbl-mode?)

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

IMO, org-yank is sufficiently different to justify not taking over the
built-in command.  Again, consider a user who edits the plain-text
portions of an Org document and expects the "usual" behavior of C-y.

> >> 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.

Each of these commands should be discussed separately, and the best
solution found and implemented.  There's no single answer to that
question for all of these remapped commands.  But remapping should be
avoided as much as possible; see below.

> > 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.

When fill-paragraph-function and other means of customizing a command
to the particular mode make sense, they will not need to be noticed,
because they will do what the users expect.  Moreover, customizing the
behavior of commands through those variables has a couple of important
advantages:

  . it doesn't use remapping, so it doesn't stick out and bother
    conscientious Emacs users, who are used to study unfamiliar
    commands before using them
  . they don't require separate documentation, apart of saying that
    paragraph-start and paragraph-separate can be modified by modes as
    appropriate -- all the rest of the command's documentation is
    still intact and easily grasped in the context of any mode (this
    is also one more reason why "niceties" like special behavior
    inside tables should be separately controlled)

> 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.

My point is that there are better ways of customizing the behavior of
a built-in command.  Org is now an integral part of Emacs, so it
should implement these customizations in ways that are available to a
core package; remapping is basically a tool used by unbundled packages
that cannot affect the core in any way.

> >> 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?

No, I'm saying that, sadly, we have no real control on what the
developers of unbundled packages decide to do.  Thus, what you see
there is the evidence of our lack of control more than anything else.