From 9580d645d001defb098d83f90d58e6a36f6220e3 Mon Sep 17 00:00:00 2001 From: Kaushal Modi Date: Thu, 22 Jun 2017 14:52:32 -0400 Subject: [PATCH] Improve noweb documentation * doc/org.texi (noweb, noweb-ref, Noweb reference syntax): Add examples and improve wording. Clarify the use of noweb style references with code block arguments. --- doc/org.texi | 145 +++++++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 122 insertions(+), 23 deletions(-) diff --git a/doc/org.texi b/doc/org.texi index b722b5da93..d41a28998a 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -16188,36 +16188,50 @@ code blocks are evaluated, tangled, or exported. @itemize @bullet @item @code{no} -Default. No expansion of ``Noweb'' syntax references in the body of the code +Default. No expansion of ``noweb'' syntax references in the body of the code when evaluating, tangling, or exporting. @item @code{yes} -Expansion of ``Noweb'' syntax references in the body of the @samp{src} code +Expansion of ``noweb'' syntax references in the body of the @samp{src} code block when evaluating, tangling, or exporting. @item @code{tangle} -Expansion of ``Noweb'' syntax references in the body of the @samp{src} code +Expansion of ``noweb'' syntax references in the body of the @samp{src} code block when tangling. No expansion when evaluating or exporting. @item @code{no-export} -Expansion of ``Noweb'' syntax references in the body of the @samp{src} code +Expansion of ``noweb'' syntax references in the body of the @samp{src} code block when evaluating or tangling. No expansion when exporting. @item @code{strip-export} -Expansion of ``Noweb'' syntax references in the body of the @samp{src} code +Expansion of ``noweb'' syntax references in the body of the @samp{src} code block when expanding prior to evaluating or tangling. Removes ``noweb'' syntax references when exporting. @item @code{eval} -Expansion of ``Noweb'' syntax references in the body of the @samp{src} code +Expansion of ``noweb'' syntax references in the body of the @samp{src} code block only before evaluating. @end itemize @subsubheading Noweb prefix lines -Noweb insertions now honor prefix characters that appear before -@code{<>}. This behavior is illustrated in the following example. -Because the @code{<>} noweb reference appears behind the SQL comment -syntax, each line of the expanded noweb reference will be commented. +Noweb insertions now honor prefix characters that appear before the ``noweb'' +syntax reference. -This @samp{src} code block: +This behavior is illustrated in the following example. Because the +@code{<>} noweb reference appears behind the SQL comment syntax, +each line of the expanded noweb reference will be commented. + +With: @example +#+NAME: example +#+BEGIN_SRC text +this is the +multi-line body of example +#+END_SRC +@end example + +this @samp{src} code block: + +@example +#+BEGIN_SRC sql :noweb yes -- <> +#+END_SRC @end example expands to: @@ -16230,17 +16244,60 @@ expands to: Since this change will 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: + +@example +#+NAME: if-true +#+BEGIN_SRC python :exports none +print('Do things when True') +#+END_SRC + +#+NAME: if-false +#+BEGIN_SRC python :exports none +print('Do things when False') +#+END_SRC +@end example + +this @samp{src} code block: + +@example +#+BEGIN_SRC python :noweb yes :results output +if True: + <> +else: + <> +#+END_SRC +@end example + +expands to: + +@example +if True: + print('Do things when True') +else: + print('Do things when False') +@end example + +and evaluates to: + +@example +Do things when True +@end example + @node noweb-ref @subsubsection @code{:noweb-ref} @cindex @code{:noweb-ref}, src header argument When expanding ``noweb'' style references, Org concatenates @samp{src} code -blocks by matching the reference name to either the block name or the +blocks by matching the reference name to either the code block name or the @code{:noweb-ref} header argument. For simple concatenation, set this @code{:noweb-ref} header argument at the sub-tree or file level. In the example Org file shown next, the body of the -source code in each block is extracted for concatenation to a pure code file. +source code in each block is extracted for concatenation to a pure code file +when tangled. @example #+BEGIN_SRC sh :tangle yes :noweb yes :shebang #!/bin/sh @@ -16756,25 +16813,67 @@ references in the @samp{src} code block before evaluation. For the header argument @code{:noweb no}, Org does not expand ``noweb'' style references in the @samp{src} code block before evaluation. -The default is @code{:noweb no}. +The default is @code{:noweb no}. Org defaults to @code{:noweb no} so as not +to cause errors in languages where ``noweb'' syntax is ambiguous. Change +Org's default to @code{:noweb yes} for languages where there is no risk of +confusion. Org offers a more flexible way to resolve ``noweb'' style references (@pxref{noweb-ref}). -Org can handle naming of @emph{results} block, rather than the body of the -@samp{src} code block, using ``noweb'' style references. - -For ``noweb'' style reference, append parenthesis to the code block name for -arguments, as shown in this example: +Org can include the @emph{results} of a code block rather than its body. To +that effect, append parentheses, possibly including arguments, to the code +block name, as show below. @example <> @end example -Note: Org defaults to @code{:noweb no} so as not to cause errors in languages -such as @samp{Ruby} where ``noweb'' syntax is equally valid characters. For -example, @code{<>}. Change Org's default to @code{:noweb yes} for -languages where there is no risk of confusion. +Note that when using the above approach to a code block's results, the code +block name set by @code{#+NAME} keyword is required; the reference set by +@code{:noweb-ref} will not work. + +Here is an example that demonstrates how the exported content changes when +``noweb'' style references are used with parentheses versus without. + +With: + +@example +#+NAME: some-code +#+BEGIN_SRC python :var num=0 :results output :exports none +print(num*10) +#+END_SRC +@end example + +this code block: + +@example +#+BEGIN_SRC text :noweb yes +<> +#+END_SRC +@end example + +expands to: + +@example +print(num*10) +@end example + +Below, a similar ``noweb'' style reference is used, but with parentheses, +while setting a variable @code{num} to 10: + +@example +#+BEGIN_SRC text :noweb yes +<> +#+END_SRC +@end example + +Note that now the expansion contains the @emph{results} of the code block +@code{some-code}, not the code block itself: + +@example +100 +@end example For faster tangling of large Org mode files, set @code{org-babel-use-quick-and-dirty-noweb-expansion} variable to @code{t}. -- 2.13.0