Hello,
Kaushal Modi <kaushal.m...@gmail.com> writes:
> I have attached a patch (rebased off maint) that attempts at clarifying how
> certain aspects of noweb work based on my experience, with few complete
> examples.
Thank you. Some comments follow.
> Note: I had to also revert a little bit of wording change that was made
> recently. I found pre-wording-change version easier to understand. Copying
> Lambda Coder to comment on that.
>
> This is what the current patch has in the "Noweb reference syntax section":
>
> =====
> It is possible to include the @emph{results} of a code block rather than the
> body. This is done by appending parentheses to the code block name which
> may
> optionally contain arguments to the code block as shown below.
> =====
>
> Earlier it was:
>
> =====
> 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:
> =====
I agree the latter is less clear. However, I suggest less convoluted
wording:
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.
> - :PROPERTIES:
> - :header-args: :noweb-ref fullest-disk
> - :END:
> + :PROPERTIES:
> + :header-args: :noweb-ref fullest-disk
> + :END:
I don't think the change above is meaningful here. Anyway it should be
consistent with other examples across the manual.
> ** query all mounted disks
> #+BEGIN_SRC sh
> @@ -16756,25 +16769,49 @@ 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 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.
What about
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. For example, @samp{Ruby} language interprets
@samp{<<arg>>} differently. Change Org's default to @code{:noweb
yes} for languages where there is no risk of confusion.
Note that I don't know what <<arg>> means in Ruby.
> -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:
> +It is possible to include the @emph{results} of a code block rather than the
> +body. This is done by appending parentheses to the code block name which may
> +optionally contain arguments to the code block as shown below.
See above.
> +Notice the difference in how they get exported:
> +@example
> +In Python 3, with "str='foo'", "print(str)" would print:
> +
> + foo
> +
> +@end example
Would it be better to split it into two distinct examples?
Regards,
--
Nicolas Goaziou
