Re: [Pre-PATCH v2] Add the capability to specify lexical scope in tangled files (was: Add new :lexical header argument)

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

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.

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