From mboxrd@z Thu Jan 1 00:00:00 1970 From: =?utf-8?Q?S=C3=A9bastien_Vauban?= Subject: Literate Programming with Org mode Date: Tue, 28 Jul 2009 18:14:50 +0200 Message-ID: <87my6ordhh.fsf@mundaneum.com> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Return-path: List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org-mXXj517/zsQ@public.gmane.org Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org-mXXj517/zsQ@public.gmane.org To: emacs-orgmode-mXXj517/zsQ@public.gmane.org Hi Eric and all, Here some promised description of how I'm using Literate Programming with LaTeX (up to now -- soon directly from Org mode?). I write an "enhanced LaTeX" file ([1], having the `.nw' -- for Nuweb -- extension). It is enhanced as I can put blocks of code in there (SQL blocks, for example), and give them a name for further referencing. Then, at some point in the file, I say how I want the code files to look li= ke, by assembling the blocks in a certain order, with some glue. For example: --8<---------------cut here---------------start------------->8--- <>=3D <> SELECT abcID, etpID, etpAssurATPolNum FROM enterprise JOIN record ON (etpAbcID_fk =3D abcID) WHERE etpAbcID_fk <> @ %def=20 --8<---------------cut here---------------end--------------->8--- The above file is made up of two defined blocks (`sql-init' and `sql-cond') plus some glue in between. The good thing is I can reuse the same blocks in other context, completely avoiding copy/paste of code: --8<---------------cut here---------------start------------->8--- <>=3D <> SELECT abcID, lesAlternNbrSem, lesNbrSem, CONVERT(varchar(10), lesDateDeb, @dateFmtStyleOut) AS lesDateDeb, CONVERT(varchar(10), lesDateFin, @dateFmtStyleOut) AS lesDateFin FROM lessons JOIN record ON (lesAbcID_fk =3D abcID) WHERE lesAbcID_fk <> @ %def=20 --8<---------------cut here---------------end--------------->8--- OK. So, my `org-lit-prog.nw' file is ready, and committed under Subversion (this is the only one I'm committing as it contains both the documentation = of the code, and the source code itself). Then, I just type (in a terminal): --8<---------------cut here---------------start------------->8--- noweb org-lit-prog.nw --8<---------------cut here---------------end--------------->8--- to extract both: o the LaTeX file [2] to be compiled into a PDF [3], o the different source code files (Enterprise.sql [4], Lessons.sql [5= ], [6] and [7]) Just that easy to keep code and doc in sync, and get a very nice-to-read documentation of the code. Sometimes, I play an extra trick is made in the noweb file: I put blocks of static code (for which I don't especially need any noweb feature) after the end of the LaTeX document. That way, it gets outputted by noweb as a source file during the Tangle process, and included in my LaTeX document via the listings package. Why that trick? I could directly put the code in the body of the document! Yes, but I want the code to be highlighted via listings. Otherwise, it's ju= st black and white display of the code... For easy access, I've put all the above files on a my Web space: [1] http://www.mygooglest.com/sva/org-lit-prog.nw [2] http://www.mygooglest.com/sva/org-lit-prog.tex [3] http://www.mygooglest.com/sva/org-lit-prog.pdf [4] http://www.mygooglest.com/sva/Enterprise.sql [5] http://www.mygooglest.com/sva/Lessons.sql [6] http://www.mygooglest.com/sva/Payment.sql [7] http://www.mygooglest.com/sva/prsNumNat.awk >From what I understand, what we both wanna reach is writing all of the `.nw' file as an Org file directly, and let Org-babel extracts the source code fi= les and the documentation out of it. What should be good in the future, when it will be ready for prime time, is that this becomes complete part of the export process: no tangle operation needed. Is the above description worth for you? Do you understand how I work when documenting code? Pay attention: I'm *the* expert in literate programming. Just an amateur being seduced by some of its features. Best regards, Seb --=20 S=C3=A9bastien=C2=A0Vauban _______________________________________________ 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