sed & awk, 2nd Edition

readsource—Format Program Source Files for troff

Contributed by Martin Weitzel

I am often preparing technical documents, especially for courses and training. In these documents, I often need to print source files of different kinds (C programs, awk programs, shell scripts, makefiles). The problem is that the sources often change with time and I want the most recent version when I print. I also want to avoid typos in print.

As I’m using troff for text processing, it should be easy to include the original sources into the text. But there are some characters (especially “” and “.” and “,” at the beginning of a line) that I must escape to prevent interpretation by troff.

I often want excerpts from sources rather than a complete file. I also need a mechanism for setting page breaks. Well, perhaps I’m being a perfectionist, but I don’t want to see a C function printed nearly complete on one page, but only the two last lines appear on the next. As I frequently change the documents, I cannot hunt for “nice” page breaks—this must be done automatically.

To solve these set of problems, I wrote a filter that preprocesses any source for inclusion as text in troff. This is the awk program I send with this letter. [He didn’t offer a name for it so it is here named readsource.]

The whole process can be further automated through makefiles. I include a preprocessed version of the sources into my troff documents, and I make the formatting dependent on these preprocessed files. These files again are dependent ...