



4. _In an emergency,_ when something in the code does confuse colordoc, you can manually set \BraceLevel to a number, and restore order. Just like that: \BraceLevel1 (or even \BraceLevel=1).
5. _The main text may appear colored_ sometimes. This is due, who knows how, to the several-pass cross-reference mechanisms. One more run will usually make it good.
6. _I wish the color of the backslash could be easily controlled._ But the backslash is typeset by doc before \macro@name starts assembling the letters of the command. \macro@name is what I lacked, and what was easiest and best to hack, but then I had no control over the backslash.
7. _Does the program know when a macro is being defined?_ While working on the package I realized that by coloring any macro that is being defined, I didn't need to religiously append \begin{macro} to generate the marginpars. With the coloring of new commands, the visual reference was there already. At a wild point I thought that maybe the package would add the \begin{macro}'s automatically! Of course this is actually impossible, and in any case the user would have no control over when and where to put it. But it is true that the need for the marginpars with macro names is eased. This dtx doesn't have many (none in the code) and thus I'm using a little less paper.
8. _METAFONT support._ I thought it would be simply changing \ for (. This much is easy, but apart from that catching if-endif is impossible for a language with no "escape character" that would allow doc scan for a macro name. The solution is to create a wholly new package adapting doc to METAFONT.

## 3 The package

### Introduction

This program modifies Frank Mittelbach's doc package to use colors in the code listing of a program. With a natural emphasis on TEX, color is used mainly to highlight matching curly braces ('C' and 'J', henceforth simply 'braces'), \if...-\fri constructions, and other TEX programming stuff.

Originally I imagined coloring pairs of matching braces with the same color (different for each level of nesting). In 2002-3 I prepared the 'interactive version' in the cd accompanying my uncle's book _El Universo ETEX_[1], and developed some macros to color matching braces in the examples. That pdf was prepared in a larger font, suitable for on-screen reading, and this made the colored braces very easy to spot. It was fun work, but not vary robust (it was intended for my own use), and it certainly required some retouching of the code that was being listed--in part, because other stuff was being done to it, like highlighting the particular commands that each example illustrated, and making them links to their description in the text. So it wasn't really a literate programming tool (where the point is to use _the same_ source as both the working program and its typeset-able listing). But that was where I saw that coloring the code makes a difference in code readability.

So when I did the first tries for the present package I started by coloring the braces. But such small characters (made even \small'er by macrocode) did not really stand out, and the colored brace matching was nice, but less than obvious to the eye. Then I think my wife Jen proposed coloring not the braces but the stuff inside them! I initially liked this a lot. (An architect and graphic designer, Jen would eventually be in charge of defining the default color schemes of the package). The result was more what I had in mind: the matching is really obvious, and the colored code is not as obnoxious as I first feared.

However, that is true when we're only considering braces. After adding the rest of the features (\if's, highlighting of newly defined macros, etc.), it became clear that, sadly, there are really a lot of things colored all over the place. So I am back to the coloring of the braces, not the contents, as a default. Coloring the contents is offered as an option--another option was thought of anyway, for black-and-white needs (i.e., when printing): instead of colors we can give braces a numeric subscript.

Just to give it a chance, I am using the "contents" option in the code of the present package below.

### General strategy

We will have to hack the macrocode environment, where the code listing actually happens, and which is analogous to the usual verbatim, except that other things happen--addition of line numbers being the most obvious. { and } will have to be made active characters--not too much of a problem because they are innocuous in macrocode, not having to perform any special tasks.

Catching \if's, and analogously catching \def's, \def's, \newcommand's, etc. (since it would be nice to highlight the commands that are being defined), seems harder. It will mean making \ active, and making it read ahead for the name of the macro it introduces: take letter by letter, find the end of a command name (is it true, as intuitively felt, that we can simply look for a character with a category code other than 'letter'?), decide what to do with it, and hope that this doesn't break anything else, and that you can prove it.

Two good news: within macrocode (or verbatim), not much does much--all the special characters' special meanings are suppressed, so, after all, there isn't much that can be 'broken'. It actually turns out to be a pretty danger-free low-level hacking setting.

And the second good news: Frank Mittelbach, in doc itself, already did most of the job about finding a macro's name! This is because of his bold dream, and execution thereof, of making macrocode compile index entries from the macros used in the code. Since the doc package not only implements literate programming, but also illustrates it very well (the explanations1 are quite sufficient to understand a code that is itself very readable, and the functions are broken into logical sections), it is very easy to achieve the results of colordoc with only relatively small, targeted modifications.

Footnote 1: I mean the explanations on how the macros work and are implemented. The explanations to the user, on how to _use_ the macros, are paradoxically less friendly!

So let's start by setting up colordoc as a package, and then the main modification from doc:

```
7(>package)
8VeedsTeXFormat{LaTeXZe}[1995/12/01]
9VProvidesPackage{colordoc}[2010/04/18 Documentation in TeXnicolor (Federico Garcia)]
8%letdoc@macrocode\macro@code
```

The new meaning of macrocode depends on colordoc's options, and will be established there (section 3.4). It will always do what it does in doc (now \doc@macrocode) plus more stuff; among this additional stuff is the need to make the braces active, through \@makebracesactive:

```
81\def\@makebracesactive{\catcode'\{active\catcode'\}active}
```

### Highlighting of special commands

When doc finds a \ in the user's code, it starts gathering the command name that follows, in order to make an index entry (except when the command is in the \DoNotIndex list). We are going to hack two of the commands involved: \macro@name, that takes each letter and adds it to the name that is being collected--we need this to find partial command names like \if... or \new...--and \macro@finish, that operates on a completed macro name--which we will use to catch complete things like \fiv





### Auxiliary functions

For cycling through the color scheme we need a pair of arithmetic functions modulo \@colorlevels.

```
\def\@_modinc#1\@me
18\sfglobal\advance#1\@me
19\sfinfnum#1>\@colorlevels
20\sfglobal\#1\@me\fi\
21\sfdef\@_moddecr#1\%
22\sfglobal\advance#1\m@me
23\sfinfnum#1>\@\else
24\sfglobal\#1\@colorlevels\fi\
25\sfglobal\advance\#1\m@me
26\sfglobal\#1\@colorlevels\fi\
27\sfthe actual color changes are performed by \@bracecolor. This is a function of \@BraceLevel, through auxiliary commands \@color\(\{\)_BraceLevel\(\}\).
28\sfdef\@_bracecolor\{\)\(\sf\#nameuse@color\)\the\BraceLevel\}
```

The auxiliary commands have to be defined in advance. Their number depends on \@colorlevels, but since the user can change this at any point, the program needs to be ready to apply new definitions. So, the user will have \ColorLevels\(\_new number of colors_): this sets \@colorlevels, and calls the definition routine. (Apart from this, the user is responsible for defining any colors beyond the original 5.)

```
\def\ColorLevels#1\%
19\sf@colorlevels#1\
20\sf@tempcnta\@colorlevels
21\sfloop\sfinfnum\@tempcnta\%2\%
22\sfexpandafter\)\_edef\_csname@color\the\@tempcnta\endcsname\%
23\sfnoexpand\color\color\-\the\@tempcnta\}
24\sfadvance\@tempcnta\m@me
25\sfrepeat
26\sf\}
```

### Color schemes

The colors themselves are \definecolor'ed as color-1, color-2, etc., up to \@colorlevels. The two options that involve colors define the defaults, but the user can change them at any time.

The braces color scheme needs eye-catching colors, since a lot of the coloring happens on single characters. The outer level will be color 0, since in principle it should never happen. However, it can happen when for some reason the code confuses colordoc (for example, when the braces are used in some special way and are unbalanced in the code; see section 2 for other cases). The default scheme is blue-purple-green-yellow.

``` \newcount\@colorlevels
19\def\_braces@colorscheme{%
20\sfColorLevels4
21\sfBraceLevel\%0
22\sfdefinecolor\color-0\frgb\{0,0,0}
23\sfdefinecolor\color-1\{cmyk\}{1,.5,0,.3}
24\sfdefinecolor\color-2\{cmyk\}{0,1,0,.2}
25\sfdefinecolor\color-3\{rgb\}{0,.6,0}
26\sfdefinecolor\color-4\{cmyk\}{0,0,1,.6}
27\sfdef\{_termew##1\{\)\(\}\)\(\}\)\(\}\)\(\}\)\(}\)\(}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}\}\}\}\}\\}\}\\}\\\\\}

For the contents option, where whole chunks of code will be colored (instead of only braces and a few macros), we want milder colors. In fact, assuming that most of the code listing in a dtx actually happens at brace level 2 (since most of it is the contents of \def's, \newcommand's, etc.), we have set level 2 to black. The outer level is a darkish purple, and then comes a green, a brown, and a blue.

\def\_contents@colorscheme{%

\ColorLevels5

\BraceLevel\@me

\definecolor{color-0}{rgb}{0,0,0}

\defincorcolorcolor-1}{cmyk}{0,.5,0,0.6}

\defincorcolorcolor-2}{rgb}{0,0,0}

\defincorcolorcolorcolor-3}{rgb}{1.5,0.15,..75}

\defincorcolorcolor-4}{rgb}{0,.47,0}

\defincorcolorcolorcolor-5}{cmyk}{0,0.72,1,..4}

\defincorcolorcolorcolorcolor-6}{rgeb}{0.8,0,0}

\defincorcolorcolorcolorcolor-4}{rgb}{0,.47,0}

\defincorcolorcolorcolorcolor-5}{cmyk}{0,0.72,1,..4}

\defincor


