forked from mirrors/org-mode
manual: some clarification on <<noweb>> syntax
* doc/org-manual.org (Noweb Reference Syntax): Add some clarification on <<noweb>>, #+name:, :noweb-ref.
This commit is contained in:
parent
41fe010868
commit
c8eaa5fcf1
|
@ -17911,12 +17911,13 @@ using a noweb[fn:144] style syntax:
|
||||||
: <<CODE-BLOCK-ID>>
|
: <<CODE-BLOCK-ID>>
|
||||||
|
|
||||||
#+texinfo: @noindent
|
#+texinfo: @noindent
|
||||||
where {{{var(CODE-BLOCK-ID)}}} refers to either the =NAME= of
|
where {{{var(CODE-BLOCK-ID)}}} refers to either the =NAME= of a single
|
||||||
a specific source code block, or a collection of source code blocks
|
source code block, or a collection of one or more source code blocks
|
||||||
sharing the same =noweb-ref= header argument (see [[*Using Header
|
sharing the same =noweb-ref= header argument (see [[*Using Header
|
||||||
Arguments]]). Org can replace such references with the source code---or
|
Arguments]]). Org can replace such references with the source code of
|
||||||
concatenation thereof--- being referenced, or with the results of an
|
the block or blocks being referenced, or, in the case of a single
|
||||||
evaluation.
|
source code block named with =NAME=, with the results of an evaluation
|
||||||
|
of that block.
|
||||||
|
|
||||||
#+cindex: @samp{noweb}, header argument
|
#+cindex: @samp{noweb}, header argument
|
||||||
The =noweb= header argument controls expansion of noweb syntax
|
The =noweb= header argument controls expansion of noweb syntax
|
||||||
|
@ -17979,11 +17980,11 @@ the second code block is expanded as
|
||||||
,#+END_SRC
|
,#+END_SRC
|
||||||
#+end_example
|
#+end_example
|
||||||
|
|
||||||
You may also concatenate the contents of multiple blocks sharing
|
You may also include the contents of multiple blocks sharing a common
|
||||||
a common =noweb-ref= header argument. For simple concatenation, set
|
=noweb-ref= header argument, which can be set at the file, sub-tree,
|
||||||
its value at the sub-tree or file level. In the example Org file
|
or code block level. In the example Org file shown next, the body of
|
||||||
shown next, the body of the source code in each block is extracted for
|
the source code in each block is extracted for concatenation to a pure
|
||||||
concatenation to a pure code file when tangled.
|
code file when tangled.
|
||||||
|
|
||||||
#+begin_example
|
#+begin_example
|
||||||
,#+BEGIN_SRC sh :tangle yes :noweb yes :shebang #!/bin/sh
|
,#+BEGIN_SRC sh :tangle yes :noweb yes :shebang #!/bin/sh
|
||||||
|
@ -18014,19 +18015,20 @@ concatenation to a pure code file when tangled.
|
||||||
By default a newline separates each noweb reference concatenation. To
|
By default a newline separates each noweb reference concatenation. To
|
||||||
use a different separator, edit the =noweb-sep= header argument.
|
use a different separator, edit the =noweb-sep= header argument.
|
||||||
|
|
||||||
Eventually, Org can include the results of evaluation of a single code
|
Alternatively, Org can include the results of evaluation of a single
|
||||||
block rather than its body. To that effect, append parentheses,
|
code block rather than its body. Evaluation occurs when parentheses,
|
||||||
possibly including arguments, to the code block name, as shown below.
|
possibly including arguments, are appended to the code block name, as
|
||||||
|
shown below.
|
||||||
|
|
||||||
: <<NAME(optional arguments)>>
|
: <<NAME(optional arguments)>>
|
||||||
|
|
||||||
Note that when using the above approach to a code block's results, the
|
Note that in this case, a code block name set by =NAME= keyword is
|
||||||
code block name set by =NAME= keyword is required; the reference set
|
required; the reference set by =noweb-ref= will not work when
|
||||||
by =noweb-ref= is not effective in that case.
|
evaluation is desired.
|
||||||
|
|
||||||
Here is an example that demonstrates how the exported content changes
|
Here is an example that demonstrates how the exported content changes
|
||||||
when noweb style references are used with parentheses versus without.
|
when noweb style references are used with parentheses versus without.
|
||||||
With:
|
Given:
|
||||||
|
|
||||||
#+begin_example
|
#+begin_example
|
||||||
,#+NAME: some-code
|
,#+NAME: some-code
|
||||||
|
|
Loading…
Reference in New Issue