From mboxrd@z Thu Jan 1 00:00:00 1970 From: Nicolas Goaziou Subject: Re: [PATCH] noweb documentation update Date: Thu, 22 Jun 2017 09:05:27 +0200 Message-ID: <87fues8pu0.fsf@nicolasgoaziou.fr> References: Mime-Version: 1.0 Content-Type: text/plain Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:58383) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dNwBI-0007x6-77 for emacs-orgmode@gnu.org; Thu, 22 Jun 2017 03:05:33 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dNwBH-0003ud-8J for emacs-orgmode@gnu.org; Thu, 22 Jun 2017 03:05:32 -0400 Received: from relay4-d.mail.gandi.net ([2001:4b98:c:538::196]:56940) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1dNwBH-0003uG-1z for emacs-orgmode@gnu.org; Thu, 22 Jun 2017 03:05:31 -0400 In-Reply-To: (Kaushal Modi's message of "Wed, 21 Jun 2017 16:57:31 +0000") List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Sender: "Emacs-orgmode" To: Kaushal Modi Cc: sjLambda@gmail.com, emacs-org list Hello, Kaushal Modi 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{<>}. 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{<>} 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 <> 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