all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
* [TASK] Move babel backend docs from WORG to Org manual
@ 2024-12-10 19:52 Ihor Radchenko
  2024-12-10 20:45 ` Thomas S. Dye
  2024-12-10 23:45 ` [TASK] Move babel backend docs from WORG to Org manual Suhail Singh
  0 siblings, 2 replies; 8+ messages in thread
From: Ihor Radchenko @ 2024-12-10 19:52 UTC (permalink / raw)
  To: emacs-orgmode

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>


^ permalink raw reply	[flat|nested] 8+ messages in thread

* Re: [TASK] Move babel backend docs from WORG to Org manual
  2024-12-10 19:52 [TASK] Move babel backend docs from WORG to Org manual Ihor Radchenko
@ 2024-12-10 20:45 ` Thomas S. Dye
  2024-12-13 18:50   ` Ihor Radchenko
  2024-12-13 18:54   ` Ihor Radchenko
  2024-12-10 23:45 ` [TASK] Move babel backend docs from WORG to Org manual Suhail Singh
  1 sibling, 2 replies; 8+ messages in thread
From: Thomas S. Dye @ 2024-12-10 20:45 UTC (permalink / raw)
  To: Ihor Radchenko; +Cc: emacs-orgmode

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


^ permalink raw reply	[flat|nested] 8+ messages in thread

* Re: [TASK] Move babel backend docs from WORG to Org manual
  2024-12-10 19:52 [TASK] Move babel backend docs from WORG to Org manual Ihor Radchenko
  2024-12-10 20:45 ` Thomas S. Dye
@ 2024-12-10 23:45 ` Suhail Singh
  2024-12-13 19:05   ` Ihor Radchenko
  1 sibling, 1 reply; 8+ messages in thread
From: Suhail Singh @ 2024-12-10 23:45 UTC (permalink / raw)
  To: Ihor Radchenko; +Cc: emacs-orgmode

Ihor Radchenko <yantar92@posteo.net> writes:

> The general idea is to port files from
> https://git.sr.ht/~bzg/worg/tree/master/item/org-contrib/babel into
> Org manual.

Do contributions to the Orgmode manual require copyright assignment to
the FSF?

-- 
Suhail


^ permalink raw reply	[flat|nested] 8+ messages in thread

* Re: [TASK] Move babel backend docs from WORG to Org manual
  2024-12-10 20:45 ` Thomas S. Dye
@ 2024-12-13 18:50   ` Ihor Radchenko
  2024-12-13 18:54   ` Ihor Radchenko
  1 sibling, 0 replies; 8+ messages in thread
From: Ihor Radchenko @ 2024-12-13 18:50 UTC (permalink / raw)
  To: Thomas S. Dye; +Cc: emacs-orgmode

"Thomas S. Dye" <tsd@tsdye.online> writes:

> 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?

Yup.
The priority is built-in languages.

-- 
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>


^ permalink raw reply	[flat|nested] 8+ messages in thread

* Re: [TASK] Move babel backend docs from WORG to Org manual
  2024-12-10 20:45 ` 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
  1 sibling, 1 reply; 8+ messages in thread
From: Ihor Radchenko @ 2024-12-13 18:54 UTC (permalink / raw)
  To: Thomas S. Dye; +Cc: emacs-orgmode

"Thomas S. Dye" <tsd@tsdye.online> writes:

> 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.

Note that ob-comint is not a language, but a helper library used to
implement session support.

> ... I 
> don't know or use any of these languages.  If someone else does 
> know one and would like to jump in, LMK.

Any specific reason why you chose the languages you don't know? May it
be easier to start from parts you are more familiar with?

-- 
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>


^ permalink raw reply	[flat|nested] 8+ messages in thread

* Re: [TASK] Move babel backend docs from WORG to Org manual
  2024-12-10 23:45 ` [TASK] Move babel backend docs from WORG to Org manual Suhail Singh
@ 2024-12-13 19:05   ` Ihor Radchenko
  0 siblings, 0 replies; 8+ messages in thread
From: Ihor Radchenko @ 2024-12-13 19:05 UTC (permalink / raw)
  To: Suhail Singh; +Cc: emacs-orgmode

Suhail Singh <suhailsingh247@gmail.com> writes:

> Ihor Radchenko <yantar92@posteo.net> writes:
>
>> The general idea is to port files from
>> https://git.sr.ht/~bzg/worg/tree/master/item/org-contrib/babel into
>> Org manual.
>
> Do contributions to the Orgmode manual require copyright assignment to
> the FSF?

Yes.
For languages that are not built-in (and that are not going to be merged
into the main manual), we do not have this requirement.

-- 
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>


^ permalink raw reply	[flat|nested] 8+ messages in thread

* Re: [TASK] Move babel backend docs from WORG to Org manual
  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
  0 siblings, 1 reply; 8+ messages in thread
From: Thomas S. Dye @ 2024-12-13 21:39 UTC (permalink / raw)
  To: Ihor Radchenko; +Cc: emacs-orgmode

Aloha Ihor,

Ihor Radchenko <yantar92@posteo.net> writes:

> Any specific reason why you chose the languages you don't know? 
> May it
> be easier to start from parts you are more familiar with?

These lack documentation on Worg, that's all.

I've been documenting the Babel languages on Worg for a few years 
with the hope that someday all the core languages would have their 
own ob-doc file.  Your talk at EmacsConf2024 inspired me to get 
back at it.

Note that there are some maintained languages that aren't 
documented, as well: groovy, calc, haskell, and processing.
-- 
Thomas S. Dye
https://tsdye.online/tsdye


^ permalink raw reply	[flat|nested] 8+ messages in thread

* [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)
  2024-12-13 21:39     ` Thomas S. Dye
@ 2024-12-14  6:58       ` Ihor Radchenko
  0 siblings, 0 replies; 8+ messages in thread
From: Ihor Radchenko @ 2024-12-14  6:58 UTC (permalink / raw)
  To: Thomas S. Dye; +Cc: emacs-orgmode

"Thomas S. Dye" <tsd@tsdye.online> writes:

>> Any specific reason why you chose the languages you don't know? 
>> May it
>> be easier to start from parts you are more familiar with?
>
> These lack documentation on Worg, that's all.

Got it.
Let me then change the subject here to indicate that these languages are
being worked on.

-- 
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>


^ permalink raw reply	[flat|nested] 8+ messages in thread

end of thread, other threads:[~2024-12-14  6:58 UTC | newest]

Thread overview: 8+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2024-12-10 19:52 [TASK] Move babel backend docs from WORG to Org manual Ihor Radchenko
2024-12-10 20:45 ` 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

Code repositories for project(s) associated with this external index

	https://git.savannah.gnu.org/cgit/emacs.git
	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.