From: "Berry, Charles" <ccberry@health.ucsd.edu>
To: "Thomas S. Dye" <tsd@tsdye.online>
Cc: Ihor Radchenko <yantar92@posteo.net>,
Evgenii Klimov <eugene.dev@lipklim.org>,
"emacs-orgmode@gnu.org" <emacs-orgmode@gnu.org>
Subject: Re: [Pre-PATCH v2] Add the capability to specify lexical scope in tangled files (was: Add new :lexical header argument)
Date: Sat, 15 Jul 2023 19:33:12 +0000 [thread overview]
Message-ID: <595242D2-8373-479C-BC4A-A3552131B19F@health.ucsd.edu> (raw)
In-Reply-To: <87edl9f4qq.fsf@tsdye.online>
> On Jul 15, 2023, at 9:11 AM, Thomas S. Dye <tsd@tsdye.online> wrote:
>
>
> Ihor Radchenko <yantar92@posteo.net> writes:
>
>> "Thomas S. Dye" <tsd@tsdye.online> writes:
>>
>>>> Am I correct that language-specific header arguments are not yet covered
>>>> in the manual? I can't find any reference of "lexical" there.
>>>
>>> Yes, I believe so. Language-specific header arguments for many languages are documented at https://orgmode.org/worg/org-contrib/babel/languages/index.html. Several languages are not documented there; in these cases the documentation is typically in the source code.
>>
>> It is actually slightly awkward that built-in babel backends are not
>> documented in the manual, while, for example, export backends are.
>>
> Agreed, but the two differ. With export, the goal is to produce code recognized as correct by the target software. With babel, the general goal is to provide language agnostic literate programming, which often produces something that meets standards of correctness not implemented in software. The idea of built-in babel backends, as distinct from contributed backends, or backends distributed by package archive is a function of maintenance burden and distribution channel, rather than something intrinsic to the backend itself and how it contributes to literate programming.
>> However, unless my memory deceives me, Bastien or Nicolas previously
>> voiced against adding babel documentation. Though I cannot find the
>> relevant discussion now and cannot recall the arguments (if there was
>> such discussion at all).
>
> IIRC, there wasn't much discussion. The current situation doesn't seem ripe for documentation in the manual.
>
Agreed. Maybe it would suffice to use enhanced docstrings for the org-babel-execute:<lang> functions and point to them in the manual.
The params argument could list the language specific keys and the language specific handling of key common to all languages (e.g. `:results graphics' in R jumps through a number of hoops that might deserve mention)
Chuck
> Here are some potential hurdles:
> - there are likely too many built-in backends;
> - the built-in backends are a mixed bag--ob-lua seems half-finished to me, though I don't program in lua and struggled to set up the language to write the documentation stub on Worg;
> - nearly a dozen of the built-in babel backends lack documentation outside the source code (see https://orgmode.org/worg/org-contrib/babel/languages/index.html#orgbc466c5); and
> - language support is inconsistent (see https://orgmode.org/worg/org-contrib/babel/languages/lang-compat.html), which introduces complications for language agnostic literate programming.
>
> One way forward might distinguish between babel backends for GNU software and babel backends for non-GNU software, with the former built in, guaranteed to be consistent to some standard (which needs to be formulated), and documented in the manual and the latter moved to contrib or a package archive, with documentation (if any) on Worg.
>
> Others might have better ideas.
>
> All the best,
> Tom
> --
> Thomas S. Dye
> https://tsdye.online/tsdye
>
>
next prev parent reply other threads:[~2023-07-15 19:34 UTC|newest]
Thread overview: 19+ messages / expand[flat|nested] mbox.gz Atom feed top
[not found] <mailman.49.1689350420.11515.emacs-orgmode@gnu.org>
2023-07-14 20:43 ` [Pre-PATCH v2] Add the capability to specify lexical scope in tangled files (was: Add new :lexical header argument) No Wayman
2023-07-14 21:25 ` Evgenii Klimov
2023-07-14 21:57 ` Thomas S. Dye
2023-07-15 8:12 ` Ihor Radchenko
2023-07-15 16:11 ` Thomas S. Dye
2023-07-15 19:33 ` Berry, Charles [this message]
2023-07-16 9:24 ` Ihor Radchenko
2023-07-16 9:18 ` [TASK] Ensure built-in babel backend consistency (standard header support) and ad documentation to the manual (was: [Pre-PATCH v2] Add the capability to specify lexical scope in tangled files (was: Add new :lexical header argument)) Ihor Radchenko
2023-07-16 17:40 ` Thomas S. Dye
2023-07-16 18:29 ` Ihor Radchenko
2023-07-16 18:53 ` Thomas S. Dye
2023-07-13 18:30 [Pre-PATCH] Add new :lexical header argument Evgenii Klimov
2023-07-13 18:41 ` Ihor Radchenko
2023-07-13 22:00 ` [Pre-PATCH v2] Add the capability to specify lexical scope in tangled files (was: Add new :lexical header argument) Evgenii Klimov via General discussions about Org-mode.
2023-07-14 9:15 ` Ihor Radchenko
2023-07-14 9:23 ` Timothy
2023-07-15 7:45 ` Ihor Radchenko
2023-07-15 16:10 ` Timothy
2023-07-16 9:43 ` Ihor Radchenko
2023-08-23 11:44 ` Ihor Radchenko
2023-08-27 8:20 ` Evgenii Klimov
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=595242D2-8373-479C-BC4A-A3552131B19F@health.ucsd.edu \
--to=ccberry@health.ucsd.edu \
--cc=emacs-orgmode@gnu.org \
--cc=eugene.dev@lipklim.org \
--cc=tsd@tsdye.online \
--cc=yantar92@posteo.net \
/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).