From baa44bd705024a4ddc56f98de561dbc4d68a6acb Mon Sep 17 00:00:00 2001 From: Nicolas Goaziou Date: Mon, 20 Apr 2020 22:31:18 +0200 Subject: [PATCH] manual: Some additional clarifications in noweb expansion * doc/org-manual.org (Cache results of evaluation): (Extracting Source Code): (Header arguments): Use noweb instead of Noweb. (Noweb Reference Syntax): Add some clarifications. --- doc/org-manual.org | 62 ++++++++++++++++++++++++---------------------- 1 file changed, 32 insertions(+), 30 deletions(-) diff --git a/doc/org-manual.org b/doc/org-manual.org index 5bdf2c43f..3f22978f3 100644 --- a/doc/org-manual.org +++ b/doc/org-manual.org @@ -17093,7 +17093,7 @@ A note of warning: when =cache= is used in a session, caching may cause unexpected results. When the caching mechanism tests for any source code changes, it does -not expand Noweb style references (see [[*Noweb Reference Syntax]]). For +not expand noweb style references (see [[*Noweb Reference Syntax]]). For reasons why, see http://thread.gmane.org/gmane.emacs.orgmode/79046. The =cache= header argument can have one of two values: =yes= or =no=. @@ -17598,7 +17598,7 @@ code. When Org tangles code blocks, it expands, merges, and transforms them. Then Org recomposes them into one or more separate files, as configured through the options. During this tangling process, Org -expands variables in the source code, and resolves any Noweb style +expands variables in the source code, and resolves any noweb style references (see [[*Noweb Reference Syntax]]). *** Header arguments @@ -17664,7 +17664,7 @@ already exist in the code block. - =noweb= :: - Includes =link= option, expands Noweb references (see [[*Noweb + Includes =link= option, expands noweb references (see [[*Noweb Reference Syntax]]), and wraps them in link comments inside the body of the code block. @@ -17703,7 +17703,7 @@ By default Org expands code blocks during tangling. The =no-expand= header argument turns off such expansions. Note that one side-effect of expansion by ~org-babel-expand-src-block~ also assigns values (see [[*Environment of a Code Block]]) to variables. Expansions also replace -Noweb references with their targets (see [[*Noweb Reference Syntax]]). +noweb references with their targets (see [[*Noweb Reference Syntax]]). Some of these expansions may cause premature assignment, hence this option. This option makes a difference only for tangling. It has no effect when exporting since code blocks for execution have to be @@ -17900,56 +17900,58 @@ for Python and Emacs Lisp languages. :PROPERTIES: :DESCRIPTION: Literate programming in Org mode. :END: -#+cindex: code block, Noweb reference -#+cindex: syntax, Noweb -#+cindex: source code, Noweb reference +#+cindex: code block, noweb reference +#+cindex: syntax, noweb +#+cindex: source code, noweb reference #+cindex: @samp{noweb-ref}, header argument -Org supports named blocks in Noweb[fn:144] style syntax: +Source code blocks can include references to other source code blocks, +using a noweb[fn:144] style syntax: : <> +#+texinfo: @noindent where {{{var(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]]). +Arguments]]). Org can replace such references with the source code---or +concatenation thereof--- being referenced, or with the results of an +evaluation. #+cindex: @samp{noweb}, header argument -Org can replace the Noweb style reference with the source code---or -concatenation thereof---, or even the results of an evaluation, as -detailed below. The =noweb= header argument controls expansion of -Noweb syntax references. Expansions occur when source code blocks are -evaluated, tangled, or exported. +The =noweb= header argument controls expansion of noweb syntax +references. Expansions occur when source code blocks are evaluated, +tangled, or exported. - =no= :: - Default. No expansion of Noweb syntax references in the body of the + Default. No expansion of noweb syntax references in the body of the code when evaluating, tangling, or exporting. - =yes= :: - Expansion of Noweb syntax references in the body of the code block + Expansion of noweb syntax references in the body of the code block when evaluating, tangling, or exporting. - =tangle= :: - Expansion of Noweb syntax references in the body of the code block + Expansion of noweb syntax references in the body of the code block when tangling. No expansion when evaluating or exporting. - =no-export= :: - Expansion of Noweb syntax references in the body of the code block + Expansion of noweb syntax references in the body of the code block when evaluating or tangling. No expansion when exporting. - =strip-export= :: - Expansion of Noweb syntax references in the body of the code block - when expanding prior to evaluating or tangling. Removes Noweb + Expansion of noweb syntax references in the body of the code block + when expanding prior to evaluating or tangling. Removes noweb syntax references when exporting. - =eval= :: - Expansion of Noweb syntax references in the body of the code block + Expansion of noweb syntax references in the body of the code block only before evaluating. In the most simple case, the contents of a single source block is @@ -18009,7 +18011,7 @@ concatenation to a pure code file when tangled. #+end_example #+cindex: @samp{noweb-sep}, header argument -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. Eventually, Org can include the results of evaluation of a single code @@ -18023,7 +18025,7 @@ code block name set by =NAME= keyword is required; the reference set by =noweb-ref= is not effective in that case. 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: #+begin_example @@ -18047,7 +18049,7 @@ expands to: : print(num*10) -Below, a similar Noweb style reference is used, but with parentheses, +Below, a similar noweb style reference is used, but with parentheses, while setting a variable =num= to 10: #+begin_example @@ -18062,10 +18064,10 @@ Note that the expansion now contains the results of the code block : 100 -Noweb insertions honor prefix characters that appear before the Noweb +Noweb insertions honor prefix characters that appear before the noweb syntax reference. This behavior is illustrated in the following -example. Because the =<>= Noweb reference appears behind the -SQL comment syntax, each line of the expanded Noweb reference is +example. Because the =<>= noweb reference appears behind the +SQL comment syntax, each line of the expanded noweb reference is commented. With: #+begin_example @@ -18095,8 +18097,8 @@ expands to: ,#+END_SRC #+end_example -Since this change does not affect Noweb replacement text without -newlines in them, inline Noweb references are acceptable. +Since this change does not affect noweb replacement text without +newlines in them, inline noweb references are acceptable. This feature can also be used for management of indentation in exported code snippets. With: @@ -21611,7 +21613,7 @@ the C language. identifier for such source blocks is =D=, you activate it by loading the C language. -[fn:144] For Noweb literate programming details, see +[fn:144] For noweb literate programming details, see http://www.cs.tufts.edu/~nr/noweb/. [fn:145] For more information, please refer to the commentary section