org: Noweb reference syntax
14.10 Noweb reference syntax
============================
The “noweb” (see <http://www.cs.tufts.edu/~nr/noweb/>) Literate
Programming system allows named blocks of code to be referenced by using
the familiar Noweb syntax:
<<code-block-name>>
When a code block is tangled or evaluated, whether or not “noweb”
references are expanded depends upon the value of the ‘:noweb’ header
argument. If ‘:noweb yes’, then a Noweb reference is expanded before
evaluation. If ‘:noweb no’, the default, then the reference is not
expanded before evaluation. See the noweb-ref header argument
for a more flexible way to resolve noweb references.
It is possible to include the _results_ of a code block rather than
the body. This is done by appending parenthesis to the code block name
which may optionally contain arguments to the code block as shown below.
<<code-block-name(optional arguments)>>
Note: the default value, ‘:noweb no’, was chosen to ensure that
correct code is not broken in a language, such as Ruby, where ‘<<arg>>’
is a syntactically valid construct. If ‘<<arg>>’ is not syntactically
valid in languages that you use, then please consider setting the
default value.
Note: if noweb tangling is slow in large Org mode files consider
setting the ‘org-babel-use-quick-and-dirty-noweb-expansion’ variable to
‘t’. This will result in faster noweb reference resolution at the
expense of not correctly resolving inherited values of the ‘:noweb-ref’
header argument.