From: Nicolas Goaziou <mail@nicolasgoaziou.fr>
To: Greg Minshall <minshall@umich.edu>
Cc: emacs-orgmode@gnu.org
Subject: Re: babel/noweb concatenation of equally-named code blocks fails?
Date: Wed, 22 Apr 2020 12:50:16 +0200 [thread overview]
Message-ID: <875zdrokuv.fsf@nicolasgoaziou.fr> (raw)
In-Reply-To: <1254269.1587530718@apollo2.minshall.org> (Greg Minshall's message of "Tue, 21 Apr 2020 21:45:18 -0700")
Hello,
Greg Minshall <minshall@umich.edu> 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:
: <<CODE-BLOCK-ID>>
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:
: <<CODE-BLOCK-ID>>
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
next prev parent reply other threads:[~2020-04-22 10:51 UTC|newest]
Thread overview: 12+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-04-19 20:07 babel/noweb concatenation of equally-named code blocks fails? Greg Minshall
2020-04-19 21:11 ` Nicolas Goaziou
2020-04-19 21:18 ` Greg Minshall
2020-04-19 21:53 ` Nicolas Goaziou
2020-04-19 23:06 ` Greg Minshall
2020-04-20 9:23 ` Nicolas Goaziou
2020-04-22 4:45 ` Greg Minshall
2020-04-22 10:50 ` Nicolas Goaziou [this message]
2020-04-22 14:22 ` Greg Minshall
2020-04-22 17:09 ` Nicolas Goaziou
2020-04-22 21:51 ` Greg Minshall
2020-04-23 8:43 ` Nicolas Goaziou
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=875zdrokuv.fsf@nicolasgoaziou.fr \
--to=mail@nicolasgoaziou.fr \
--cc=emacs-orgmode@gnu.org \
--cc=minshall@umich.edu \
/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).