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 <m...@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
0001-Improve-noweb-documentation.patch
Description: Binary data
