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

Kaushal Modi