From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp1 ([2001:41d0:2:bcc0::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms0.migadu.com with LMTPS id UOAUKW3S6GB4AAAAgWs5BA (envelope-from ) for ; Sat, 10 Jul 2021 00:49:17 +0200 Received: from aspmx1.migadu.com ([2001:41d0:2:bcc0::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp1 with LMTPS id 6FGSJG3S6GDLTwAAbx9fmQ (envelope-from ) for ; Fri, 09 Jul 2021 22:49:17 +0000 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by aspmx1.migadu.com (Postfix) with ESMTPS id 0058D1033A for ; Sat, 10 Jul 2021 00:49:17 +0200 (CEST) Received: from localhost ([::1]:57514 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1m1zJ5-0003iJ-9C for larch@yhetil.org; Fri, 09 Jul 2021 18:49:15 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:56780) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1m1zHg-0003i8-Oa for emacs-orgmode@gnu.org; Fri, 09 Jul 2021 18:47:48 -0400 Received: from mail-oi1-x234.google.com ([2607:f8b0:4864:20::234]:42678) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1m1zHe-0004Tx-EB for emacs-orgmode@gnu.org; Fri, 09 Jul 2021 18:47:48 -0400 Received: by mail-oi1-x234.google.com with SMTP id z3so13283721oib.9 for ; Fri, 09 Jul 2021 15:47:45 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=mime-version:references:in-reply-to:from:date:message-id:subject:to :cc; bh=OmAiWNAb4txH4eO2r0poQBRfQuyyFKil8LnY2eJbS9s=; b=NDt+88NVnoGG97wmAn/3IaT8LkKC5027Yy0IY5pN45iFtckcf8+8qH5g/zgTZkuCCc w5tY+nTmDi2JPKBV7mYytT4JgcqV4BXDtpwQtkqe1H7V9gszKPYSq3PQdl/tRbixAMK/ 4YA91oSLB26efrF47VUsib8r764utmtMsPmxRwQy4qgM+Mv4TuhtVbsVo/F8x++zOUJv IXpHMuR1x/N1sGXKOjF+uPmiGKHalR7av+GNswYuyDYx83WaisGpOdfZ5oYRljtwwe90 5dAC2ZIH7H3hF1w4wRXzBIpRioZ+ic2BFo8I43EOpMBjii8zc1ysdQeDX1RVboG6OGFE oe4g== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc; bh=OmAiWNAb4txH4eO2r0poQBRfQuyyFKil8LnY2eJbS9s=; b=PhIDe2AUU3+k1b6qbWA/eOsZ3ogv75CH3awlAHhPMpS4z6XsuwS6mHCNkt3TzlvZeS rIkAnCrZl+wXEz5CuHYXXOAkSL2hY+GHrqcb35pKq9uEmnJO/76skvdZ3pZ0GNVf0msM fc8DcGkkMltIR1nSUQBAmHEZTNScO32iy89Bpsi2Eadgv6cNy4vkySY188zOi0Y6cXbx VN1m9qdLINpF1PLYMnVuao8vijGwkXjS0ItQCP6tU76UJ3Mrbx7ufhoQ27uC6GCHtaPa VI6HyR0BjzafV1oBsBRU9KvLan9gXPoBXs/EqyPVgcCG3BIT02GF18cVc3405TS2xQ+b SjXw== X-Gm-Message-State: AOAM5329MVZUBIo9mOJajPIpLNgAShUY2PJeLsT3p7hovzokiKWwntr7 F1buAFhy26nL248V0DWoZP0JvwuYqqzI4VwR4Ao= X-Google-Smtp-Source: ABdhPJz/+ohEEoBRhQ8wNfi8+vlb3Hypd7Zh5g9+CpaeFDfwW+9IDTSWlN2/zyyN9yATCPzFzXjSuAcJFTg+w6iW0q0= X-Received: by 2002:aca:cf82:: with SMTP id f124mr23076809oig.47.1625870864551; Fri, 09 Jul 2021 15:47:44 -0700 (PDT) MIME-Version: 1.0 References: <348721.1625640966@apollo2.minshall.org> In-Reply-To: From: Tim Cross Date: Sat, 10 Jul 2021 08:47:33 +1000 Message-ID: Subject: Re: [PATCH] Allow tangling to a list of files To: Vladimir Lomov Content-Type: multipart/alternative; boundary="00000000000055114b05c6b88f24" Received-SPF: pass client-ip=2607:f8b0:4864:20::234; envelope-from=theophilusx@gmail.com; helo=mail-oi1-x234.google.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, FREEMAIL_FROM=0.001, HTML_MESSAGE=0.001, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: emacs-orgmode@gnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Greg Minshall , Org-mode , Jacopo De Simoi Errors-To: emacs-orgmode-bounces+larch=yhetil.org@gnu.org Sender: "Emacs-orgmode" X-Migadu-Flow: FLOW_IN ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1625870957; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-type:in-reply-to:in-reply-to: references:references:list-id:list-help:list-unsubscribe: list-subscribe:list-post:dkim-signature; bh=OmAiWNAb4txH4eO2r0poQBRfQuyyFKil8LnY2eJbS9s=; b=USTf4b1UD2r5Y9OhuvspIsjktOVekrnX+WD7hturhWIAKvgrPF8+iYY7pwF1id8Ll62jY/ 5dd0EOFEi73cK0VbLjNQ28fti4wb0X270VssP46T2lkHdJYVctE+cDOzONu+Q/l5lH/HgO 4Krl3YSeTmcsj1rJGoKz3xGAW9ETjRQp8zpAXivSInCf0cepvYU+mX36CGomFIwnbXCt/Q 1kuE0nRCJn4BrnXo/tr9VC+093i0ROkbaLHCmiIKV9tu8D9a0EkUNs5vgm+oFHC9f5fGBq JZcSEs4UDULK0wDEZ1ZlIjjyv1HvVe+7d3LClvaiUl+7hdLEUF81NcbhkA+hPQ== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1625870957; a=rsa-sha256; cv=none; b=T9PFCmVBUFWgziScLrC/SU2RoqrtbwKviCfZV0yfgskrG9JA3HN06zuNBel/2Je7XPEglU l5oFV4tjFE59c0WVRJ3iRG+PWrKsuROzJ0RdsOXOlXBjrPJKjQz7o3jsp2xH4LO+cZU0EG wkHDY/Qg94vzkUQfnXxRHRL1cgOZNNDAEKWKRMkyJzcZH4S5Rx67ej2CnkrqXnNBMGkegj 3DjcCjGsRzzb3Jmqq6GZ624Fl/pkX0eBYfec/hSWTXkrUCI+BtOUWQJ/ER5hEDKZUNiRT3 c7MXiQEgqoWEORC2TPPKSq1rWtc0E/26EQ/lTH0HanJ1nrBMjqrAEyV5vqjy1A== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=gmail.com header.s=20161025 header.b=NDt+88NV; dmarc=pass (policy=none) header.from=gmail.com; spf=pass (aspmx1.migadu.com: domain of emacs-orgmode-bounces@gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=emacs-orgmode-bounces@gnu.org X-Migadu-Spam-Score: -3.10 Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=gmail.com header.s=20161025 header.b=NDt+88NV; dmarc=pass (policy=none) header.from=gmail.com; spf=pass (aspmx1.migadu.com: domain of emacs-orgmode-bounces@gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=emacs-orgmode-bounces@gnu.org X-Migadu-Queue-Id: 0058D1033A X-Spam-Score: -3.10 X-Migadu-Scanner: scn0.migadu.com X-TUID: hAqOX4Iw6I+N --00000000000055114b05c6b88f24 Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable On Fri, 9 Jul 2021 at 22:28, Vladimir Lomov wrote: > Hello, > ** Greg Minshall [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 unde= r > > 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. A= s > 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 =E2=80=98tangle=E2=80=99 header argument specifies if the code block i= s 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 =E2=80=98tangle=E2=80=99 header argument. Or= g derives the file name as being relative to the directory of the Org file=E2=80=99s location. Example: =E2=80=98:tangle FILENAME=E2=80=99." 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 --00000000000055114b05c6b88f24 Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable


=
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 ther= e are
>> several source code blocks with the same file name for ':tangl= e'. The
>> Org manual section "15.8 Extracting Source Code" is a bi= t
>> obscure. There are these two sentences

> i think what Tim answered is correct.=C2=A0 but, i believe the "d= esired"
> approach is to put all those blocks to be tangled to the same file und= er
> a headline with a property drawer containing something like:
> ----
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0:header-args+:=C2=A0 =C2=A0 :tangle &= quot;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 ref= erring
to. Besides I didn't find definition of [source] code block. If Org doc= ument
has several #+BEGIN/END_SRC constructions is this the one "code block&= quot; or not?
May be they are different if they use different "language" identi= fier? Again,
I didn't find any definition or explanation in the manual. This is eith= er 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 sou= rce blocks and multiple destination files is within the scope of documented= features. Therefore, I'm not in a good position to suggest what modifi= cations to the documentation are necessary. However, I did use literate pro= gramming 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 interpretatio= n, that will help.=C2=A0

If we start from a high l= evel literate programming perspective, we can assume a file can contain mul= tiple source blocks. This is largely the whole idea. You have a file which = has source code and 'pros' mixed together. To distinguish them, sou= rce code is wrapped in a source block. In org, this means a block of the fo= rm

+begin_src
...
+end_src=

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

+begin_src emacs-lisp :tangle yes
<= /div>
...
+end_src

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

The org manual st= ates in the section on extracting source code

&quo= t;When Org tangles code blocks, it expands, merges, and transforms
the= m.=C2=A0 Then Org recomposes them into one or more separate files, as
co= nfigured through the options.=C2=A0 During this tangling process, Org
ex= pands variables in the source code, and resolves any noweb style
referen= ces (see *note Noweb Reference Syntax::)."

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

The manual then goes on to describe the :tangle option
"The =E2=80=98tangle=E2=80=99 header argument specifies if= the code block is exported to
source file(s)."

Note the use of 'file(s)" to indic= ate one or more files. The documentation goes on to explain that the tangle= argument can have the vaules=C2=A0"yes", "no" or a FIL= ENAME. If the argument is a file name

"Export the code block to source file whose file name is d= erived
from any string passed to the =E2=80=98tangle=E2=80=99 header arg= ument.=C2=A0 Org
derives the file name as being relative to the director= y of the Org
file=E2=80=99s location.=C2=A0 Example: =E2=80=98:tangle FI= LENAME=E2=80=99."

So,= at this point we know

- A= n org file can contain multiple source blocks
- Org w= ill expand, merge and transform source blocks as required
- By default, a tangled block will be written to a source file with th= e same base name as the org file it comes from with a language appropriate = extension
- If the :tangle option specifies a filenam= e, 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 opti= on to send the tangled output to different files. The fact there is a test = case for this behaviour further confirms this is expected behaviour.=C2=A0<= /div>

The only undocumented beha= viour is the use of a function instead of a filename to specify the destina= tion for tangled output. I was not aware that this functionality is uspport= ed and have not yet tried it. If this does indeed work, it does need to be = added to the manual.


--
= Tim Cross

--00000000000055114b05c6b88f24--