[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [O] [PATCH] noweb documentation update
From: |
Nicolas Goaziou |
Subject: |
Re: [O] [PATCH] noweb documentation update |
Date: |
Thu, 22 Jun 2017 09:05:27 +0200 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/25.2 (gnu/linux) |
Hello,
Kaushal Modi <address@hidden> 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
> address@hidden 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:
> address@hidden
> +In Python 3, with "str='foo'", "print(str)" would print:
> +
> + foo
> +
> address@hidden example
Would it be better to split it into two distinct examples?
Regards,
--
Nicolas Goaziou
- [O] How to use noweb reference with argument in other languages?, address@hidden, 2017/06/19
- Re: [O] How to use noweb reference with argument in other languages?, Kaushal Modi, 2017/06/19
- Re: [O] How to use noweb reference with argument in other languages?, address@hidden, 2017/06/19
- Re: [O] How to use noweb reference with argument in other languages?, Kaushal Modi, 2017/06/20
- Re: [O] How to use noweb reference with argument in other languages?, address@hidden, 2017/06/20
- [O] [PATCH] noweb documentation update (Was: Re: How to use noweb reference with argument..), Kaushal Modi, 2017/06/21
- Re: [O] [PATCH] noweb documentation update,
Nicolas Goaziou <=
- Re: [O] [PATCH] noweb documentation update, Kaushal Modi, 2017/06/22
- Re: [O] [PATCH] noweb documentation update, Kaushal Modi, 2017/06/22
- Re: [O] [PATCH] noweb documentation update, Nicolas Goaziou, 2017/06/22
- Re: [O] [PATCH] noweb documentation update, Kaushal Modi, 2017/06/22
- Re: [O] [PATCH] noweb documentation update, Nicolas Goaziou, 2017/06/23
- Re: [O] [PATCH] noweb documentation update, Kaushal Modi, 2017/06/23