Re: Literate Programming with Org mode

From: "Sébastien Vauban" <wxhgmqzgwmuf-geNee64TY+gS+FvcfC7Uqw@public.gmane.org>
To: emacs-orgmode-mXXj517/zsQ@public.gmane.org
Subject: Re: Literate Programming with Org mode
Date: Mon, 03 Aug 2009 10:42:23 +0200	[thread overview]
Message-ID: <87r5vtffv4.fsf@mundaneum.com> (raw)
In-Reply-To: m263d7vvgp.fsf@gmail.com

Hi Eric,

"Eric Schulte" wrote:
> "Eric Schulte" <schulte.eric-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> writes:
>> Thanks for the description.  This is very interesting and I think
>> warrants a re-working of the tangle functionality in org-babel.

I don't know if it warrants a re-working of the tangle functionality, but it
warrants at least having the possibility to do such documents from withing
Org IMHO.

We're both (many more?) convinced...

>> Given your description below I think I may try to add the Nuweb
>> link/reference syntax "<<source-block-name>>" to org-babel.

Good.

Sorry for the (little) mistake I've made, but -- to be exact -- the above
syntax is from noweb.

Nuweb syntax one is with @ such as the following "include" code:

--8<---------------cut here---------------start------------->8---
@< Cursor abcID : Init on records @>
--8<---------------cut here---------------end--------------->8---

where the thing between `@<' and `@>' is the name of the source.

>> As source-code blocks are already named in the current org-babel setup this
>> wouldn't be a very significant change. Once this is added it shouldn't be
>> difficult to expand these links/references on export.

Excellent.

>> Under this new setup the example file you described would be analogous
>> to the this org-mode file.
>>
>> Does this sound like it would accomplish most of what you are after?

I think so, yes. I'll scan all my Nuweb and noweb files over the past years,
but I am positive you cover all of my needs -- with the exception of one, but
I guess it's solvable somehow: the fact that the code should be included via
the LaTeX `listings' package (thus, colored contextually to the programming
language) and not as verbatim.

> With the newest version of org-babel [1]

Done: `git pull'.

> try opening the attached org-mode file [2] which is an org-mode
> translation of Sébastien's noweb file from his previous email.

I wanted to translate it in Org. You've been much quicker than I currently am.
Thanks.

> Calling `org-babel-tangle' from within this file will create the
> Payment.sql, Lessons.sql, and Enterprise.sql source-code files.

Nope...

--8<---------------cut here---------------start------------->8---
Open ~/Personal/Templates/org-babel-lit-prog.org
tangled 0 source-code blocks
--8<---------------cut here---------------end--------------->8---

I don't understand why.

Is it normal that you don't include the extension in the tangle property?
Does it add the language extension automatically?

> The document can also be exported into html and latex using org-mode's
> standard export functionality.

I have problems as well...

LaTeX error:

--8<---------------cut here---------------start------------->8---
ERROR: Missing \endcsname inserted.

--- TeX said ---
<to be read again>
                   \protect
l.47 \begin{\LaTeX{}}

--- HELP ---
From the .log file...

The control sequence marked <to be read again> should
not appear between \csname and \endcsname.
--8<---------------cut here---------------end--------------->8---

(Begin of) exported file is:

--8<---------------cut here---------------start------------->8---
% Created 2009-08-03 Mon 09:58
\documentclass[final]{article}
\usepackage[utf8x]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{graphicx}
\usepackage{longtable}
\usepackage{hyperref}

\title{Showing the benefits of Literate Programming}
\author{Sebastien Vauban}
\date{03 August 2009}

\begin{document}

\maketitle

\section*{Context}
\label{sec-1}

  I wanna show (or, at least, try to show) some advantages of literate
  programming, such as no copy/pasting of code, and being able to
  explain the code independently of its final structure as ``source
  code''.

  This file is a translation of Sebastien's noweb file into an org-mode
  document.

\section*{Files with SQL commands}
\label{sec-2}

\subsection*{Common Code}
\label{sec-2.1}

    All files have some code in common.

\subsubsection*{Header}
\label{sec-2.1.1}

\begin{\LaTeX{}}  % <--- spot of the error <--- <--- <--- <---
\begin{verbatim}
-- Hey, Emacs! This is a -*- coding: utf-8 -*- file!

-- no longer display the count message
SET NOCOUNT ON

DECLARE @dateFmtStyleIn int; SET @dateFmtStyleIn = 120 -- ODBC canonical
DECLARE @dateFmtStyleOut int; SET @dateFmtStyleOut = 103 -- French dd/mm/yyyy

DECLARE @firstDayOfThisMonth smalldatetime
SET @firstDayOfThisMonth = CONVERT(smalldatetime,
CAST(YEAR(GETDATE()) AS char(4)) + '-'
+ CAST(MONTH(GETDATE()) AS char(2)) + '-'
+ '01' + ' 00:00:00',
@dateFmtStyleIn)
\end{verbatim}
\end{\LaTeX{}}
--8<---------------cut here---------------end--------------->8---

Don't understand how this LaTeX environment comes in the play.

I saw a difference between the way you write your levels in Org and the way I
do it: I'm using a odd number of stars.

--8<---------------cut here---------------start------------->8---
;; skip even levels and only use odd levels for the outline
(setq org-odd-levels-only t)
--8<---------------cut here---------------end--------------->8---

So, I've rewritten the Org file as follows:

--8<---------------cut here---------------start------------->8---
#+TITLE: Showing the benefits of Literate Programming
#+AUTHOR: Sebastien Vauban
#+OPTIONS: toc:nil num:nil ^:nil

* Context

  I wanna show (or, at least, try to show) some advantages of literate
  programming, such as no copy/pasting of code, and being able to
  explain the code independently of its final structure as ``source
  code''.

  This file is a translation of Sebastien's noweb file into an org-mode
  document.

* Files with SQL commands

*** Common Code

    All files have some code in common.

***** Header

#+srcname: sql-init
#+begin_src sql
-- Hey, Emacs! This is a -*- coding: utf-8 -*- file!

-- no longer display the count message
SET NOCOUNT ON

DECLARE @dateFmtStyleIn int; SET @dateFmtStyleIn = 120 -- ODBC canonical
DECLARE @dateFmtStyleOut int; SET @dateFmtStyleOut = 103 -- French dd/mm/yyyy

DECLARE @firstDayOfThisMonth smalldatetime
SET @firstDayOfThisMonth = CONVERT(smalldatetime,
                                   CAST(YEAR(GETDATE()) AS char(4)) + '-'
                                   + CAST(MONTH(GETDATE()) AS char(2)) + '-'
                                   + '01' + ' 00:00:00',
                                   @dateFmtStyleIn)
#+end_src
--8<---------------cut here---------------end--------------->8---

But that does not change anything:

    o   Tangle is not extracting any code block;
    o   same LaTeX error.

Any idea?

BTW, what do you think of my proposal to include the Tangle process as a
built-in step of the export to LaTeX (and HTML)?

That way, we only would export and get both flies caught with one stone.

Thanks for all!  This is seriously a hot topic you've almost solved...

Seb

-- 
Sébastien Vauban

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