[Aldor-l] Literate programming

[Thomas J. Moore]

Sorry for the long post from a lurker; I am somewhat of a literate
programming fan, so the subject caught my eye:

On 08/18/08 23:16, pip88nl at gmail.com wrote:
> First of all, who would be interested in having the aldor sources? I know
> from myself that I tend not to even look at literate programming sources,
> not even the tangled ones (as they contain no comments). The reason I
> don't like looking at them is that vim doesn't do syntax highlighting
> very well on noweb sources.

And neither does noweb-mode or mmm-mode on emacs.  I just use a
non-syntax-highlighting mode in my editor (not emacs or vi) for editing
noweb code; the only real features that editor provides are text
paragraph justification, indentation continuation, and macros.  For
reading the source, I have the PDF output in a separate window.  Sure, I
used to like/rely on syntax highlighting and autoindentation in my text
editor to help catch typos and brace mismatches, but I have (re)learned
to live without.

> The second issue or even problem I have with it (and that is what keeps
> me from looking at nw sources) is that it is possible to scatter the
> source over many places and let the tangler merge it later, as in:
> <<chunk1>>
> for (int i = 0; i < 100; i++)
>   {
>     <<Do something interesting here>>
>   }
> @
> This requires me to look for the string "Do something interesting here"
> in the nw document. That takes me time and I quickly get annoyed when
> things take time.

The noweb-mode on emacs does support a menu and side-tree and 
hypertext-like commands (I think), but here I use PDF as well.  If you 
use the hyperref package, you can just click on "Do something 
interesting here" (actually, the little number next to it), and if it's 
a split definition, there are arrows by the side to navigate.  The same 
is true of the HTML output, if you prefer.

I have invested a lot into making my noweb output work the way I like.
Part of that is making PDF and HTML output look good (at least for code
I produce - I am a programmer, not a mathematician, so I don't have a
lot of formulas to convert to HTML), which includes color syntax
highlighting even with multiple source languages.  The way I do this is
no better than naming chunks, though: I use \lstset{language=...}
directives to change the language for the following chunks, as used by
the listings package (and in fact one of my highlight modes uses
listings, but I tend not to use that mode any more).  My web server is
down at present (and has been down for more than a year, so don't expect
it up any time soon), but my current build system (revision 3, hot off
my latest project, and still not perfect; in fact it lost some features
from version 1) is at http://storage.iu.edu/qmgr/build.pdf (noweb source
is attached to PDF).  Use it/modify it if you like.  I'm aware of
allprose, but I have not done anything with it, mainly because I use C
and Ada for nearly all of my code right now.  I'm also aware that my
build system does not use autoconf, and has pathetic dependency logic,
but it works for me.

> The second option would be using POD instead. This is a format commonly
> used in Perl modules. Most of my website is written using POD (nobody
> uses html anymore nowadays). The problem with POD is mainly that it
> requires the text to be in the first line, so it would look like:

That and POD is not really literate programming.  It does fulfill a
different need, though: the need to document the API, and provide user
documentation.  I have yet to find the holy grail that allows me to
easily integrate source code documentation, API-level user
documentation, and end user documentation in a single document/source
file that also meets my need to have related things be as close to each
other as possible for maintenance and document flow.  For my Ada code, I
used a custom syntax highlighter for code chunks with integrated API
documentation, which I extracted and reinserted into the same document
as an appendix, but that was mostly library code so only API
documentation was necessary.

> The third option would be using doxygen. Doxygen can analyse C code and
> draw graphs on relationships. In my opinion, it shines at documenting the
> functions' signature. The rest is relatively uninteresting. There is a
> search function using php, but that's not really interesting to me.

Same comment as POD.

> To the noweb experts here: can <<chunk>>s be called as
> macros? Can they be parametrised? If that is the case, it would be an
> excellent alternative to the C preprocessor, because the latter kills any
> useful line information.

No, and that is something I consider a major deficiency in comparison to
(c)web.  Instead, I surround chunk refs with #define/#undef to supply
"parameters", which is definitely a horrible way of doing things.  Of
course you could always create a simple noweb "filter", similar to the
conditional code filter, that does parameter substitution, but I have
never felt enough of a need to actually do this.

> To conclude, here is what I would like to have: LaTeX comments inside C
> comments.

The first google/ctan hit for c2latex will give you something like this.
  I may have found others like it in my quest for literate programming
tools, but I tend to reject these for the same reasons I reject POD and
doxygen.

> What are your opinions on this? I think it is an important step in
> getting people look into the sources to have easily accessible
> documentation. Ralf talked about this at the workshop and in an earlier
> email to me. He is very right about the need for documentation but I am
> unsure about the actual tool used for this.

One of my wild dreams is to make an aldor-like compiler, written in
literate aldor (a change from my old dream, which was to the same in
Ada, but aldor does most of what I like about Ada, and is less wordy).
Missing bits are a nice formatter for aldor code I can incorporate into
my noweb build system, a more formal/complete language specification,
and copious amounts of free time.  I started the Ada version in '90, and
never finished, so don't expect anything in your lifetime unless I
retire.  I particularly don't want to look at aldor source, because I'd
rather implement from scratch (I'm masochistic that way, I guess).  One
of my other wild long-unimplemented dreams is a text editor that
actually supports literate programming properly.

   - Thomas J. Moore