[babel] Org-babel vs NoWeb (and the like)

[babel] Org-babel vs NoWeb (and the like)

[Sébastien Vauban]

Hi Dan and Eric,

Please find here a document written with both NoWeb and Org-babel, to be able
to compare and explain the differences between both approaches.

What's *nice with Org-babel* is:

- code is easy to edit in the source buffer with =C-c '= (highlighted
  correctly in the indirect buffer)
- source (Org text + code) is much, much more readable (with nicely
  highlighted sections)
- all the source blocks are correctly colored in the PDF, according to the
  source language (via listings) -- even the ones that are not tangled

Org-babel source: http://www.mygooglest.com/sva/ecm-babel-org.org
Org-babel PDF: http://www.mygooglest.com/sva/ecm-babel-org.pdf

What's *not nice with Noweb* is:

- source (Org text + code) is even less readable than LaTeX, and not really
  correctly fontified by current Emacs modes (being "extended" LaTeX)
- code must be tangled through an external command
- source blocks are just verbatim (with yellow background in my case), but no
  language-sensitive highlighting
- only tangled outputs that are re-imported in the document through listings
  can be highlighted correctly in the PDF

Noweb source: http://www.mygooglest.com/sva/ecm-noweb.nw
Noweb PDF: http://www.mygooglest.com/sva/ecm-noweb.pdf

Though, what's *nice with Noweb* is:

- every code snippet is identified (left, in the PDF) by a counter, for easy
  reference (page + order position) from another block of code
- every code snippet lists where it's used (right, in the PDF), using the same
  counters
- tangled code is correctly indented

These last points are, for me, the only "drawbacks" (a "big word" -- dunno
which other word to use, not native speaker) of Org-babel for literate
programming.

Would they be fixed, Org-babel would clearly, clearly, clearly out-beats all
alternative I'm aware of (Nuweb and NoWeb)...

Would they never be fixed, I still prefer Org-babel (vs NoWeb)!

Best regards,
  Seb

-- 
Sébastien Vauban



_______________________________________________
Emacs-orgmode mailing list
Please use `Reply All' to send replies to the list.
Emacs-orgmode-mXXj517/zsQ@public.gmane.org
http://lists.gnu.org/mailman/listinfo/emacs-orgmode

Re: [babel] Org-babel vs NoWeb (and the like)

[Eric Schulte]

Hi Sébastien,

Sorry to take so long to reply.  Thanks for this comparison, as someone
with no personal Noweb experience it is very enlightening to hear how it
compares and contrasts with Org-babel.  It sounds like the three places
where Org-babel can still improve vs. Noweb are

> - every code snippet is identified (left, in the PDF) by a counter, for easy
>   reference (page + order position) from another block of code
> - every code snippet lists where it's used (right, in the PDF), using the same
>   counters
> - tangled code is correctly indented

I believe that indentation should be fixed by now, if that's not the
case please shoot me an example where it breaks and I'll take a look.

As for the names and references of source-code blocks there is certainly
still work to be done on the babel side.  I just released some code
which does add source-code block names to exported output (using
listings in latex, and as a <label> in html) however it is currently not
as *attractive* or *informative* as the Noweb block identification.

- attractive :: as opposed to relying on the listings package to name
     source-code blocks it should be possible to implement better
     looking source-code block names by including more raw LaTeX in the
     org-babel exporter.  My feeling is that the centering of the title
     in the current export is more difficult to read than would be a
     left-justified title as used in the Noweb export.  Also, it would
     be nice to better associate the title with the code.  Noweb
     accomplishes this by actually pushing the source-code block name
     into the block of source-code.  I'm wary of moving too far in that
     direction as I don't want the complication of interfering with the
     internals of the listings package.  If anyone with more LaTeX-foo
     than myself can propose a raw latex solution I can handle fitting
     it into the exporter.

- informative :: it should be possible for Org-babel to collect the
     names of every source-code block in which a given block is
     referenced.  With that information we could then provide a list of
     the referencing blocks along with an exported block.  As this list
     could be quite long (using names rather than numbers) I am not sure
     what a good default method for displaying the list would be.
     Possibly this information should be displayable separate from the
     body of the source-code block with a

#+referenced: source-block-name

     line or something similar.

- linking :: It seems like it would be nice to be able to link to
     source-code blocks using their names.  This features would probably
     be useful both inside of org-mode files and in exported LaTeX and
     HTML pages.  Both of these should be possible through making
     the #+srcname: lines act as link targets -- I'm not sure if this
     would be hard to implement or if it would trample of existing
     Org-mode semantics but it seems to me like it would be handy.

Thanks for reading this rambling reply.  The original email has
certainly been food for thought. -- Eric

Sébastien Vauban <wxhgmqzgwmuf@spammotel.com> writes:

> Hi Dan and Eric,
>
> Please find here a document written with both NoWeb and Org-babel, to be able
> to compare and explain the differences between both approaches.
>
> What's *nice with Org-babel* is:
>
> - code is easy to edit in the source buffer with =C-c '= (highlighted
>   correctly in the indirect buffer)
> - source (Org text + code) is much, much more readable (with nicely
>   highlighted sections)
> - all the source blocks are correctly colored in the PDF, according to the
>   source language (via listings) -- even the ones that are not tangled
>
> Org-babel source: http://www.mygooglest.com/sva/ecm-babel-org.org
> Org-babel PDF: http://www.mygooglest.com/sva/ecm-babel-org.pdf
>
> What's *not nice with Noweb* is:
>
> - source (Org text + code) is even less readable than LaTeX, and not really
>   correctly fontified by current Emacs modes (being "extended" LaTeX)
> - code must be tangled through an external command
> - source blocks are just verbatim (with yellow background in my case), but no
>   language-sensitive highlighting
> - only tangled outputs that are re-imported in the document through listings
>   can be highlighted correctly in the PDF
>
> Noweb source: http://www.mygooglest.com/sva/ecm-noweb.nw
> Noweb PDF: http://www.mygooglest.com/sva/ecm-noweb.pdf
>
> Though, what's *nice with Noweb* is:
>
> - every code snippet is identified (left, in the PDF) by a counter, for easy
>   reference (page + order position) from another block of code
> - every code snippet lists where it's used (right, in the PDF), using the same
>   counters
> - tangled code is correctly indented
>
> These last points are, for me, the only "drawbacks" (a "big word" -- dunno
> which other word to use, not native speaker) of Org-babel for literate
> programming.
>
> Would they be fixed, Org-babel would clearly, clearly, clearly out-beats all
> alternative I'm aware of (Nuweb and NoWeb)...
>
> Would they never be fixed, I still prefer Org-babel (vs NoWeb)!
>
> Best regards,
>   Seb