Re: [PATCH] noweb documentation update

[Nicolas Goaziou <mail@nicolasgoaziou.fr>]

Hello,

Kaushal Modi <kaushal.modi@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