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.