Ihor Radchenko <yanta...@posteo.net> writes:
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
So, the first order of business is to ensure that all
ob-doc-<lang>.org files on Worg are complete by i) creating
missing files, ii) editing incomplete files, and iii) checking
complete files?
Then, once Worg holds complete documentation for each built-in
language, port them all to the manual?
If so, this seems like a good work flow because the documentation
on Worg can be easily reviewed by all before it is ported to the
manual.
I'm happy to volunteer and will start by creating
ob-doc-<lang>.org files for undocumented and unmaintained
languages: comint, F90, forth, sed, ocaml, ruby, and sass. I
don't know or use any of these languages. If someone else does
know one and would like to jump in, LMK.
All the best,
Tom
--
Thomas S. Dye
https://tsdye.online/tsdye
