From: Ihor Radchenko <yantar92@posteo.net>
To: emacs-orgmode@gnu.org
Subject: [TASK] Move babel backend docs from WORG to Org manual
Date: Tue, 10 Dec 2024 19:52:32 +0000 [thread overview]
Message-ID: <87zfl3uxhb.fsf@localhost> (raw)
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
Once we are done with individual languages, we will need to:
1. Review, update, and double check
https://git.sr.ht/~bzg/worg/tree/master/item/org-contrib/babel/languages/lang-compat.org
2. Write documentation about writing a new backend as in
https://git.sr.ht/~bzg/worg/tree/master/item/org-contrib/babel/languages/ob-doc-template.org
and
https://git.sr.ht/~bzg/worg/tree/master/item/org-contrib/babel/ob-template.el
3. Refer to (or move) this documentation from Org manual
4. Review
https://git.sr.ht/~bzg/worg/tree/master/item/org-contrib/babel/header-args.org
and possibly merge it with Org manual
5. There will be some non-builtin language docs available at the end.
We will need to move this documentation to relevant packages (is
there are), to org-contrib, or obsolete
6. Review the remaining files in https://git.sr.ht/~bzg/worg/tree/master/item/org-contrib/babel
List of built-in languages:
- [ ] ob-C
- [ ] ob-R
- [ ] ob-awk
- [ ] ob-calc
- [ ] ob-clojure
- [ ] ob-css
Note: This is a stub. We might later discuss if it can be generalized.
- [ ] ob-ditaa
- [ ] ob-dot
- [ ] ob-emacs-lisp
- [ ] ob-eshell
- [ ] ob-forth
- [ ] ob-fortran
- [ ] ob-gnuplot
- [ ] ob-groovy
- [ ] ob-haskell
- [ ] ob-java
- [ ] ob-js
- [ ] ob-julia
- [ ] ob-latex
- [ ] ob-lilypond
- [ ] ob-lisp
- [ ] ob-lua
- [ ] ob-makefile
- [ ] ob-matlab
- [ ] ob-maxima
- [ ] ob-ocaml
- [ ] ob-octave
- [ ] ob-org
- [ ] ob-perl
- [ ] ob-plantuml
- [ ] ob-processing
- [ ] ob-python
- [ ] ob-ruby
- [ ] ob-sass
- [ ] ob-scheme
- [ ] ob-screen
- [ ] ob-sed
- [ ] ob-shell
- [ ] ob-sql
- [ ] ob-sqlite
--
Ihor Radchenko // yantar92,
Org mode maintainer,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>
next reply other threads:[~2024-12-10 19:51 UTC|newest]
Thread overview: 8+ messages / expand[flat|nested] mbox.gz Atom feed top
2024-12-10 19:52 Ihor Radchenko [this message]
2024-12-10 20:45 ` [TASK] Move babel backend docs from WORG to Org manual Thomas S. Dye
2024-12-13 18:50 ` Ihor Radchenko
2024-12-13 18:54 ` Ihor Radchenko
2024-12-13 21:39 ` Thomas S. Dye
2024-12-14 6:58 ` [TASK] Documenting ob-fortran, ob-forth, ob-sed, ob-ocaml, ob-ruby, and ob-sass (was: [TASK] Move babel backend docs from WORG to Org manual) Ihor Radchenko
2024-12-10 23:45 ` [TASK] Move babel backend docs from WORG to Org manual Suhail Singh
2024-12-13 19:05 ` Ihor Radchenko
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.orgmode.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87zfl3uxhb.fsf@localhost \
--to=yantar92@posteo.net \
--cc=emacs-orgmode@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).