Integrating Programs and Documentation

Ralf Hartmut Güting

Praktische Informatik IV, FernUniversität Hagen, D-58084 Hagen, Germany

Abstract: A simple tool called PD system is described and offered for general use that allows one to integrate programs and their documentation in ASCII files. Such a program with documentation file (PD file) consists of alternating documentation and program sections. PD files can be compiled directly; for a compiler, documentation sections are just commentaries to be ignored. On the other hand, the PD system allows one to transform PD files into LaTeX source files and so to produce formatted documents. For the description of formatted material in the documentation sections, a simple markup language is offered. The main goal in the design of this language is readability of the source text. In other words, formatting specifications are kept as ``implicit'' and ``invisible'' as possible and much of the ``formatting noise'' occurring in LaTeX and other markup languages can be hidden. PD files should be readable for anyone without prior learning of the markup language.

Independent from the problem of documenting programs, PD files may be convenient for describing text documents in ASCII files (rather than using LaTeX directly). The PD System was written in C using the lex and yacc tools. It is free software available from the author and includes its own documentation as a PD file.

Published: FernUniversität Hagen, Informatik-Report 182, May 1995.