Dear all,
In my talk https://emacsconf.org/2024/talks/org-update, one of
the tasks
I announced was moving babel documentation from WORG to Org
manual.
Here, I would like to details what should be done for that task.
This is a big task, but we can split it into much smaller and
simpler tasks.
I recommend taking documentation from a single language to get
started.
Multiple volunteers (if any) may work on other languages in
parallel.
Please tell us which language you are working on to avoid
conflicts.
Also, feel free to ask anything here or in any other
communication
channel (IRC, Matrix, OrgMeetup) if there are difficulties.
The general idea is to port files from
https://git.sr.ht/~bzg/worg/tree/master/item/org-contrib/babel
into Org
manual.
At the end, we should have all the ob-<lang> files from
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/tree/lisp
documented in the manual.
The documentation at various stages of completeness is listed in
https://git.sr.ht/~bzg/worg/tree/master/item/org-contrib/babel/languages
(ob-doc-<lang>.org).
For each built-in language, we will need to:
1. Find ob-doc-<lang>.org file, if any
2. Make sure that the documentation conforms to
https://git.sr.ht/~bzg/worg/tree/master/item/org-contrib/babel/languages/ob-doc-template.org
3. If it does not, we at least need to indicate undocumented
sections
4. If possible, may also document the missing parts
4.1. Sometimes, the language implementations in
lisp/ob-<lang> miss
features from the checklist. Such problems should be reported
as
bugs for easier tracking.
5. The cleaned up documentation should be ported to Org
manual. Tentatively, we can follow the structure of export
backends
as in https://orgmode.org/manual/Exporting.html
6. If there is no documentation at all, it should be written