Hello,
Greg Minshall <minsh...@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
