C Y <[EMAIL PROTECTED]> writes: > --- Stuart Sierra <[EMAIL PROTECTED]> 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 _______________________________________________ Gardeners mailing list [email protected] http://www.lispniks.com/mailman/listinfo/gardeners
