Tangling without clutter?

Tangling without clutter?

[Jos'h Fuller]

Hi!

I was writing some documentation about how to use a Python function, so I decided to try the tangling feature. However, the result, when exported to PDF, is unsatisfactory because the referenced code block is included twice -- first in the original location, then again where I referenced it with <<function-definition>>. 

This is, of course, exactly what it needs to do to be able to execute the code properly and show the result. But it doesn't look nice. Is there any way to suppress the second printing inside the function-demo block?
 
If this isn't clear from the example below, I can provide examples of the duplication in action as well as what I'd like the output to look like.

Thanks very much!

Example file:
#+TITLE:     Tangle Test
#+LANGUAGE:  en
#+OPTIONS:   H:3 num:nil toc:nil \n:nil @:t ::t |:t ^:nil -:t f:t *:t <:t
#+OPTIONS:   TeX:t LaTeX:t skip:nil d:nil todo:t pri:nil tags:not-in-toc

* Tangled Code
  I want to show the definition of a function first:
  #+name: function-definition
  #+begin_src python :tangle yes :exports code
    def entable(data):
        if not data: return "/No data./"
        
        columns = len(data[0])
        sizes   = [0,]*columns
        for row in data:
            sizes = [max(x) for x in zip(sizes, [len(str(t)) for t in row])]
    
        format = "| " + " | ".join(["%%%ds" % x for x in sizes])+" |"
        return "\n".join([format % tuple(row) for row in data])
  #+end_src

  Now I want to show a demonstration of how the function might be
  called. I need the function to be included so that demonstration
  code can be executed, but I don't want to include the function
  definition twice:

  #+name: function-demo
  #+begin_src python :tangle yes :exports both :noweb yes :results output
    <<function-definition>>
    
    print entable([["One", 2, 3],["Four", 5, 6], ["Seven", 8, 9]])
  #+end_src

  Which gives us this result:

  #+results: function-demo
  : |   One | 2 | 3 |
  : |  Four | 5 | 6 |
  : | Seven | 8 | 9 |

Re: Tangling without clutter?

[Thomas S. Dye]

Jos'h Fuller <Jos'h.Fuller@arcproductions.com> writes:

> Hi!
>
> I was writing some documentation about how to use a Python function, so I decided to try the tangling feature. However, the result, when exported to PDF, is unsatisfactory because the referenced code block is included twice -- first in the original location, then again where I referenced it with <<function-definition>>. 
>
> This is, of course, exactly what it needs to do to be able to execute the code properly and show the result. But it doesn't look nice. Is there any way to suppress the second printing inside the function-demo block?
>  
> If this isn't clear from the example below, I can provide examples of the duplication in action as well as what I'd like the output to look like.
>
> Thanks very much!
>
> Example file:
> #+TITLE:     Tangle Test
> #+LANGUAGE:  en
> #+OPTIONS:   H:3 num:nil toc:nil \n:nil @:t ::t |:t ^:nil -:t f:t *:t <:t
> #+OPTIONS:   TeX:t LaTeX:t skip:nil d:nil todo:t pri:nil tags:not-in-toc
>
> * Tangled Code
>   I want to show the definition of a function first:
>   #+name: function-definition
>   #+begin_src python :tangle yes :exports code
>     def entable(data):
>         if not data: return "/No data./"
>         
>         columns = len(data[0])
>         sizes   = [0,]*columns
>         for row in data:
>             sizes = [max(x) for x in zip(sizes, [len(str(t)) for t in row])]
>     
>         format = "| " + " | ".join(["%%%ds" % x for x in sizes])+" |"
>         return "\n".join([format % tuple(row) for row in data])
>   #+end_src
>
>   Now I want to show a demonstration of how the function might be
>   called. I need the function to be included so that demonstration
>   code can be executed, but I don't want to include the function
>   definition twice:
>
>   #+name: function-demo
>   #+begin_src python :tangle yes :exports both :noweb yes :results output
>     <<function-definition>>
>     
>     print entable([["One", 2, 3],["Four", 5, 6], ["Seven", 8, 9]])
>   #+end_src
>
>   Which gives us this result:
>
>   #+results: function-demo
>   : |   One | 2 | 3 |
>   : |  Four | 5 | 6 |
>   : | Seven | 8 | 9 |
>
>
Aloha!

Does the :no-expand header argument do what you want?  See
http://orgmode.org/manual/no_002dexpand.html#no_002dexpand.

hth,
Tom
-- 
Thomas S. Dye
http://www.tsdye.com

Re: Tangling without clutter?

[Eric Schulte]

Jos'h Fuller <Jos'h.Fuller@arcproductions.com> writes:

> Hi!
>
>> > It seems like I almost need some variant of the "tangle" argument to
>> > :noweb where syntax references are expanded for evaluation, but not
>> > for anything else.
>> >
>> 
>> Why would you want to tangle out a python src file with an un-expanded
>> noweb reference?  Either way, who am I to judge.  I've just added a new
>> "eval" option to the noweb header argument which will expand noweb
>> references *only* during interactive evaluation.
>
> Please allow me to explain, I think it's a legitimate use case...
>
> I would like to provide a listing of a Python function, then later in
> the document show a demonstration of how it's used. I just did this
> when preparing some documentation for another programmer who is
> porting an application between languages.
>
> So I listed the function, then after a discussion, I had a
> demonstration of how to use the function. I wanted the output from the
> demonstration to be "live", generated from the demonstration
> code. Therefore, I needed to reference the function defined
> above. Unfortunately, the reference was expanded during export so that
> the same block of code appeared /twice/, presenting the reader with
> something like this:
>
> : Here's a function:
> :  def gorking():
> :   return "gork"
> :
> : Here's how to use the function:
> :  def gorking():
> :   return "gork"
> :
> :  print gorking()
> : 
> : Which gives us:
> :  gork
>
> As you can see, it's rather clumsy to have the function in the output
> twice. It's not too bad for this example, but anything more than a few
> lines becomes quite a distraction! This would have been preferable:
>
> : Here's a function:
> :  def gorking():
> :   return "gork"
> :
> : Here's how to use the function:
> :  <<function-gorking>>
> : 
> :  print gorking()
> : 
> : Which gives us:
> :  gork
>
> The original %.org file would look like this:
>
> : Here's a function:
> :  #+name: function-gorking
> :  #+begin_src python :tangle yes
> :  def gorking():
> :   return "gork"
> :  #+end_src
> :
> : Here's how to use the function:
> :  #+name: function-gorking-demo
> :  #+begin_src python :tangle yes
> :  <<function-gorking>>
> :
> :  print gorking()
> :  #+end_src
> : 
> : Which gives us:
> :  #+results: function-gorking-demo
> :  gork
>
> Does that explain it better?
>

Yes, although it seems that the existing "no-export" or "strip-export"
options to the :noweb header argument may better suit your purposes.
These are described in the Org-mode manual, however, they are not
mentioned in the online version of the manual which is out of date.

Cheers,

>
> Thanks!
>
> Jos'h
>
>
>

-- 
Eric Schulte
http://cs.unm.edu/~eschulte/

Re: Tangling without clutter?

[Jos'h Fuller]

Hi!

> Does the :no-expand header argument do what you want?  See
> http://orgmode.org/manual/no_002dexpand.html#no_002dexpand.

I tried using it like this:

  #+name: function-demo
  #+begin_src python :exports both :noweb yes :results output :no-expand
    <<function-definition>>
    
    print entable([["One", 2, 59],["Four", 5, 27], ["Seven", 8, 9]])
  #+end_src

But it didn't seem to affect the results at all. I may be using it wrong, the documentation is a bit sparse, without any examples...

It seems like I almost need some variant of the "tangle" argument to :noweb where syntax references are expanded for evaluation, but not for anything else. 

Thanks for taking a look!

Jos'h


> -----Original Message-----
> From: Thomas S. Dye [mailto:tsd@tsdye.com]
> Sent: Wednesday, March 14, 2012 2:23 PM
> To: Jos'h Fuller
> Cc: emacs-orgmode@gnu.org
> Subject: Re: Tangling without clutter?
> 
> Jos'h Fuller <Jos'h.Fuller@arcproductions.com> writes:
> 
> > Hi!
> >
> > I was writing some documentation about how to use a Python function,
> so I decided to try the tangling feature. However, the result, when
> exported to PDF, is unsatisfactory because the referenced code block is
> included twice -- first in the original location, then again where I
> referenced it with <<function-definition>>.
> >
> > This is, of course, exactly what it needs to do to be able to execute
> the code properly and show the result. But it doesn't look nice. Is
> there any way to suppress the second printing inside the function-demo
> block?
> >
> > If this isn't clear from the example below, I can provide examples of
> the duplication in action as well as what I'd like the output to look
> like.
> >
> > Thanks very much!
> >
> > Example file:
> > #+TITLE:     Tangle Test
> > #+LANGUAGE:  en
> > #+OPTIONS:   H:3 num:nil toc:nil \n:nil @:t ::t |:t ^:nil -:t f:t *:t
> <:t
> > #+OPTIONS:   TeX:t LaTeX:t skip:nil d:nil todo:t pri:nil tags:not-in-
> toc
> >
> > * Tangled Code
> >   I want to show the definition of a function first:
> >   #+name: function-definition
> >   #+begin_src python :tangle yes :exports code
> >     def entable(data):
> >         if not data: return "/No data./"
> >
> >         columns = len(data[0])
> >         sizes   = [0,]*columns
> >         for row in data:
> >             sizes = [max(x) for x in zip(sizes, [len(str(t)) for t in
> row])]
> >
> >         format = "| " + " | ".join(["%%%ds" % x for x in sizes])+" |"
> >         return "\n".join([format % tuple(row) for row in data])
> >   #+end_src
> >
> >   Now I want to show a demonstration of how the function might be
> >   called. I need the function to be included so that demonstration
> >   code can be executed, but I don't want to include the function
> >   definition twice:
> >
> >   #+name: function-demo
> >   #+begin_src python :tangle yes :exports both :noweb yes :results
> output
> >     <<function-definition>>
> >
> >     print entable([["One", 2, 3],["Four", 5, 6], ["Seven", 8, 9]])
> >   #+end_src
> >
> >   Which gives us this result:
> >
> >   #+results: function-demo
> >   : |   One | 2 | 3 |
> >   : |  Four | 5 | 6 |
> >   : | Seven | 8 | 9 |
> >
> >
> Aloha!
> 
> Does the :no-expand header argument do what you want?  See
> http://orgmode.org/manual/no_002dexpand.html#no_002dexpand.
> 
> hth,
> Tom
> --
> Thomas S. Dye
> http://www.tsdye.com

Re: Tangling without clutter?

[Eric Schulte]

Jos'h Fuller <Jos'h.Fuller@arcproductions.com> writes:

> Hi!
>
>> Does the :no-expand header argument do what you want?  See
>> http://orgmode.org/manual/no_002dexpand.html#no_002dexpand.
>
> I tried using it like this:
>
>   #+name: function-demo
>   #+begin_src python :exports both :noweb yes :results output :no-expand
>     <<function-definition>>
>     
>     print entable([["One", 2, 59],["Four", 5, 27], ["Seven", 8, 9]])
>   #+end_src
>
> But it didn't seem to affect the results at all. I may be using it
> wrong, the documentation is a bit sparse, without any examples...
>
> It seems like I almost need some variant of the "tangle" argument to
> :noweb where syntax references are expanded for evaluation, but not
> for anything else.
>

Why would you want to tangle out a python src file with an un-expanded
noweb reference?  Either way, who am I to judge.  I've just added a new
"eval" option to the noweb header argument which will expand noweb
references *only* during interactive evaluation.

Best,

>
> Thanks for taking a look!
>
> Jos'h
>
>
>> -----Original Message-----
>> From: Thomas S. Dye [mailto:tsd@tsdye.com]
>> Sent: Wednesday, March 14, 2012 2:23 PM
>> To: Jos'h Fuller
>> Cc: emacs-orgmode@gnu.org
>> Subject: Re: Tangling without clutter?
>> 
>> Jos'h Fuller <Jos'h.Fuller@arcproductions.com> writes:
>> 
>> > Hi!
>> >
>> > I was writing some documentation about how to use a Python function,
>> so I decided to try the tangling feature. However, the result, when
>> exported to PDF, is unsatisfactory because the referenced code block is
>> included twice -- first in the original location, then again where I
>> referenced it with <<function-definition>>.
>> >
>> > This is, of course, exactly what it needs to do to be able to execute
>> the code properly and show the result. But it doesn't look nice. Is
>> there any way to suppress the second printing inside the function-demo
>> block?
>> >
>> > If this isn't clear from the example below, I can provide examples of
>> the duplication in action as well as what I'd like the output to look
>> like.
>> >
>> > Thanks very much!
>> >
>> > Example file:
>> > #+TITLE:     Tangle Test
>> > #+LANGUAGE:  en
>> > #+OPTIONS:   H:3 num:nil toc:nil \n:nil @:t ::t |:t ^:nil -:t f:t *:t
>> <:t
>> > #+OPTIONS:   TeX:t LaTeX:t skip:nil d:nil todo:t pri:nil tags:not-in-
>> toc
>> >
>> > * Tangled Code
>> >   I want to show the definition of a function first:
>> >   #+name: function-definition
>> >   #+begin_src python :tangle yes :exports code
>> >     def entable(data):
>> >         if not data: return "/No data./"
>> >
>> >         columns = len(data[0])
>> >         sizes   = [0,]*columns
>> >         for row in data:
>> >             sizes = [max(x) for x in zip(sizes, [len(str(t)) for t in
>> row])]
>> >
>> >         format = "| " + " | ".join(["%%%ds" % x for x in sizes])+" |"
>> >         return "\n".join([format % tuple(row) for row in data])
>> >   #+end_src
>> >
>> >   Now I want to show a demonstration of how the function might be
>> >   called. I need the function to be included so that demonstration
>> >   code can be executed, but I don't want to include the function
>> >   definition twice:
>> >
>> >   #+name: function-demo
>> >   #+begin_src python :tangle yes :exports both :noweb yes :results
>> output
>> >     <<function-definition>>
>> >
>> >     print entable([["One", 2, 3],["Four", 5, 6], ["Seven", 8, 9]])
>> >   #+end_src
>> >
>> >   Which gives us this result:
>> >
>> >   #+results: function-demo
>> >   : |   One | 2 | 3 |
>> >   : |  Four | 5 | 6 |
>> >   : | Seven | 8 | 9 |
>> >
>> >
>> Aloha!
>> 
>> Does the :no-expand header argument do what you want?  See
>> http://orgmode.org/manual/no_002dexpand.html#no_002dexpand.
>> 
>> hth,
>> Tom
>> --
>> Thomas S. Dye
>> http://www.tsdye.com
>

-- 
Eric Schulte
http://cs.unm.edu/~eschulte/

Re: Tangling without clutter?

[Jos'h Fuller]

Hi!

> > It seems like I almost need some variant of the "tangle" argument to
> > :noweb where syntax references are expanded for evaluation, but not
> > for anything else.
> >
> 
> Why would you want to tangle out a python src file with an un-expanded
> noweb reference?  Either way, who am I to judge.  I've just added a new
> "eval" option to the noweb header argument which will expand noweb
> references *only* during interactive evaluation.

Please allow me to explain, I think it's a legitimate use case...

I would like to provide a listing of a Python function, then later in the document show a demonstration of how it's used. I just did this when preparing some documentation for another programmer who is porting an application between languages. 

So I listed the function, then after a discussion, I had a demonstration of how to use the function. I wanted the output from the demonstration to be "live", generated from the demonstration code. Therefore, I needed to reference the function defined above. Unfortunately, the reference was expanded during export so that the same block of code appeared /twice/, presenting the reader with something like this:

: Here's a function:
:  def gorking():
:   return "gork"
:
: Here's how to use the function:
:  def gorking():
:   return "gork"
:
:  print gorking()
: 
: Which gives us:
:  gork

As you can see, it's rather clumsy to have the function in the output twice. It's not too bad for this example, but anything more than a few lines becomes quite a distraction! This would have been preferable:

: Here's a function:
:  def gorking():
:   return "gork"
:
: Here's how to use the function:
:  <<function-gorking>>
: 
:  print gorking()
: 
: Which gives us:
:  gork

The original %.org file would look like this:

: Here's a function:
:  #+name: function-gorking
:  #+begin_src python :tangle yes
:  def gorking():
:   return "gork"
:  #+end_src
:
: Here's how to use the function:
:  #+name: function-gorking-demo
:  #+begin_src python :tangle yes
:  <<function-gorking>>
:
:  print gorking()
:  #+end_src
: 
: Which gives us:
:  #+results: function-gorking-demo
:  gork

Does that explain it better?

Thanks!

Jos'h

Re: Tangling without clutter?

[Eric Schulte]

Jos'h Fuller <Jos'h.Fuller@arcproductions.com> writes:

> Hi!
>
>> Yes, although it seems that the existing "no-export" or "strip-export"
>> options to the :noweb header argument may better suit your purposes.
>> These are described in the Org-mode manual, however, they are not
>> mentioned in the online version of the manual which is out of date.
>
> I thought I had the latest at 7.8.03... Are you referring to a
> development version? I don't see a reference to those in the
> documentation that came with that version.
>

I was referring to the head of the git repository, which can be
installed following the instructions from the main org-mode page.

Best,

-- 
Eric Schulte
http://cs.unm.edu/~eschulte/

Re: Tangling without clutter?

[Jos'h Fuller]

Hi!

> Yes, although it seems that the existing "no-export" or "strip-export"
> options to the :noweb header argument may better suit your purposes.
> These are described in the Org-mode manual, however, they are not
> mentioned in the online version of the manual which is out of date.

I thought I had the latest at 7.8.03... Are you referring to a development version? I don't see a reference to those in the documentation that came with that version.

Thanks!

Jos'h

Re: Tangling without clutter?

[Viktor Rosenfeld]

Hi Jos'h,

have you looked at the :session header argument? I use it to define
environment variables in bash that are used in later code blocks.

Something like this:

#+BEGIN_SRC sh :session foo
export W="world."
#+END_SRC

#+RESULTS:

#+BEGIN_SRC sh :session foo
echo Hello $W
#+END_SRC

If these code blocks are executed in order, the latter returns "Hello
world."

Not sure though, how it interacts with Python.

Cheers,
Viktor

Jos'h Fuller wrote:

> Hi!
> 
> > > It seems like I almost need some variant of the "tangle" argument to
> > > :noweb where syntax references are expanded for evaluation, but not
> > > for anything else.
> > >
> > 
> > Why would you want to tangle out a python src file with an un-expanded
> > noweb reference?  Either way, who am I to judge.  I've just added a new
> > "eval" option to the noweb header argument which will expand noweb
> > references *only* during interactive evaluation.
> 
> Please allow me to explain, I think it's a legitimate use case...
> 
> I would like to provide a listing of a Python function, then later in the document show a demonstration of how it's used. I just did this when preparing some documentation for another programmer who is porting an application between languages. 
> 
> So I listed the function, then after a discussion, I had a demonstration of how to use the function. I wanted the output from the demonstration to be "live", generated from the demonstration code. Therefore, I needed to reference the function defined above. Unfortunately, the reference was expanded during export so that the same block of code appeared /twice/, presenting the reader with something like this:
> 
> : Here's a function:
> :  def gorking():
> :   return "gork"
> :
> : Here's how to use the function:
> :  def gorking():
> :   return "gork"
> :
> :  print gorking()
> : 
> : Which gives us:
> :  gork
> 
> As you can see, it's rather clumsy to have the function in the output twice. It's not too bad for this example, but anything more than a few lines becomes quite a distraction! This would have been preferable:
> 
> : Here's a function:
> :  def gorking():
> :   return "gork"
> :
> : Here's how to use the function:
> :  <<function-gorking>>
> : 
> :  print gorking()
> : 
> : Which gives us:
> :  gork
> 
> The original %.org file would look like this:
> 
> : Here's a function:
> :  #+name: function-gorking
> :  #+begin_src python :tangle yes
> :  def gorking():
> :   return "gork"
> :  #+end_src
> :
> : Here's how to use the function:
> :  #+name: function-gorking-demo
> :  #+begin_src python :tangle yes
> :  <<function-gorking>>
> :
> :  print gorking()
> :  #+end_src
> : 
> : Which gives us:
> :  #+results: function-gorking-demo
> :  gork
> 
> Does that explain it better?
> 
> Thanks!
> 
> Jos'h
> 
> 
> 

Re: Tangling without clutter?

[Jacek Generowicz]

At Thu, 15 Mar 2012 07:25:47 +0100,
Viktor Rosenfeld wrote:
> 
> Hi Jos'h,
> 
> have you looked at the :session header argument? I use it to define
> environment variables in bash that are used in later code blocks.
> 
> Something like this:
> 
> #+BEGIN_SRC sh :session foo
> export W="world."
> #+END_SRC
> 
> #+RESULTS:
> 
> #+BEGIN_SRC sh :session foo
> echo Hello $W
> #+END_SRC
> 
> If these code blocks are executed in order, the latter returns "Hello
> world."

Which is exactly how I was planning to use org babel to prepare a lot
of Python-based teaching material. Unfortunately ...

> Not sure though, how it interacts with Python.

... it interacts with Python in a less than ideal way. In effect, it
pretends you typed the code in the Python source block, into Python's
standard interactive shell. This leads to problems: Imagine that you
want to demonstrate how to write a simple class in Python, and that
you wish to follow Python's style guide, which states that "Method
definitions inside a class are separated by a single blank line."

So you present this example code

#+begin_src python :session :results output
class Foo:

    def __init__(self, state):
        self.state = state

    def get(self):
        return self.state
#+end_src

in the hope of writing some explanatory notes about it, before
demonstrating its use

#+begin_src python :session :results output
f = Foo('frustrated')
print f.get()
#+end_src

Unfortunately, the plan is foiled because the class definiton in the
first block fails to execute properly. This happens because Python's
standard interactive shell (in contrast to Python's non interactive
mode) understands blank lines to close all currently open blocks. This
results in the =class Foo:= block being closed before any of its
components have been defined, at which point the whole thing goes
pear-shaped.

Currently there are two things you can do to get around this problem.

1. Remove any blank lines which are inside any block in any of your
   code (resulting in very ugly and heterodox formatting of your
   Python code: not the sort of thing you want to be doing in
   tutorials, lectures, documentation, etc.).

2. Hunt down all blank lines which are inside a block, and add enough
   whitespace to match the indentation of the next non-whitespace line
   in that block (very tedious and very fragile).


Last week I had a short exchange about this, on list, with Eric
Schulte, and seem to have persuaded him that the current state of
affairs is not the desired one.

I am planning to have a look at how the situation can be improved with
the aim of providing a patch, but

1. I have zero time to devote to this in the next few weeks.

2. I have never tinkered with babel's internals before, so I cannot
   guarantee success, or quality of output.


In the meantime, I have *slightly* changed my position, since the
exchange with Eric. Last week I claimed that what the session mode
should do is, essentially, emulate Emacs' python-mode's C-c C-c
(execute the code block in the context of the session without choking
on blank lines, and without echoing any of the code itself). I stand
by this being the desired primary behaviour, but I do admit that an
alternative valid (though less important) use case would be to have
the code in the src block be 'typed' into a standard interactive
session, and have the whole session (prompt, input, output) be
produced as the result. (IIRC, this currently doesn't work properly
either: the prompts and the inputs are out of sync, and you get a
horrible mess.)