Re: babel/noweb concatenation of equally-named code blocks fails?

[Nicolas Goaziou]

Hello,

Greg Minshall <address@hidden> 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