From: Kaushal Modi <kaushal.modi@gmail.com>
To: Nicolas Goaziou <mail@nicolasgoaziou.fr>
Cc: sjLambda@gmail.com, emacs-org list <emacs-orgmode@gnu.org>
Subject: Re: [PATCH] noweb documentation update
Date: Thu, 22 Jun 2017 19:13:01 +0000 [thread overview]
Message-ID: <CAFyQvY2zcg3YLA-D3GEOW_D+9a91tuvaeO+Ze=tkjK-DjFRioA@mail.gmail.com> (raw)
In-Reply-To: <CAFyQvY0Ck6qZjihCzgys+Fust5Z7s=wrN8k=JZmC19Pg2Jaz=A@mail.gmail.com>
[-- Attachment #1.1: Type: text/plain, Size: 308 bytes --]
A quick update.. the attached patch has minor formatting fixes over the
previous one.
Please use this patch for review.
Thanks.
On Thu, Jun 22, 2017 at 3:01 PM Kaushal Modi <kaushal.modi@gmail.com> wrote:
> Hello,
>
> Thanks. My comments are below, and the updated patch is attached.
>
--
Kaushal Modi
[-- Attachment #1.2: Type: text/html, Size: 772 bytes --]
[-- Attachment #2: 0001-Improve-noweb-documentation.patch --]
[-- Type: application/octet-stream, Size: 7168 bytes --]
From 9580d645d001defb098d83f90d58e6a36f6220e3 Mon Sep 17 00:00:00 2001
From: Kaushal Modi <kaushal.modi@gmail.com>
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{<<reference>>}. This behavior is illustrated in the following example.
-Because the @code{<<example>>} 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{<<example>>} 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
-- <<example>>
+#+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:
+ <<if-true>>
+else:
+ <<if-false>>
+#+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
<<code-block-name(optional arguments)>>
@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{<<arg>>}. 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
+<<some-code>>
+#+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
+<<some-code(num=10)>>
+#+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
next prev parent reply other threads:[~2017-06-22 19:13 UTC|newest]
Thread overview: 13+ messages / expand[flat|nested] mbox.gz Atom feed top
2017-06-19 4:57 How to use noweb reference with argument in other languages? numbchild
2017-06-19 10:21 ` Kaushal Modi
2017-06-19 23:40 ` numbchild
2017-06-20 16:57 ` Kaushal Modi
2017-06-21 2:03 ` numbchild
2017-06-21 16:57 ` [PATCH] noweb documentation update (Was: Re: How to use noweb reference with argument..) Kaushal Modi
2017-06-22 7:05 ` [PATCH] noweb documentation update Nicolas Goaziou
2017-06-22 19:01 ` Kaushal Modi
2017-06-22 19:13 ` Kaushal Modi [this message]
2017-06-22 19:58 ` Nicolas Goaziou
2017-06-22 20:10 ` Kaushal Modi
2017-06-23 5:56 ` Nicolas Goaziou
2017-06-23 10:14 ` Kaushal Modi
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.orgmode.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to='CAFyQvY2zcg3YLA-D3GEOW_D+9a91tuvaeO+Ze=tkjK-DjFRioA@mail.gmail.com' \
--to=kaushal.modi@gmail.com \
--cc=emacs-orgmode@gnu.org \
--cc=mail@nicolasgoaziou.fr \
--cc=sjLambda@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).