Limitations on using Org mode in buffers mixing Org markup with non-Org markup (was: Convert README.org to plain text README while installing package)

[Ihor Radchenko]

Eli Zaretskii <eliz@gnu.org> writes:

>> I do not think that Org will support major user changes in Org syntax
>> any time soon or in future. At least, there is no intention to guarantee
>> such support.
>
> Neither of the other markup modes is being proposed for viewing and
> editing documents that were not originally edited under those modes.
> By contrast, there's a fraction of Emacs contributors and developers
> who repeatedly suggest to use Org for documents that were not
> originally written in Org.  A notable example (not the only one) is
> recent discussions of turning on Org when visiting NEWS files.

Do I understand correctly that users would like to have some Org
features (like fontification) in text that partially follows Org markup,
but not fully?

If so, Org mode cannot be used there as a major mode. non-Org parts of
syntax will cause undefined behavior. Which is to be expected as
major mode (every major mode) uses certain assumptions about the text in
buffer. Even text-mode will behave weirdly if binary data is mixed with
plain text. Org major mode expects text in buffers to be using Org
markup.

On the other hand, some parts of Org functionality are available in a
form of minor modes or individual commands. As usual, minor modes are
less demanding on the text in buffer.

AFAIK, we have the following functionality exposed to non-Org buffers:
- org-open-at-point-global/org-insert-link-global commands
- orgtbl-mode to edit tables, which use Org table syntax outside Org mode
- (ELPA) orgalist mode to edit lists written using Org list syntax outside Org 
mode
- (MELPA) org-msg mode to edit and send messages using Org markup (it
  exports to html mime parts)
- outline minor mode share a lot of functionality with Org without
  relying on Org markup. AFAIK, some Org features have been ported back
  to outline mode as well.

This dedicated functionality is designed to be used outside Org markup
buffers.

People who request Org mode to be used in non-Org buffers probably have
a specific subset of useful Org features in mind. I'd ask them which
features they want to and then consider exposing them out from Org mode
into minor mode (if not yet covered by the above).

> If you think these ideas are problematic from the POV of Org
> developers, please voice this opinion whenever such proposals are
> brought up.  Those proposals, and in general the proposals to use Org
> widely in unrelated contexts, is what I had in mind all the time in
> this discussion.  Perhaps now you can better understand some of my
> comments and responses.

I do understand you comments now. However, I do not follow emacs-devel
closely. So, it would be more efficient to CC Org ML in such
discussions.

> For example, what is your opinion of using Org markup in email
> messages?  There are a lot of examples of that, both here and on the
> bug tracker.  People use Org markup and Org-style code blocks quite a
> lot, and reading that is always jarring to me.  For some reason,
> people assume that I read my email in Org mode or some derivative of
> Org.

I also noticed that. AFAIU it is sometimes the text part sent by org-msg
and sometimes people just using Org syntax, because why not.

I personally do not see a problem with using Org markup to indicate code
blocks. At least, it is not much different from markdown some other
people are using in emails. Even without Org mode, such markup is
perfectly readable. AFAIK, there is no convention on indicating
"special" parts of plain text email (e.g. code snippets) in mailing
lists.

The convention for indicating "markup" in emails is associating the
correct mime-type to the message part. If it is html, the mail agent
should render html. If it is Org, Org can be rendered. If it is plain
text, the behavior is undefined in principle - people sending plain text
should make the text readable as plain text in text-mode (Org can be
made readable usually, but same can be said for e.g. Markdown).

Best,
Ihor