Dogwagger logo: a yin/yang symbol subtly modified with a dog head jutting from the dark region

Dogwagger

In a single line, you can change for the better how you document your computer code. Here's that line: 

% DogWagger version=`4.0.4' fileTarget=`MYFILE.pl'
Inserted at the start of a LaTeX file, this comment line allows you to combine your code and documentation without having to learn the use of new tools. This example generates Perl but, with a little help from Dogwagger, a single LaTeX file can spawn multiple different files in multiple languages — html, PHP, Javascript, C, C++, SQL, R, Erlang, and so forth.

For more details, read the manual (PDF, 320K). And yes, the manual was written in LaTeX, and contains the complete source code. (Regard it as proof of concept). Here's the manual as a .tex file (Dogwagger404.tex, 95K). You can turn it into a PDF using PDFLaTeX, or you can turn it into a Perl executable, using DogWagger!

Of course, (heh!) you need the Perl script for it to be able to make itself from Dogwagger404.tex, so we have a bit of a chicken-and-egg problem, unless you download the Perl script (about 29K). To prevent hassles with unhappy servers and so on, I've called it Dogwagger404.txt. On Linux/Unix/Mac systems, just run it from the command line. Try the help page first: 

perl Dogwagger404.txt --help
Under MS Windows, you might wish to rename the file to Dogwagger404.pl, and then run the script directly (If Perl is properly set up). Most Linux/Unix systems will have Perl built in, but Windows users may need to install Strawberry Perl or ActivePerl.

Why not noweb?

Noweb is a great tool, and has been around for years, but it has a couple of limitations (shared by many literate programming tools, and indeed documentation generators):

  1. Dependencies. With noweb you need scripts to make the documentation (noweave) and the code (notangle). With Dogwagger, you can generate documents directly from the LaTeX code as usual, and Dogwagger404.pl will extract multiple files of different types, automagically. (You can even include uuencoded binaries, if you wish).
  2. Exacting requirements. Although noweb is pretty simple, you do need to learn a new approach to writing documentation (not entirely a bad thing). You also need a slightly different approach to reading code — personally I find the noweb styling quite fragmented. With DogWagger, you're reading conventional code that is embedded within a LaTeX document, but you can (if you wish) move blocks around and so forth. The great thing about DogWagger is that you can break the code at any point, write comments, and insert headers. See how the clumsy source code becomes almost readable in Dogwagger404.pdf.

Does it work with LyX?

Yes. In fact, starting at version 4.0.1, Dogwagger was written in LyX. Here's the LyX source code: Dogwagger404.lyx (180K; you will also need the image Dogwagger.png which is at the head of this page, right click it to download it). See how you can simply embed your verbatim statements within Evil Red Text, and export the .lyx document as a .tex file (Pdflatex). You can then run Dogwagger on the .tex file. This is the origin of the Dogwagger404.tex file linked to above.

The one catch is that it's wise to put an extra comment line (% followed by a carriage return) above each "% Dogwagger" statement, as LyX sometimes reformats slightly according to its own rules. You can always still export to LaTeX.

Thanks

Thanks to Mark Ellison for amendments to version 4.0.4 that allow components of multiple files to be inserted "in any order".

Date of First Publication: 7/7/2005 Date of Last Update: 2012/05/16Web page author: Click here