Re: Org mode and Emacs

[Eli Zaretskii <eliz@gnu.org>]

> From: "T.V Raman" <raman@google.com>
> Cc: Po Lu <luangruo@yahoo.com>,  Ihor Radchenko <yantar92@gmail.com>,  Payas
>  Relekar <relekarpayas@gmail.com>,  emacs-devel@gnu.org
> Date: Mon, 26 Sep 2022 06:58:31 -0700
> 
> I think there are two (perhaps more) aspects to writing good
> documentation and accepting / making contributions:
> 
> 1. The basics -- write a paragraph or two describing some feature.
> Orthogonal to that and here is where each format bites in different
> ways:
> 
> 2. Integrating that contribution into the main corpus of the work --- at
>    the write place, with the right surrounding context, generating the
>    right table-of-contents and menus (a running nightmare in Texinfo if
>    you dont set things up right at the beginning) and so on.
> 
> I think (2) might likely contribute negatively to  (1) happening more
> often.

I think the division you suggest is somewhat artificial.  Unlike man
pages, Info manuals are not a collection of loosely-couples articles;
instead, the sections in a good Info manual are always connected and
context-aware.  Thus, writing the documentation for the manual should
_always_ start by studying the "neighborhood" in which that new stuff
will live.  IOW, putting the new text in context is not an
after-thought, it should be considered prior to writing.

I don't know what you allude to as "running nightmare in Texinfo".
Adding a new node to a manual is since long ago a very simple process:
just add it and make sure the @menu of the parent node (if there is
one) is updated to have the new node in its correct place.  That's it.

> So rather than arguing about formats (and it's been pointed out already
> that there are tools for automatic conversion) we should perhaps:
> 
> A. Create a simple content repository where contributors can check-in
>    their small to medium contributions in the format of their choice
>    (limited to a few open formats) along with the meta-data 
> B. A small group of more experienced volunteers take on the task of
>    incorporating those contributions into the main work.

Most contributors to Emacs already write pretty good Texinfo; adding
finishing touches to that and fixing a few style or markup mistakes is
already being done in the background by those who spot those blunders.
So I think we already have the above in place.