The compsci package

macros for writing about macros (Frankenstein’s conscience)

                 Matt Swift <swift@bu.edu>

Version: v0.92 (beta) Documentation revision: 1996/10/04

Abstract The compsci package provides L^{A}TEX macros for writing about L^{A}TEX macros. Most often this package will be used to supplement the ltxdoc class, but it can be used with other classes.

In this initial version, there are a few cosmetic bugs, some minor bugs, and some features break if you are not using the ltxdoc class.

Part I

Discussion

1 Textual elements

\word \word {⟨word⟩} is used to typeset a word referred to as a word. For example,

Elephant is such a silly word. \term \term{⟨technical term⟩} typesets the a techincal term in a different font. You

might want to use this where a techincal term is first used, or defined. For example, This sort of thing is called a blibnil.

\defn \defn {⟨definition⟩} typesets a definition, perhaps of a technical term. We

may describe a blibnil as a slibnil with three arms. \env \env {⟨environment name⟩} typesets the name of a L^{A}TEX environment. For

example, the enumerate environment. \bst \bst{⟨bibstyle name⟩} typesets the name of a BibTEX bibliography style. For

example, the achicago bibstyle.

\package \package {⟨package name⟩} typesets the name of a L^{A}TEX package. For ex-

ample, the compsci package. \class \class {⟨class name⟩} typesets the name of a L^{A}TEX class. For example, the

letter class. \file \file {⟨file name⟩} typesets the name of a disk file. For example, the file

Makefile.in.

\ext \ext {⟨extension⟩} typesets the name of a disk file extension. For example, the extension dvi. The argument should not include the dot that separates the root name from the extension. The dot can be inserted by the macro if you want it.

\caveat \caveat{⟨warning text⟩} typesets a warning paragraphs. You can also enclose warning the ⟨warning text⟩ in a warning environment. Using the warning environment is

necessary if the ⟨warning text⟩ is to include |...|s, a codeexample environment or other “verbatim” constructs.

Warning: This is an example \caveat or warning environment.

\todo The \todo {⟨text⟩} command and the todoenv environment are analogous to todoenv \caveat and warning, but they typeset paragraphs of a task “to do”.

To do: This is an example \todo or todoenv environment.

\code \code {⟨verbatim text⟩} and |⟨verbatim text⟩| typesets short pieces of code

\code*
|...|

