Re: Improving documentation of Org Mode integration into Emacs.

[Karl Fogel]

On 05 Jan 2022, Eli Zaretskii wrote:
> I think we should explain the issue concisely, and then provide
> specific instructions.  This text is IMO enough for the first 
> part:
>
> [...]
>
> Following that, we should provide a full, exhaustive list of all 
> such
> packages in Emacs core, each one with a corresponding URL 
> (mailing
> list, upstream repository with an issue tracker, etc.).  It might 
> be a
> good idea to have this list on a separate file, perhaps in etc/, 
> and
> only have CONTRIBUTE point to that file.

The attached patch puts a concise text in CONTRIBUTE as you 
described,
and adds an entry for Org Mode to the new "Externally maintained 
packages" section of admin/MAINTAINERS -- following Michael 
Albinius's and Protesilaos Stavrou's lead re Tramp and Modus 
Themes respectively.

The Org Mode entry is larger than the Tramp and Modus Themes 
entries, because the situation with Org Mode is more complex. 
That's why I've attached this patch for review instead of just 
committing it.

> I disagree.  If we don't provide a full list of such packages 
> with
> precise instructions, we will not make any significant progress:
> people would still need to ask us about the details, when they 
> aren't
> "smart" enough (or patient enough) to read the instructions that 
> teach
> them how to deduce that by themselves.  Moreover, as you have 
> found
> out already, there's no standard way such packages use to "plug"
> themselves into Emacs, so it's likely that any general 
> instructions we
> provide will be inaccurate in some cases.  An exhaustive 
> "cookbook" is
> much better, IMO, and is easier to maintain in the long run.  It 
> will
> also be shorter, which is a nice bonus, given today's "TL;DR"
> attitude.

That's persuasive; I think it's a good solution.  Feedback on the 
attached patch is welcome.  A couple of notes about it:

* Although the "Branches" section in CONTRIBUTE implies that these 
 changes should go on the "emacs-28" branch, this patch is 
 against "master" because Michael and Protesilaos committed their 
 changes to "master".  (I think it's all fine on "master" too, 
 and the guidance in CONTRIBUTE is a bit ambiguous about this 
 kind of change anyway.)

* In admin/MAINTAINERS, I did not list 
 "test/lisp/org/org-tests.el" as a 
 file maintained by the Org Mode project, because it looks like 
 that file exists only in Emacs and is not shipped with Org Mode. 

Best regards,
-Karl

0001-Document-external-maintenance-of-some-packages.patch
Description: [PATCH] Document external maintenance of some packages