2 Overview of the ProgDoc system

With this historical background in mind, ProgDoc takes a completely different approach. It releases the ``one source'' policy, which was so crucial for all WEB systems, thus giving the programmer maximum freedom to arrange his source files in any desirable way. On the other hand, the consistency between source code and documentation is preserved by special handles, which are present in the source files as ordinary comments⁴ and which can be referenced in the documentation. pdweave, ProgDoc's weave utility incorporates the desired code parts into the documentation.

But let's first of all start with an example. Suppose we have a C++ header file called ClassDefs.h which contains some class declarations. Subsequent you can see a verbatim copy of the file :

class Example1 {
private :
  int x;
public :
  explicit Example1(int i) : x(i) {}
};

class Example2 {
private :
  double y;
public :
  explicit Example2(double d) : y(d) {}
  explicit Example2(int i) : y(i) {}
  explicit Example2(long i) : y(l) {}
  explicit Example2(char c) : y((unsigned int)c) {}
};

It is common practice until now, especially among programmers not familiar with any literate programming tools, that system documentations contain such verbatim parts of the source code they want to explain. The problem with this approach is the code duplication which results from copying the code from the source files and pasting it into the text processing system. From now on every change in the source files has to be repeated in the documentation. This is reasonable of course, but the practice tells us that the discipline among programmers to keep their documentation and their source code up to date is not very high.

At this point, the ProgDoc system enters the scene. It allows us to write ClassDefs.h as follows :

// BEGIN Example1
class Example1 {
private :
  int x;                             // Integer variable
public :
  explicit Example1(int i) : x(i) {} // The constructor
};
// END Example1

// BEGIN Example2
class Example2 {
// ...
private :
  double y;
// ...
public :
  explicit Example1(double d) : y(d) {}
  explicit Example2(int i) : y(i) {}
  explicit Example2(long i) : y(l) {}
  explicit Example2(char c) : y((unsigned int)c) {}
};
// END Example2

The only changes introduced so far are the comments at the beginning and at the end of each class declaration. These comments, which of course are non-effective for the source code, enable us to use the new \sourceinput[options]{ filename}{ tagname} command in the L^ATEX documentation. This will results in the inclusion and syntax highlighting of the source code lines which are enclosed by the ``// BEGIN tagname'' and ``// END tagname'' lines respectively. Consequently the following L^ATEX code:

``.. next we present the declaration of the class {\mytt Example1}:

\sourceinput[fontname=blg, fontsize=8, listing, linenr, label=Example1]{ ClassDefs.h}{ Example1}

as you can see, there is no magic at all using the {\mytt \symbol{92}sourceinput} command ..''

will result in the following output:

``.. next we present the declaration of the class Example1:

Listing 1: ClassDefs.h [Line 2 to 7]

class Example1 {
private :
  int x;                             // Integer variable
public : 
  explicit Example1(int i) : x(i) {} // The constructor
};

as you can see, there is no magic at all using the \sourceinput command ..''

First of all, we observe that the source code appears nicely highlighted, while its indentation is preserved. Second, the source code is preceded by a caption line similar to the one known from figures and tables. In addition to a running number, the caption also contains the file name and the line numbers of the included code. Furthermore this code sequence can be referenced everywhere in the text through a usual \ref command (like for example here: see Listing 1). Notice however that the boxes shown here are used for demonstrational purpose only and are not produced by the ProgDoc system.

After we got an impression of how ProgDoc's output looks like, it's time to explain the way how it is produced. First of all the style file 'progdoc.sty' has to be included into the latex source file. Among some definitions and default settings (see section 9) 'progdoc.sty' contains an empty definition of \sourceinput. If L^ATEX will process any file with this command, it will only print out the following warning:

WARNING !!! Run pdweave on this file before processing it with latex. Then you will see the source code example labeled Example1 from the file ClassDefs.h instead of this message.

There are two main reasons for this behavior. The first and main one is that I'm an awful L^ATEX ``speaker'' and thus unable to implement all this functionality in pure TEX/L^ATEX. The second reason is that there already are a lot of useful tools around there in the Web, so why not combine and use them as shown in Figure 1.

Figure: Overview of the ProgDoc system.

In fact the ProgDoc system consists of two parts: pdweave and pdhighlight where pdweave is an AWK script while pdhighlight is a heavily modified, extended and renamed version of Norbert Kiesel's c++2latex filter. The production of HTML is done by Nikos Drakos' and Ross Moore's latex2html [La2HT] utility.

The main idea behind ProgDoc is to write the documentation into so called '.pd' files which contain pure L^ATEX code and, as an extension to ordinary L^ATEX, some additional commands like the above mentioned \sourceinput. These '.pd' files are processed by pdweave which extracts the desired parts out of the source files, highlights them and finally merges them with the ordinary parts of the documentation. The file generated this way is an usual L^ATEX source file which in turn can be passed to the L^ATEX text processor.

Usually, all this steps are simplified by the use of a special Makefile which also keeps track of dependencies between source files and the documentation itself (see section 10 for an example).

In the next sections a brief description of the different commands available in '.pd' files will be given. The format of the handles required in the source files will be explained and finally an example Makefile which automates the generation of the program documentation will be presented.

Footnotes

... comments⁴

As far as I know, any computer language offers comments, so this seems to be no real limitation.