[Aldor-l] Literate programming

[pip88nl at gmail.com]

Hi,

I am getting increasingly interested in literate programming. There are a
few questionmarks I am turning at the idea of turning the aldor compiler
sources into literate programs.

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. I have a noweb highlighting definition, but
it's suboptimal as it depends on the code chunks being marked as being C
or C++ or whatever by using the extension, as in:
<<foo.c>>
c code
@
and that's not really common in literate programming.

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 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:

/*
=item stoAlloc (unsigned code, ULong size)

Allocates maximally aligned dynamic storage.

=cut
*/
MostAlignedType *
stoAlloc (unsigned code, ULong size)
{
/*
=pod

Something interesting about this function.

=cut
/*
  actual (code);
  // etc..

Another problem are the newlines that blow up the code, so it is really
not an option to me.

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.

I would really like to compile the documentation obtained from the source
into a PDF using LaTeX. That is where noweb comes in. The problem I have
with it as I described above could be made into my friend. If noweb could
be used as a sort of advanced preprocessor, that could prove useful, as
there is some code duplication in aldor and extensive use of macros (some
are really required to be macros, others will be turned into functions as
I come along). 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.

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

/**
 * \function{stoAlloc}{unsigned int code, ULong size}
 * \begin{param}[code]
 *    The type code used as identifier for this storage. It can be used
 *    to optimise the garbage collector when using one that supports
 *    gaps.
 * \end{param}
 * \begin{param}[size]
 *    Size of the storage. Note that the actual memory allocated may be
 *    more than requested due to alignment.
 * \end{param}
 *
 * This function returns maximally aligned..etc just like above.
 */
MostAlignedType *
stoAlloc (unsigned code, ULong size)
{
  /**
   * Also have some documentation \emph{inside} functions.
   */
  // etc..

I don't know of any tool that currently supports this, but it should be
trivial to implement. It could even be made to detect the function's
prototype if such a thing occurs below the comment. In that case, the
first \function command could be omitted. Does anyone know of a tool that
supports things like what I just described?

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.

Pippijn
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: Digital signature
Url : http://aldor.org/pipermail/aldor-l_aldor.org/attachments/20080819/dab3acb5/attachment.bin