From: Tim Cross <theophilusx@gmail.com>
To: Vladimir Lomov <lomov.vl@yandex.ru>
Cc: Greg Minshall <minshall@umich.edu>,
Org-mode <emacs-orgmode@gnu.org>,
Jacopo De Simoi <wilderjds@protonmail.com>
Subject: Re: [PATCH] Allow tangling to a list of files
Date: Sat, 10 Jul 2021 08:47:33 +1000 [thread overview]
Message-ID: <CAC=50j8kh5Y85jO21a0Lizivq=Ppow9tq9eP3DPSLFisb2TWHQ@mail.gmail.com> (raw)
In-Reply-To: <YOhAdZzb8ek64aNQ@smoon.bkoty.ru>
[-- 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 --]
next prev parent reply other threads:[~2021-07-09 22:49 UTC|newest]
Thread overview: 21+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-07-05 18:54 [PATCH] Allow tangling to a list of files Jacopo De Simoi
2021-07-06 2:57 ` Vladimir Lomov
2021-07-06 4:43 ` Greg Minshall
2021-07-06 5:09 ` Jacopo De Simoi via General discussions about Org-mode.
2021-07-06 6:11 ` Vladimir Lomov
2021-07-06 15:24 ` Jacopo De Simoi via General discussions about Org-mode.
2021-07-07 3:27 ` Vladimir Lomov
2021-07-07 4:09 ` Tim Cross
2021-07-07 5:01 ` Jacopo De Simoi
2021-07-07 6:56 ` Greg Minshall
2021-07-07 11:05 ` Jacopo De Simoi
2021-07-09 12:26 ` Vladimir Lomov
2021-07-09 13:39 ` Jacopo De Simoi
2021-07-09 22:47 ` Tim Cross [this message]
2021-07-06 7:30 ` Tim Cross
2021-07-07 23:06 ` Jacopo De Simoi via General discussions about Org-mode.
2021-07-07 23:28 ` Tim Cross
2021-07-08 0:01 ` Jacopo De Simoi
2021-07-08 0:41 ` Tom Gillespie
2021-07-08 16:41 ` Trust me I am a Doctor
2021-07-08 17:42 ` Jacopo De Simoi
[not found] <-0ZoEP_lzUvrnWSq9TwiYHNJ0Spa94xjiTOF0TU8np0pYgHEPx-62_dr5xBMd3VUu7frSRXxiAFje99v2jeaJg==@protonmail.internalid>
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='CAC=50j8kh5Y85jO21a0Lizivq=Ppow9tq9eP3DPSLFisb2TWHQ@mail.gmail.com' \
--to=theophilusx@gmail.com \
--cc=emacs-orgmode@gnu.org \
--cc=lomov.vl@yandex.ru \
--cc=minshall@umich.edu \
--cc=wilderjds@protonmail.com \
/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).