Re: [PATCH] Allow tangling to a list of files

[Tim Cross <theophilusx@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 5153 bytes --]

On Fri, 9 Jul 2021 at 22:28, Vladimir Lomov <lomov.vl@yandex.ru> wrote:

> Hello,
> ** Greg Minshall <minshall@umich.edu> [2021-07-07 09:56:06 +0300]:
>
> > Vladimir,
>
> >> I couldn't find in Org manual how tangling should work if there are
> >> several source code blocks with the same file name for ':tangle'. The
> >> Org manual section "15.8 Extracting Source Code" is a bit
> >> obscure. There are these two sentences
>
> > i think what Tim answered is correct.  but, i believe the "desired"
> > approach is to put all those blocks to be tangled to the same file under
> > a headline with a property drawer containing something like:
> > ----
> >         :header-args+:    :tangle "submsim.jl"
> > ----
>
> Hmm, the more I read the manual and your answers the less I understand. As
> I
> said I didn't find in the manual any mention of feature you and Tim
> referring
> to. Besides I didn't find definition of [source] code block. If Org
> document
> has several #+BEGIN/END_SRC constructions is this the one "code block" or
> not?
> May be they are different if they use different "language" identifier?
> Again,
> I didn't find any definition or explanation in the manual. This is either
> lack
> of documentation or feature of how Org deals with source blocks. In my
> opinion, this is undocumented feature.
>
> > i believe this is for performance of tangling, but possibly the
> > "multiple source blocks to same :tangle'd file" feature may disappear?
>
> Personally, I don't find the documentation lacking in this area. I think
it is quite clear and the use of multiple source blocks and multiple
destination files is within the scope of documented features. Therefore,
I'm not in a good position to suggest what modifications to the
documentation are necessary. However, I did use literate programming before
org mode, so perhaps my understanding or expectations have been influenced
by thiat.

Perhaps if I outline my understanding and the sections from the manual
which guide my interpretation, that will help.

If we start from a high level literate programming perspective, we can
assume a file can contain multiple source blocks. This is largely the whole
idea. You have a file which has source code and 'pros' mixed together. To
distinguish them, source code is wrapped in a source block. In org, this
means a block of the form

+begin_src
...
+end_src

To provide some additional functionality, the source block definition above
can be extended with a number of useful options, including specifying the
language of the source code and the :tangle option. e.g.

+begin_src emacs-lisp :tangle yes
...
+end_src

The above block will be tangled as emacs lisp code and written to the
default output file, which is the org filename with a language appropriate
extension. e.g. if the org file is my-code.org, the tangled output file
will be my-code.el

The org manual states in the section on extracting source code

"When Org tangles code blocks, it expands, merges, and transforms
them.  Then Org recomposes them into one or more separate files, as
configured through the options.  During this tangling process, Org
expands variables in the source code, and resolves any noweb style
references (see *note Noweb Reference Syntax::)."

I think the above paragraph largely describes the feature of supporting
both multiple code blocks (which are expanded, merged and transformed) and
multiple destination files ("...recomposes them into one or more separate
files...").

The manual then goes on to describe the :tangle option

"The ‘tangle’ header argument specifies if the code block is exported to
source file(s)."

Note the use of 'file(s)" to indicate one or more files. The documentation
goes on to explain that the tangle argument can have the vaules "yes", "no"
or a FILENAME. If the argument is a file name

"Export the code block to source file whose file name is derived
from any string passed to the ‘tangle’ header argument.  Org
derives the file name as being relative to the directory of the Org
file’s location.  Example: ‘:tangle FILENAME’."

So, at this point we know

- An org file can contain multiple source blocks
- Org will expand, merge and transform source blocks as required
- By default, a tangled block will be written to a source file with the
same base name as the org file it comes from with a language appropriate
extension
- If the :tangle option specifies a filename, that filename will be used
for *that* block

I think the above covers the behaviour where you have multiple source
blocks in an org file and you use the :tangle FILENAME option to send the
tangled output to different files. The fact there is a test case for this
behaviour further confirms this is expected behaviour.

The only undocumented behaviour is the use of a function instead of a
filename to specify the destination for tangled output. I was not aware
that this functionality is uspported and have not yet tried it. If this
does indeed work, it does need to be added to the manual.


--
Tim Cross

[-- Attachment #2: Type: text/html, Size: 6545 bytes --]