emacs-orgmode
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [O] [PATCH] noweb documentation update


From: Kaushal Modi
Subject: Re: [O] [PATCH] noweb documentation update
Date: Thu, 22 Jun 2017 19:01:10 +0000

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 <address@hidden> 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:
> 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?

Done. 
--

Kaushal Modi

Attachment: 0001-Improve-noweb-documentation.patch
Description: Binary data


reply via email to

[Prev in Thread] Current Thread [Next in Thread]