code reading dds

The Making of

The text was written using the elvis, vim, and nvi editors on several computers: a Mitac 6020 running Microsoft Windows 98 and RedHat Linux 6.1; a Toshiba Satellite 35 running Microsoft Windows 2000 and RedHat Linux 7.1; an IBM PC-340 running FreeBSD 4.1-RELEASE and later 4.6 and 4.8; and a Digital DNARD (Shark) running NetBSD 1.5-ALPHA. My impression is that the final production typesetting was performed in a Mac.

Text was processed using LaTeX (MiKTeX 1.11 and 2.1) and converted into Postscript using dvips 5.86. Bibliographic references were integrated with the text by MiKTeX-BibTeX 1.7 (BibTeX 0.99c). Diagrams were specified in a declarative, textual form (using a custom Perl script for annotated code diagrams, and in some cases using the UMLGraph tool I developed during the process) and converted into encapsulated Postscript by the GraphViz system dot program, version 1.8.6 (see http://www.graphviz.org). Screen dumps were converted into encapsulated Postscript using programs from the outwit and netpbm systems. I also used GNU make to coordinate the build process, and RCS to manage file revisions (544 revisions on last count):

$ for i in RCS/* ; do ; rlog $i ; done | grep '^revision' | wc -l

I wrote a number of Perl scripts to automate parts of the production process. Most were processed by Perl 5.6.1. All the annotated code examples were specified textually with commented code delimited by special character sequences. A Perl script converted the annotated code into encapsulated Postscript. As an example, the code

                                 $.
$(main(argc, argv)$)|Simple annotation|
$([...]$)|Omitted code|
{
	$(if (argc > 1)
		for(;;)
			(void)puts(argv[1]);
	else for (;;)
		(void)puts("y");$)|{l:egano:txt}Annotation referenced from#the text|
}

Similarly, the code reading maxims, the book's index, and the source code list were generated by LaTeX macro output post-processed by Perl scripts. Another script converted the manuscript's initial British spelling into American spelling through OLE calls to the Microsoft Word spell checker. I also wrote a Perl script (now part of the GraphViz distribution) to visualize a directory's structure as a dot diagram. Its output was hand-tuned to create figures such as the ones comparing the NetBSD vs the Linux kernel source tree. Writing a book can be a lot more enjoyable if it involves some coding.

The Typesetting Process

Figure 1: The manuscript production process

The process for typesetting the manuscript into Postscript from the sources is outlined in Figure 1. Some elements of the process were also described as rules in a Makefile, but they were mainly there as a mnemonic aid; the Makefile never expressed all dependencies. Although the process appears complex, textual modifications (as opposed to changes in the diagrams, the maxims, the index, and the annotated code) simply required re-running LaTeX on the main file.

Commenting (or not) three lines at the top of main file allowed me to create single or double-spaced output, omit the revision identifier marks at the start of each chapter, and process only a single chapter (specified later in the same file).

The four main categories of input were:

Text files

(ch*.tex) containing the text for each chapter in LaTeX markup, and a separate file defs.tex containing about 50 macro definitions specific to this book. These were processed by LaTeX to generate device independent output and then by dvips to generate Postscript.

Annotated code

(*.c, *.java, *.any, *.sh, *.out ...) These files contained source code with embedded annotations. The annotations were bracketed in $( and $) pairs. These were processed by the ano.pl Perl script to generate encapsulated Postscript.

Dot diagrams

(*.dot) containing the descriptions for all diagrams. These were processed by the AT&T GraphViz dot program to generate Postscript.

Postscript diagrams

(*.ps) various figures such as screen dumps provided in encapsulated Postscript.

maxim.out

A list of all maxims embedded in the chapters. This was postprocessed by the Perl script mkmaxim.pl to generate the maxim.tex file.

coderead.aux, ch*.aux

These contained the page number of all labeled items and bibliography references, and was used for updating page references and the various tables. In addition, the BibTeX program read the aux files and the database of bibliography files I maintained (*.bib), to generate the coderead.bbl bibliography that appears at the end of the book. The author index was generated using the LaTeX authorindex package.

coderead.toc,lot,lof

Table of contents, and list of tables and figures.

coderead.idx

Index elements. These, together with the list of hand-created list of "see", and "see also" entries in addindex was processed by the Perl script mkindex.pl to generate the index index.tex.

lst*.aux

The names of these files, generated by the code annotation script ano.pl, were merged by the Perl script mklstaux.pl into a single file lstaux.tex that was read by LaTeX to obtain information on all labels used on the annotated code files.

Indexing

• Ada keyword
• C library
• keyword
• operator
• directory name
• editor command
• file name
• file extension
• file name
• identifier name
• Hungarian prefix
• Java class
• javadoc tag
• Java method
• Java package
• Java keyword
• Java interface
• Java operator
• Modula keyword
• pseudo-target
• Perl keyword
• C++ library
• Perl module
• Perl identifier
• regular expression
• revision-id tag
• troff command
• Texinfo command
• Unix-specific function
• Unix-specific identifier
• Win32 SDK
• X-Windows library

The End Result

Book homepage | Author homepage

(C) Copyright 2000-2003 D. Spinellis. May be freely uploaded by WWW viewers and similar programs. All other rights reserved. Last modified: 2003.10.24