From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp1 ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms11 with LMTPS id qkZCO6QhoF6PJAAA0tVLHw (envelope-from ) for ; Wed, 22 Apr 2020 10:51:16 +0000 Received: from aspmx1.migadu.com ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp1 with LMTPS id qJNuD6shoF5CFwAAbx9fmQ (envelope-from ) for ; Wed, 22 Apr 2020 10:51:23 +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 F2D2A94029A for ; Wed, 22 Apr 2020 10:51:21 +0000 (UTC) Received: from localhost ([::1]:47790 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jRCyO-0002H8-33 for larch@yhetil.org; Wed, 22 Apr 2020 06:51:20 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:37734) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jRCxU-0002FR-Te for emacs-orgmode@gnu.org; Wed, 22 Apr 2020 06:50:25 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.90_1) (envelope-from ) id 1jRCxT-0004er-Kh for emacs-orgmode@gnu.org; Wed, 22 Apr 2020 06:50:24 -0400 Received: from relay6-d.mail.gandi.net ([217.70.183.198]:35257) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jRCxS-0004ZU-Ug for emacs-orgmode@gnu.org; Wed, 22 Apr 2020 06:50:23 -0400 X-Originating-IP: 185.131.40.67 Received: from localhost (40-67.ipv4.commingeshautdebit.fr [185.131.40.67]) (Authenticated sender: admin@nicolasgoaziou.fr) by relay6-d.mail.gandi.net (Postfix) with ESMTPSA id 5A46BC0004; Wed, 22 Apr 2020 10:50:17 +0000 (UTC) From: Nicolas Goaziou To: Greg Minshall Subject: Re: babel/noweb concatenation of equally-named code blocks fails? References: <1254269.1587530718@apollo2.minshall.org> Mail-Followup-To: Greg Minshall , emacs-orgmode@gnu.org Date: Wed, 22 Apr 2020 12:50:16 +0200 In-Reply-To: <1254269.1587530718@apollo2.minshall.org> (Greg Minshall's message of "Tue, 21 Apr 2020 21:45:18 -0700") Message-ID: <875zdrokuv.fsf@nicolasgoaziou.fr> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/26.3 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain Received-SPF: pass client-ip=217.70.183.198; envelope-from=mail@nicolasgoaziou.fr; helo=relay6-d.mail.gandi.net X-detected-operating-system: by eggs.gnu.org: First seen = 2020/04/22 06:50:19 X-ACL-Warn: Detected OS = Linux 3.11 and newer [fuzzy] X-Received-From: 217.70.183.198 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: emacs-orgmode@gnu.org Errors-To: emacs-orgmode-bounces+larch=yhetil.org@gnu.org Sender: "Emacs-orgmode" X-Scanner: scn0 X-Spam-Score: 1.39 Authentication-Results: aspmx1.migadu.com; dkim=none; dmarc=none; 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-Scan-Result: default: False [1.39 / 13.00]; RCVD_VIA_SMTP_AUTH(0.00)[]; GENERIC_REPUTATION(0.00)[-0.56594048391034]; HAS_XOIP(0.00)[]; MX_INVALID(1.00)[cached]; TO_DN_SOME(0.00)[]; R_SPF_ALLOW(-0.20)[+ip4:209.51.188.0/24:c]; IP_REPUTATION_HAM(0.00)[asn: 22989(0.23), country: US(-0.01), ip: 209.51.188.17(-0.57)]; RCPT_COUNT_TWO(0.00)[2]; MAILLIST(-0.20)[mailman]; FORGED_RECIPIENTS_MAILLIST(0.00)[]; RCVD_IN_DNSWL_LOW(-0.10)[209.51.188.17:from]; SUBJECT_ENDS_QUESTION(1.00)[]; R_DKIM_NA(0.00)[]; ASN(0.00)[asn:22989, ipnet:209.51.188.0/24, country:US]; MID_RHS_MATCH_FROM(0.00)[]; TAGGED_FROM(0.00)[larch=yhetil.org]; ARC_NA(0.00)[]; RCVD_COUNT_FIVE(0.00)[6]; FROM_NEQ_ENVFROM(0.00)[mail@nicolasgoaziou.fr,emacs-orgmode-bounces@gnu.org]; FROM_HAS_DN(0.00)[]; URIBL_BLOCKED(0.00)[umich.edu:email]; MIME_GOOD(-0.10)[text/plain]; MIME_TRACE(0.00)[0:+]; DMARC_NA(0.00)[nicolasgoaziou.fr]; HAS_LIST_UNSUB(-0.01)[]; RCVD_TLS_LAST(0.00)[]; FORGED_SENDER_MAILLIST(0.00)[] X-TUID: QeqlasORcTnX Hello, Greg Minshall writes: > Nicolas, > > thank you. wordsmithing opens up endless possibilities, so i don't know > that the following is at all an improvement on your suggestion. but, it > occurs to me to get the importance of =noweb-ref=, and its role in > concatenation, brought out early on the "page". Thank you. I certainly appreciate some help on documentation writing. The wording evolved a bit since you checked it. Just to be sure, you suggest to replace (I'm adding context here) Source code blocks can include references to other source code blocks, using a noweb[fn:145] style syntax: : <> where CODE-BLOCK-ID refers to either the NAME of a specific source code block, or a collection of source code blocks sharing the same noweb-ref header argument (see Using Header Arguments). Org can replace such references with the source code---or concatenation thereof--- being referenced, or with the results of an evaluation. The noweb header argument controls expansion of noweb syntax references. Expansions occur when source code blocks are evaluated, tangled, or exported. with Source code blocks can include references to other source code blocks, using a noweb style syntax: : <> where CODE-BLOCK-ID refers to either the NAME of a specific source code block, or a collection of source code blocks sharing the same noweb-ref header argument (see Using Header Arguments). Depending on the setting of the noweb header argument, Org will either ignore a noweb style reference, or will attempt to replace it. In the latter case, the replacement text will be either the source code from exactly *one* named source code block (using either a NAME keyword line, or a noweb-ref header argument), or a concatenation of one or more source code blocks, each with an identically named noweb-ref header argument. Expansions can only occur when source code blocks are evaluated, tangled, or exported. For more details, see below. The noweb header argument controls expansion of noweb syntax references. Expansions occur when source code blocks are evaluated, tangled, or exported. Note there's some duplication with the last paragraph. Can we avoid it? Also, I'm not sure we should insist on the fact that you can use a unique noweb-ref header argument as a code block ID: it is the slow path without any advantage over NAME keyword. I also suggest to replace Depending on the setting of the noweb header argument, Org will either ignore a noweb style reference, or will attempt to replace it. In the latter case, the replacement text will be either ... with Depending on the setting of the noweb header argument, Org either ignores the reference, or replaces it. In the latter case, the replacement text is ... I.e., I'm not a big fan of future tense in documentation, unless there's some grammar rule involved. But then, the following part: the source code from exactly *one* named source code block (using either a NAME keyword line, or a noweb-ref header argument), or a concatenation of one or more source code blocks, each with an identically named noweb-ref header argument. is redundant with the earlier CODE-BLOCK-ID refers to either the NAME of a specific source code block, or a collection of source code blocks sharing the same noweb-ref header argument This already explains that there are two ways for referencing code, as a single code block or as a collection of such blocks, and how to reference them. Can we re-use this to explain that replacement text is the consequence of that choice, instead of repeating ourselves? WDYT? Regards, -- Nicolas Goaziou