Hello,

Thanks. My comments are below, and the updated patch is attached.

In addition to your suggestion:

- Replaced ``Noweb'' with ``noweb'' every where. I am still bugged by the inconsistency that some places have ``noweb'' while some places have just noweb (no quotes). Or would replacing all occurrences of ``noweb'' and noweb with Noweb be better?

- Added more examples under "Noweb prefix lines" sub-heading.

On Thu, Jun 22, 2017 at 3:05 AM Nicolas Goaziou <mail@nicolasgoaziou.fr> wrote:

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.

That's better, thanks.

> - :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.

I agree, that indentation change is reverted. By default everything is left-flushed in org (except where you intend to have indented (see what I did?) lists and such). So I removed that extra spaces from before the property drawer. But I think all such property drawer instances in org.texi have 2 leading spaces, so I will stick to that.

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.

OK. I had simply moved the prior "Note" as it was useful to have the information about :noweb default in one place. I have reworded it as suggested.

Note that I don't know what <<arg>> means in Ruby.

Neither do I. Hope this is fine -- I have removed that line as there is no clear reference to that statement. Quick searching through this also doesn't show anything like <<foo>>: http://ruby-doc.com/docs/ProgrammingRuby/. Also this answer ( https://stackoverflow.com/a/6852104/1219634 ) has reference to "<<", but all it says is that "<<" is an operator.. like in many other languages too.

> +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?

Done.