Re: "Why is emacs so square?"

[Joost Kremers]

On Fri, Apr 24 2020, Richard Stallman wrote:
> [[[ To any NSA and FBI agents reading my email: please consider 
> ]]]
> [[[ whether defending the US Constitution against all enemies, 
> ]]]
> [[[ foreign or domestic, requires you to follow Snowden's 
> example. ]]]
>
>   > Org's biggest strength 
>   > is that the various features are tightly integrated.
>
> You may see that as an advantage, but I consider it a drawback. 
> The
> "tight integration" of these different features is an obstacle 
> to
> learning to use one of them, or even finding out about one of 
> them.

No, it really isn't. It's just the way the current documentation 
is set up that makes this difficult. (I know, I agree, I've been 
there.)

> Separate and integrated are not opposites.
> It is possible for several features to be integrated,
> in the sense that they work together _when you want that_,
> and also separate, in the sense that we describe each one 
> separately
> and you can learn about one without paying the slightest 
> attention
> to the others.

Again, that's all about documentation.

> I can see that that integration is useful -- but _the fact that 
> it
> applies only to "parts of Org mode"_ makes it also a a 
> limitation.
> It is a drawback that _only_ the modes that are "part of Org 
> mode" can
> integrate with these features -- and the rest of Emacs cannot do 
> so.
>
> Instead of dividing Emacs facilities and modes into the "Org
> first-class modes" and the "Org second-class modes", we should 
> make
> all modes equally able to integrate in these ways.

That sounds good in theory, but I'm really not sure what that 
would mean in practice. (I'm not entirely sure that you do either. 
;-) The reason Org's facilities can be so tightly integrated is 
because they all use the same Org syntax. Org files are just plain 
text files with a well-defined markup, after all.

As for integrating with the rest of Emacs, any part of Emacs is 
free to make use of this syntax as well, Org in fact provides 
libraries to make this easier. For example, I maintain a package 
for managing .bib files. It integrates with Org in that the user 
can add notes to bib entries, which are kept in Org files, and the 
user can maintain a reading list, also as an Org file, which then 
integrates with the user's TODO list and calendar, if s/he so 
wishes. I started this package long before I ever heard of Org 
mode, but it was easy to add this functionality once I realised it 
would be useful to do so.

So I believe the kind of integration you talk about is already 
possible, you just need to write the Elisp code to do it. In that 
way it doesn't differ from all the other facilities that Emacs 
provides: if I want to integrate Gnus and Eshell (whatever that 
would mean), I need to write Elisp code.

This of course contrasts with the integration of the various 
facilities that Org provides, because that only requires knowledge 
of Org's syntax. But I believe that's OK and fully expected: the 
things Org can do are closely related and many people *need* them 
to integrate well with each other. So integrating them should be 
easy.

On the other hand, what Gnus does has little to do with what 
Eshell does and scenarios where it would be useful to integrate 
them are probably rare. So it's OK that that's not so easy to do, 
as long as it's not impossible.

> > > It would make more sense to call them various different 
> > > modes. That they all use a certain way of formatting the 
> > > text may not be important to mention.
>
>   > Actually, it's crucial to mention that.
>
> People who want to use a specific one of these facilities don't 
> need
> to know that.

Sure, but I don't think it's a big cognitive burden for them to 
know that. Pointing out this fact in a couple of crucial places 
wouldn't take more than a sentence or two, with a reference to a 
section where it's all explained in more detail.

>  It is useful for those users who want to use more
> than one of these facilities together -- but that should be
> an advanced topic.

No, it shouldn't be billed as an advanced topic, for two reasons. 
First, it really isn't advanced at all: like I said, you really 
only need to know Org syntax in order to integrate these 
facilities, and you need to know Org syntax anyway to be able to 
use just one facility. Second, the tight integration is one of the 
reasons people are attracted to Org mode in the first place, so 
it's likely something people will look for in a manual early on.

Anyway, I think this subthread is slowly getting out of hand. :-) 
I don't believe our positions are as far apart as the discussion 
might suggest. I do agree with you and Eli that it would be very 
helpful if the Org manual were structured along the lines Eli 
suggested. I envisage an introductory section that clearly states 
the different use cases of Org and directs the reader to separate 
sections for each of them, which should all be written from the 
point of view of a new user, i.e., they shouldn't assume 
familiarity with any of the other use cases. At the same time, the 
introduction should mention Org's integrative nature and point the 
reader to relevant section(s), without labelling these as 
"advanced".

Whether and to what extent the Org code base should be modified, 
I'm not qualified to say, but given the limited resources, it 
isn't likely to happen anyway. Improving the documentation would 
be a much better investment of time.

--
Joost Kremers
Life has its moments