verbatim. Instead of matching curly braces, any character may be used to contain the ⟨verbatim⟩ after the \code command. For example, |{{@#%$^\| looks like

 {{@#%$^\ .

To do: Implement \code*. Like \verb*, \code* marks spaces explicitly.

\typeset \typeset {⟨text⟩} typesets ⟨text⟩ in a normal way, but indicates by boxing that the contents are an example of how some piece of code actually appears. For example, this looks like this when typeset.

typesetexample These example environments may be used to present a piece of source code and what it looks like when typeset. The typesetexample environment typesets its contents like \typeset except they are set off in their own indented block element instead of being boxed.

Example of typesetexample environment.

codeexample The codeexample and codeexample* environments are similar analogs of

codeexample*
codeexamplex
codeexamplex*

\code and \code*. The codeexamplex environment is like the codeexample en-

vironment except that \, {, } have their usual meanings. Inside the argument, \\ produces a typeset backslash.

   This is a \env{codeexample} environment: \(\int e^x\,dx\)  {}{{{!#@$%^&\^^A for emacs $
   There is a percent sign in the source after the $.^^A for emacs $

␣␣␣This␣is␣a␣\env{codexample*}␣environment:␣\(\int␣e^x\,dx\)␣␣{}{{{!#@$%^&\^^A␣for␣emacs␣$
␣␣␣Someday␣I␣would␣like␣to␣get␣rid␣of␣the␣the␣leading␣spaces␣in␣a␣line.
␣␣␣
   This is a codeexamplex environment: ∫ eˆ x dx !#@$^&\^^A for emacs $
   The earlier examples had three unmatched open-braces which had to be
   closed in this environment.  Also the backslash had to be doubled.
   Percent signs get ignored -- a bug.

Warning: The codeexamplex environment ideally should ignore %s in the first column and print all others. The best I can do for the moment is to ignore %s.

bothexample The bothexample and bothexample* environments typeset their contents two bothexample* times, side by side. The left side is set like either a codeexample or codeexample*

environment, and the right side is set like a typesetexample environment.

%␣␣␣     This is one part of a \env{bothexample} environment:
     \(\int e^x\,dx\)  \fbox{jub-jub} \par

     The contents must not contain any \LaTeX{} errors.
     There is an annoying \ plus three explicit spaces at the beginning of
     the first part.  They are a bug!  Also notice also the missing percent
     sign after the backslash after ``annoying'' -- another bug that affects
     the verbatim part only.

LOOKS LIKE:

This is one part of a bothexample environment: ∫ e^{x} dx jub-jub The contents must not contain any L^{A}TEX errors. There is an annoying % plus three explicit spaces at the beginning of the first part. They are a bug! Also notice also the missing percent sign after the backslash after “annoying” – another bug that affects the verbatim part only.

splitexample The splitexample environment takes an argument which is used on the right splitexample* side (the typeset side) of an element that looks like bothexample. The contents

of the environment are set on the left side. This is a way to cheat, making the right side something other than the strict tyepsetting of what’s on the left.

Warning: The splitexample and bothexample environments execute example code. The example code is executed in a group, but be careful with global assignments, and with assignments that might screw up the example environment itself before the group ends. Notice that \setcounter is global.

Warning: The % character is entirely ignored inside bothexample environments. Don’t count on them. This is a bug.

The bothexample and splitexample environments use an auxiliary file with extension vrb, but a second pass with L^{A}TEX is not necessary.

To do: Get the annoying initial %␣␣␣ out of the beginning of bothexample.

   To do: Implement splitexample and splitexample*.

To do: Get the bothexample sub-environments side by side! Right now they are sequential. I recommend keeping line length inside this environment less than 40, however, in case the side-by-side presentation is ever possible. I have not followed this advice myself.

To do: Get these environments to ignore leading spaces on a line, and handle all percent signs properly.

To do: Implement codeexamplex*.

\url The compsci package uses the url package by Donald Arseneau to handle the

\email
\path

typesetting of URLs, email addresses, and filesystem paths. See that package for details of how line breaks are handled within these elements.

To do: Surround an email with < and >.

\option \option {⟨option name⟩} typesets the name of a package or class option. For

example, the landscape option.

\program \program {⟨program name⟩} typesets the name of a computer program. For

example the xdvi program. See also \newprogram below. \lips The compsci package uses the lips package, so you can use the \lips command

for text ellipses. My love is like a red red rose. …

\booktitle The compsci package uses the titles package, so several commands like \booktitle are available.

2 Referring to commands

\cs \cs {⟨command sequence⟩} typesets a command sequence, such as the one that \cmd starts this sentence. \cmd does the same thing. For example, \cs\foo looks

like \foo . When writing, e.g., \cs\foo the following spacing is automatically handled. The result doesn’t look different from using the |...| or \code syntax, but the markup allows the parsing of the macro name itself for some future purpose such as for indexing.

Warning: You cannot say \cs\foo@bar when @ is not a letter (category

code 11), you must say \cs{\foo@bar} or \cname{foo@bar} instead.

Nor can you say \cs\par. It trips on \text@command.

Nor can you say \cs\iffoo. Use \cname{iffoo} instead.

\cname \cname {⟨command name⟩} is like \cs but its argument is evaluated and prefixed with a backslash character. For example, writing \cname{@tfor} gives you

 \@tfor .

\marg \marg {⟨mandatory argument⟩} typesets a mandatory argument, and \oarg \oarg {⟨optional argument⟩} typesets an optional argument. For example,

%␣␣␣     \cs\GobbleMOM\marg{first arg}\oarg{optional second arg}\marg{third arg}

LOOKS LIKE:

\GobbleMOM {⟨first arg⟩}[⟨optional second arg⟩]{⟨third arg⟩}

\meta \meta{⟨text⟩} refers to a syntactic placeholder. You would use this for example to talk about one of the arguments of a command you’ve introduced, like ⟨text⟩ above, which can contain normal text but is broken across lines only at spaces.

3 Miscellaneous

\newprogram The compsci package uses the abbrevs package to define the Program category of abbreviation. Use \newprogram{⟨“csname⟩}{⟨initial expansion⟩}[⟨subsequent expansion⟩] to define a new abbreviation {⟨“csname⟩} for a program.

\ProcessDTXFile \ProcessDTXFile can be used by a documentation driver file of the kind you might be inclined to make using the doc package. Its purpose is to be able to load a package up to a certain point so that just descriptive information can be read without reading in the whole file. \ProcessDTXFile{⟨filename⟩} defines the variable \JuStLoAdInFoRmAtIoN and inputs the file ⟨filename⟩. To be useful, the file must have a statement that branches on whether \JuStLoAdInFoRmAtIoN is defined. For an example of its use, see the present package.

\AddToCheckSum \AddToCheckSum {⟨number⟩} simply adds ⟨number⟩ globally to the checksum counter implemented in the doc package. This macro finds applications when the sources of a package are spread over one or more files such as configuration files or files concatenated by a Make process. For an example of its use, see the present package.

\BibTeX The BibTEX logo is provided if it isn’t already defined.

Part II

Implementation

4 Version control

\fileinfo \fileversion \filedate \docdate \PPOptArg These definitions must be the first ones in the file.
 1 \def\fileinfo{macros for writing about macros (Frankenstein's conscience)}
 2 \def\DoXNeeDME{}
 3 \def\fileversion{v0.92 (beta)}
 4 \def\filedate{1996/10/04}
 5 \def\docdate{1996/10/04}
 6 \edef\PPOptArg {%
 7 \filedate\space \fileversion\space \fileinfo
 8 }

Stop right here if we’re just loading the file’s information, and don’t want to load this code for typesetting its documentation (only makes sense for certain packages). The JuStLaAdInFoRmAtIoN flag will be set by the documentation driver; the DoXNeeDME flag will be set in the dtx file, and will appear above if it’s set.

 9 \makeatletter
10 \@ifundefined{JuStLoAdInFoRmAtIoN} {%
11 }{% ELSE
12 \@ifundefined{DoXNeeDME} {%
13  }{% ELSE
14  \UndefineCS\JuStLoAdInFoRmAtIoN
15  \usepackage{compsci}%

16 }

17 \makeatother
18 \endinput

19 }

Now we check for L^{A}TEX2e and declare the package.

20 \NeedsTeXFormat{LaTeX2e}
21 \ProvidesPackage{compsci}[\PPOptArg]

5 Requirements and context

22 \RequirePackage{abbrevs,alltt,lips,moredefs,moreverb,relsize,shortvrb,%
23  slemph,titles,url,verbatim}
24 \@ifclassloaded{ltxdoc}{%
25 }{% ELSE
26 \MonsterWarning{compsci}
27 {You may encounter errors with this version of the compsci package \MessageBreak
28 since you are not using the ltxdoc class. \MessageBreak
29 This will be fixed in a future version.}%

30 }

6 Textual elements

\code |...| \url@ttnobreakstyle We use the url package to implement \code and the shortvrb package to implement |...|. There are no linebreaks in either. See the respective packages for considerations of robustness.

To do: summarize robustness considerations here.

31 \MakeShortVerb{\|}
32 \newcommand\code {%
33 \begingroup
34 \urlstyle{ttnobreak}%
35 \Url

36 }

37 \newcommand\url@ttnobreakstyle {%
38 \def\UrlFont     {\ttfamily}%
39 \def\UrlSpecials {\do\ {\ }}%
40 \def\UrlOrds     {\do\*\do\-}%

41 }

Warning: All the verbatim-like environments below are hacked and queer. I have been meaning to become a verbatim expert for a long time, but I am not even close yet.

What needs to be done is to create the equivalent of \@docverbatim above but using the new verbatim package. Then both the codeexamplex environment and the bothexample environments could use this when writing out the vrb file of their contents. Then we can treat all the %s in the vrb file the same, that is either print or obey them.

codeexample codeexample* What I’m doing here is defining codeexample and codeexample* to be just like

the doc package’s verbatim and verbatim*. That is, they ignore % characters at the beginning of lines.

42 \begingroup
43 \catcode `|=0
44 \catcode `[=1
45 \catcode `]=2
46 \catcode`\{=12
47 \catcode`\}=12
48 \catcode`\\=12
49 |gdef|@xverbatim#1\end{codeexample}[#1|end[codeexample]]
50 |gdef|@sxverbatim#1\end{codeexample*}[#1|end[codeexample*]]
51 |endgroup
52 \newcommand\codeexample {%
53 \@beginparpenalty
54 \predisplaypenalty
55 \@docverbatim
56 \MacroFont
57 \frenchspacing
58 \@vobeyspaces
59 \@xverbatim

60 }

61 \NewName{codeexample*} {} {%
62 \@beginparpenalty
63 \predisplaypenalty
64 \@docverbatim
65 \MacroFont
66 \@sxverbatim

67 }

68 \newcommand\@docverbatim {%

69 \trivlist
70 \item[]%
71 \if@minipage\else
72  \vskip\parskip
73 \fi
74 \leftskip\@totalleftmargin
75 \rightskip\z@
76 \parindent\z@
77 \parfillskip\@flushglue
78 \parskip\z@
79 \@@par
80 \@tempswafalse
81 \def\par {%
82  \if@tempswa
83  \hbox{}%
84  \fi
85  \@tempswatrue
86  \@@par
87  \penalty\interlinepenalty
88  \check@percent
89 }%
90 \obeylines
91 \let\do\do@noligs
92 \verbatim@nolig@list
93 \let\do\@makeother
94 \dospecials

95 }

codeexamplex The codeexamplex environment ideally should ignore %s in the first column and print all others. The best I can do for the moment is to ignore %s.

96 \newenvironment{codeexamplex} {%
97  \alltt
98  \def\\{\char`\\}\catcode`\%=9\relax}{%
99 \endalltt

100 }

typesetexample The typesetexample environment is simple, it’s just the quote environment.

101 \newenvironment{typesetexample} {%
102  \quote
103 }{%
104 \endquote

105 }

To implement the bothexample environments we write out the contents of the environment and read them in twice, typesetting them differently each time. The verbatimwrite environment comes from the moreverb package. Reading the text twice seems unavoidable because we want to read them with different catcodes each time.

To do: Figure whether the tab stuff here is going is a help or a hindrance.

\@verbatimtabinput First we want to redefine \@verbatimtabinput so that it ignores %s. Once again, we should like to print %s that are not in the first column, but this implementation ignores them all.

106 {\catcode`\~=\active \lccode`\~=`\^^M \lccode`\N=`\N
107 \lowercase{%
108 \gdef\@verbatimtabinput[#1]#2{\begingroup
109  \do@verbatimtab{#1}{%
110  \@verbatim\frenchspacing\@vobeyspaces\@vobeytabs}%
111  \def\verbatim@addtoline##1~{%
112  \verbatim@line\expandafter{\the\verbatim@line##1}}%
113  \openin\verbatim@in@stream=#2
114  \ifeof\verbatim@in@stream\typeout{No file #2.}\else
115  \verbtab@oktrue
116  \catcode`\%=9
117  \loop
118  \read\verbatim@in@stream to \verbtab@line
119  \ifeof\verbatim@in@stream\verbtab@okfalse\else
120  \expandafter\verbatim@addtoline\verbtab@line
121  \verbatim@processline
122  \verbatim@startline
123  \fi
124  \ifverbtab@ok\repeat
125  \closein\verbatim@in@stream\fi
126  \endtrivlist\endgroup\@doendpe}}}

bothexample bothexample* The first \begingroup … \endgroup I think is necessary to contain the verbatim activity. The second is necessary so that activity in the example environment does not effect anything outside it. Of course global activity will, so be careful! The \minipage effects the second group.

127 \newenvironment{bothexample} {%
128  \par
129  \begingroup
130  \verbatimwrite{\jobname.vrb}%
131 }{%
132 \endverbatimwrite
133 \verbatimtabinput{\jobname.vrb}%
134 \endgroup
135 \par

We compensate here for the extra line caused by the final newline above.

136 \addvspace{-\baselineskip}%
137 \noindent{\sffamily\large LOOKS LIKE:}%
138 \par\smallskip
139 \noindent\fbox{%
140  \minipage{\textwidth}
141  \DocInput{\jobname.vrb}%  ^^A FIX DocInput not defined
142  \endminipage

143 }%

144 \par\medskip

145 }

splitexample splitexample* We can’t use #1 in the end-environment part, so we write it out. Again we have

the problem of %s.

Warning: This is broken!

146 \newenvironment{gogog}[1]
147 {\verbatimwrite{\jobname.vrb}#1}
148 {\endverbatimwrite}

149 \newenvironment{splitexample} [1] {%
150 \gogog{#1}\endgogog
151 \codeexample
152 }{%
153 \endcodeexample
154 \par\smallskip
155 \noindent\fbox{%
156  \minipage{\textwidth}
157  \catcode`\%=9
158  \input{\jobname.vrb}%
159  \endminipage

160 }%

161 \par\medskip

162 }

\caveat
warning
\cs@caveat
\todo
todoenv
\cs@todo

163 \newcommand\caveat [1] {%
164 \cs@caveat
165 #1%
166 \endgroup
167 \par

168 }

169 \newenvironment{warning} {%
170  \cs@caveat
171 }{%
172 \endgroup
173 \par

174 }

175 \newcommand\cs@caveat {%
176 \par
177 \begingroup
178  \em {\bfseries Warning:}\space

179 }

180 \newcommand\todo [1] {%
181 \cs@todo
182  #1%
183 \endgroup
184 \par

185 }

186 \newenvironment{todoenv} {%
187  \cs@todo
188 }{%
189 \endgroup
190 \par

191 }

192 \newcommand\cs@todo {%
193 \par
194 \begingroup
195  \em {\bfseries To do:}\space

196 }

\word \term \defn \env \option \package \program \class \file \bst \ext \email \typeset Abstract markup of terms and objects.
197 \NewTextFontCommand \program \TMFontProgram % generic name of computer program
198 \NewTextFontCommand \bst     \ttfamily      % name of BibTeX bibliography style

199 \NewTextFontCommand \cat     \sffamily      % name of a category
200 \NewTextFontCommand \class   \slshape       % name of LaTeX class
201 \newlet             \defn    \textslswitch  % definition
202 \requirecommand     \email   {\url}         % email address
203 \NewTextFontCommand \env     \ttfamily      % name of environment
204 \NewTextFontCommand \ext     \ttfamily      % name of file extension
205 \requirecommand     \file    {\url}         % name of disk file
206 \NewTextFontCommand \option  \ttfamily      % name of package or class option
207 \NewTextFontCommand \package \slshape       % name of LaTeX package
208 \newlet             \term    \textslswitch  % technical term
209 \newlet             \typeset \fbox          % text as it appears when typeset
210 \newlet             \word    \textitswitch  % refer to a word as a word

7 Referring to commands

\meta \m@ta \do@space \sp@ce \sp@@ce Here I redefine \meta to include a \normalfont right at the beginning inside a

group, since the command was working strangely when \ttfamily was in effect. Also, I redefine \\ to be a typeset backslash.

211 \begingroup
212 \obeyspaces%
213 \catcode`\^^M\active%
214 \gdef\meta{\begingroup\def\\{\char`\\}\normalfont\obeyspaces\catcode`\^^M\active%
215 \let^^M\do@space\let \do@space%
216 \def\-{\egroup\discretionary{-}{}{}\hbox\bgroup\itshape}%
217 \m@ta}%
218 \endgroup

These are simply from the doc package.

219 \defcommand\m@ta [1] {%
220 \leavevmode
221 \hbox\bgroup$\langle$\itshape#1\/$\rangle$\egroup
222 \endgroup

223 }

224 \def\do@space {%
225 \egroup
226 \space
227 \hbox\bgroup\itshape\futurelet\next\sp@ce

228 }

229 \def\sp@ce {%
230 \ifx\next\do@space
231  \expandafter\sp@@ce
232 \fi

233 }

234 \defcommand\sp@@ce [1] {%
235 \futurelet\next\sp@ce

236 }

\marg \oarg These use \meta and are therefore slightly different than their counterparts in ltxdoc. A tiny bit of breakability is added at the beginning.

237 \defcommand*\marg [1] {%
238 \penalty 9999%
239 {\ttfamily\char`\{\meta{#1}\char`\}}%

240 }

241 \defcommand*\oarg [1] {%
242 \penalty 9999%
243 {\ttfamily[\meta{#1}]}%

244 }

\cname \cmd \cs For referring to a L^{A}TEX macro. The code is a mix from the ltxdoc class and the abbrevs package. There is no need to check for \nocorr commands inside the argument so we skip \text@command. We might conceivably be in a typewriter slanted, so we do check for italic corrections. We don’t handle the case of calling this in math mode (see the definition of \DeclareTextFontCommand in the kernel).

We handle the cases of \cmd{\foo} and \foo differently. The latter needs logic to determine the following space, whereas the former does not. They both need italic corrections.

245 \DeclareRobustCommand*\cname [1] {%
246 \expandafter\code\expandafter{\bslash#1}%

247 }

248 \DeclareRobustCommand*\cmd {%
249 \leavevmode
250 \@ifnextchar \bgroup
251  \cs@cmd@grouped
252  \cs@cmd@ungrouped

253 }

254 \newcommand\cs@cmd@grouped [1] {%
255 \begingroup
256  \maybe@ic
257  \code{#1}%
258  \aftergroup\maybe@ic
259 \endgroup

260 }

261 \newcommand\cs@cmd@ungrouped [1] {%
262 \begingroup
263  \maybe@ic
264  \code{#1}%
265  \aftergroup\maybe@ic@space
266 \endgroup

267 }

268 \let\cs\cmd

8 Miscellaneous

\partname \ProcessDTXFile \AddToCheckSum See the version control section above for an example of when you might want to use these commands.

269 \def\partname {%
270 Part%

271 }

272 \newcommand*\ProcessDTXFile [1] {%
273 \InitCS\JuStLoAdInFoRmAtIoN
274 \def\filename {#1}%
275 \UndefineCS\DoXNeeDME
276 \input{#1}%
277 \UndefineCS\JuStLoAdInFoRmAtIoN

278 }

279 \newcommand*\AddToCheckSum [1] {%
280 \global\advance\check@sum #1%

281 }

\newprogram \TMFontProgram \TMHookProgram \TMResetProgram Provide for program abbreviations.
282 \TMNewCategory{Program}
283 \NewUserAbbrevDefiner\newprogram{Program}
284 \def\TMFontProgram {%
285 \relsize{-1}\ttfamily

286 }

\BibTeX The BibTEX logo.

287 \providecommand\BibTeX {%
288 {\rmfamily B\kern-.05em{\scshape i\kern-.025em b}\kern-.08em
289  T\kern-.1667em\raisebox{-.7ex}{E}\kern-.125emX}%

290 }

9 Configuration

Other things are deferred to a configuration file.

291 \InputIfFileExists{compsci.cfg}{}{}

The contents of the distributed configuration file are below.

292 \def\fileinfo{Compsci package configuration}
293 \def\fileversion{v1.0}
294 \def\filedate{1996/03/23}
295 \def\docdate{1996/03/23}
296 \ProvidesFile{compsci.cfg}
\ALaTeX \Frankenstein \monster \CTAN \kpse \gemacs \auctex \nts \MakeIndex \etex \LaTeXiii Various program names.
297 \newprogram\Frankenstein{Frankenstein}
298 \newlet\monster\Frankenstein
299 \requirecommand\ALaTeX {%
300 A\LaTeX%

301 }

302 \newtextmacro\ctan{CTAN}
303 \newprogram\kpse{kpathsea}
304 \newprogram\gemacs{\textrm{GNU} Emacs}
305 \newprogram\auctex{AUC-\TeX}
306 \newprogram\nts{$\cal NTS$}
307 \newprogram\MakeIndex{{\normalshape\em Makeindex\/}}
308 \newprogram\etex{e-\TeX}
309 \newprogram\LaTeXiii{\LaTeX~3}