[Gardeners] Literate Programming

[Stuart Sierra]

C Y <smustudent1 at yahoo.com> writes:
> --- Stuart Sierra <mail at stuartsierra.com> wrote:
>> 1. LaTeX does not have standard markup specific to
>> software documentation, such as examples or argument
>> lists.  I had to define new LaTeX commands to get what I
>> wanted.
>
> Hmm.  Would you be interesting in releasing the commands
> you created as a LaTeX package? [...]

They were quick & dirty hacks, not suitable for packaging.
A LaTeX package for documentation would be a good idea,
though.

>> 3. Noweb/LaTeX is sub-optimal for generating HTML, which
>> is the primary format in which I read documentation these
>> days.  Noweb's built-in l2h filter is limited, and
>> LaTeX2HTML is a disaster.
>
> I think there are one or two other LaTeX to html tools
> available, but I have little experience with them.  What
> were the problems you encountered with the current tools?

Well, Noweb's 'l2h' filter only understands a small subset
of LaTeX, so my new commands didn't work.  LaTeX2HTML can
parse most of LaTeX, but it doesn't understand Noweb markup.
You can see the problem.

Noweb's 'latex+html' filter was designed for use with
LaTeX2HTML, but having two different programs generating
HTML causes problems.  For example, if I tell LaTeX2HTML to
split my documentation into multiple HTML files, the links
between code chunks don't work.  I also had issues with
LaTeX2HTML incorrectly numbering sections.  All in all, it
was just messy.

>> 4. Building the code and documentation from the literate
>> source is a complicated, multi-step process.  My Makefile
>> is getting longer than the code itself.
>
> [...]  I agree it's a bit more complicated than just
> building code, but surely the first two steps can be done
> at the beginning with a few commands?

Yes.  My real problems started when I tried to package the
files for distribution.  I wanted 'make dist' to generate
the source files and all documentation.  I needed different
LaTeX sources (running 'noweave' with different options) for
PDF and HTML output.  Again, it got messy.

Three things would have made this process easier:

1. A LaTeX package for source code documentation

2. A Noweb style file for LaTeX2HTML

3. Example Makefiles for use with Noweb, similar to the many
   LaTeX Makefiles floating around on the web

If I decide to stick with Noweb/LaTeX, I might try to
implement some of those.

-Stuart