Re: [TASK] Move babel backend docs from WORG to Org manual

["Thomas S. Dye" <tsd@tsdye.online>]

Ihor Radchenko <yantar92@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