Debian Codegraph @

texmf-dist/source/latex/mftinc/mftinc.dtx

raw
1 % \iffalse meta-comment
2 %
3 % Copyright (C) 2005 by Scott Pakin <[email protected]>
4 % -------------------------------------------------------
5 %
6 % This file may be distributed and/or modified under the
7 % conditions of the LaTeX Project Public License, either version 1.2
8 % of this license or (at your option) any later version.
9 % The latest version of this license is in:
10 %
11 % http://www.latex-project.org/lppl.txt
12 %
13 % and version 1.2 or later is part of all distributions of LaTeX
14 % version 1999/12/01 or later.
15 %
16 % \fi
17 %
18 % \iffalse
19 %<*driver>
20 \ProvidesFile{mftinc.dtx}
21 %</driver>
22 %<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
23 %<package>\ProvidesPackage{mftinc}
24 %<*package>
25 [2005/01/31 v1.0a Include pretty-printed Metafont listings in LaTeX]
26 %</package>
27 %
28 %<*driver>
29 \documentclass{ltxdoc}
30 \usepackage{mftinc}[2005/01/31]
31 \EnableCrossrefs
32 \CodelineIndex
33 \RecordChanges
34
35 % Unfortunately, we need to input mftmac.tex in the driver section. Its
36 % lines don't start with "%", which causes doc to complain. Even worse,
37 % mftmac steps on a few LaTeX things, which we have to correct here
38 % and/or every time we show MFT examples in this document.
39 \newlength{\oldparindent}
40 \setlength{\oldparindent}{\parindent}
41 \input mftmac
42 \setlength{\parindent}{\oldparindent}
43
44 % Define a \MFT command to typeset "MFT" in the same font that Knuth
45 % uses to typeset "Metafont". If the font doesn't exist, just use the
46 % current sans-serif font as an approximation.
47 \IfFileExists{mflogo.sty}
48 {\let\MF=\relax
49 \RequirePackage{mflogo}
50 \newcommand{\MFT}{\textlogo{MFT}}}
51 {\newcommand{\MFT}{{\tenlogo MFT}}}
52
53 % Use booktabs if we have it, otherwise fake its macros.
54 \IfFileExists{booktabs.sty}
55 {\RequirePackage{booktabs}}
56 {\let\toprule=\hline
57 \let\midrule=\hline
58 \let\bottomrule=\hline
59 }
60
61 \begin{document}
62 \DocInput{mftinc.dtx}
63 \PrintChanges
64 \PrintIndex
65 \end{document}
66 %</driver>
67 % \fi
68 %
69 % \CheckSum{525}
70 %
71 % \CharacterTable
72 % {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
73 % Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
74 % Digits \0\1\2\3\4\5\6\7\8\9
75 % Exclamation \! Double quote \" Hash (number) \#
76 % Dollar \$ Percent \% Ampersand \&
77 % Acute accent \' Left paren \( Right paren \)
78 % Asterisk \* Plus \+ Comma \,
79 % Minus \- Point \. Solidus \/
80 % Colon \: Semicolon \; Less than \<
81 % Equals \= Greater than \> Question mark \?
82 % Commercial at \@ Left bracket \[ Backslash \\
83 % Right bracket \] Circumflex \^ Underscore \_
84 % Grave accent \` Left brace \{ Vertical bar \|
85 % Right brace \} Tilde \~}
86 %
87 %
88 % \changes{v1.0}{2001/05/15}{Initial version}
89 % \changes{v1.0a}{2005/01/31}{Restructured the \texttt{.dtx} file}
90 %
91 % \GetFileInfo{mftinc.dtx}
92 %
93 % \DoNotIndex{\%, \', \/, \:, \\, \9}
94 % \DoNotIndex{\@height, \@minus, \@plus, \@tempdima}
95 % \DoNotIndex{\addtolength, \advance, \begin, \begingroup, \bgroup}
96 % \DoNotIndex{\box, \char, \chardef, \cr, \DeclareRobustCommand, \def}
97 % \DoNotIndex{\divide, \dp, \egroup, \else, \empty, \end, \endgroup}
98 % \DoNotIndex{\expandafter, \fi, \gdef, \global, \halign, \hbox, \hfil}
99 % \DoNotIndex{\hrule, \hrulefill, \hsize, \hspace}
100 % \DoNotIndex{\ht, \ifdim, \if, \ifnum, \ifx, \ignorespaces, \it}
101 % \DoNotIndex{\kern, \lastpenalty, \let, \loop, \linewidth, \long, \lower}
102 % \DoNotIndex{\meaning, \medskip, \MessageBreak, \multiply, \multispan}
103 % \DoNotIndex{\newcount, \newdimen, \newenvironment, \newfam, \newif}
104 % \DoNotIndex{\newlength, \next}
105 % \DoNotIndex{\noalign, \nobreak, \noindent, \nointerlineskip, \null, \par}
106 % \DoNotIndex{\penalty, \quad, \raise, \renewcommand, \renewenvironment}
107 % \DoNotIndex{\repeat, \rlap, \rm, \setbox, \setlength, \settowidth}
108 % \DoNotIndex{\smash, \space, \tabskip, \the, \tt, \unskip, \vbox, \vcenter}
109 % \DoNotIndex{\vrule, \vskip, \vspace, \xdef}
110 %
111 % ^^A Give LaTeX some more leeway in placing floats
112 % ^^A (suggested by Donald Arseneau <[email protected]>).
113 % \renewcommand{\topfraction}{0.85}
114 % \renewcommand{\bottomfraction}{0.7}
115 % \renewcommand{\textfraction}{0.15}
116 % \renewcommand{\floatpagefraction}{0.66}
117 % \renewcommand{\dbltopfraction}{0.66}
118 % \renewcommand{\dblfloatpagefraction}{0.66}
119 % \setcounter{topnumber}{9}
120 % \setcounter{bottomnumber}{9}
121 % \setcounter{totalnumber}{20}
122 % \setcounter{dbltopnumber}{9}
123 %
124 % ^^A We caption tables at the top, so make sure we have sufficient spacing.
125 % \setlength{\belowcaptionskip}{\abovecaptionskip}
126 %
127 %
128 % \title{The \textsf{mftinc} package\thanks{This document
129 % corresponds to \textsf{mftinc}~\fileversion, dated \filedate.}}
130 % \author{Scott Pakin \\ \texttt{[email protected]}}
131 %
132 % \maketitle
133 %
134 % \begin{abstract}
135 % The \MFT\ program pretty-prints \MF\ source code into a \TeX\ file.
136 % The \textsf{mftinc} package facilitates incorporating such files
137 % into a \LaTeXe\ document. In addition, \textsf{mftinc} provides
138 % routines for improved comment formatting and for typesetting font
139 % tables.
140 % \end{abstract}
141 %
142 % \section{Introduction}
143 %
144 % \MF~\cite{mft:MFB} is Donald Knuth's system for creating fonts---and
145 % entire families of fonts---by describing the characters
146 % mathematically in a specialized programming language. As with any
147 % programming language, it is important for a programmer to document his
148 % code, to make it easier to extend and modify in the future. \MFT\ is
149 % a stand-alone utility that makes \MF\ programs more readable by
150 % typesetting different language constructs (keywords, variables, etc.)\
151 % in different fonts and styles. For example, the following is the font
152 % program for Computer Modern Roman's plus-sign character (taken
153 % from |punct.mf|):
154 %
155 % \begin{verbatim}
156 % cmchar "Plus sign";
157 % beginarithchar("+"); pickup rule.nib;
158 % x1=x2=good.x .5w; top y1=h+eps; .5[y1,y2]=math_axis;
159 % lft x3=hround u-eps; x4=w-x3; y3=y4=math_axis;
160 % draw z1--z2; % stem
161 % draw z3--z4; % crossbar
162 % labels(1,2,3,4); endchar;
163 % \end{verbatim}
164 % \unskip
165 %
166 % \noindent
167 % and this is how \MFT\ formats it:
168 %
169 % \bigskip
170 % \noindent| |^^A
171 % \begin{minipage}{0.9\linewidth}
172 % \let\\=\textit \parindent=0pt
173 % $\2{cmchar}\7"Plus sign";$\par
174 % $\2{beginarithchar}(\7"+");\ \2{pickup}\\{rule}.\\{nib};$\par
175 % $x_{1}=x_{2}=\\{good}.x\,.5w;\ \\{top}\,y_{1}=h+\\{eps};\ .5[y_{1},y_{2}]=^^A
176 % \\{math\_axis};$\par
177 % $\\{lft}\,x_{3}=\1{hround}u-\\{eps};\ x_{4}=w-x_{3};\ y_{3}=y_{4}=\\{math^^A
178 % \_axis};$\par
179 % $\2{draw}z_{1}\8{--}z_{2};\ \9 stem\par
180 % $\2{draw}z_{3}\8{--}z_{4};\ \9 crossbar\par
181 % $\2{labels}(1,2,3,4);\3{endchar};$\par
182 % \end{minipage}
183 % \bigskip
184 %
185 % The formatted version draws attention to language features. It shows
186 % keywords in bold, variables in italics, subscripts as subscripts, and
187 % comments right-justified. The problem, though, is that \MFT\ produces
188 % Plain \TeX\ documents, which can't readily be included into a \LaTeXe\
189 % document. What's the advantage of including formatted font programs
190 % in \LaTeX? The answer is that it lets you take advantage of \LaTeX's
191 % formatting and structuring capabilities to produce clear font
192 % documentation with comparatively little effort. Because a \MF\
193 % program is like any other program, good documentation is important, as
194 % it makes it easier to extend and modify the font in the future. Using
195 % \LaTeX, you can, for instance, put majuscules in one chapter,
196 % miniscules in another, and punctuation in a third; you can include
197 % graphics produced by \MF's smoke or proof modes to show what the
198 % resulting glyphs should look like; and you could add hyperlinks, a
199 % table of contents, a bibliography, font samples, and anything else
200 % that can clarify how the various character programs operate.
201 %
202 % The \textsf{mftinc} packages's initial purpose was somewhat
203 % unambitious: simply include an \MFT-produced |.tex| file within a
204 % \LaTeXe\ document. But it evolved from that to support the following
205 % additional features:
206 %
207 % \begin{itemize}
208 % \item Comments describing large, top-level blocks of code, such
209 % as the character programs themselves
210 %
211 % \item Stanza-level comments within a block of code
212 %
213 % \item Font tables, \`a la Knuth's |textfont.tex| utility
214 % \end{itemize}
215 %
216 % Figure~\ref{mft:annotated-plus} shows an example of how one might
217 % format Computer Modern Roman's plus-sign program, using
218 % \textsf{mftinc}'s comment environments. Notice how \textsf{mftinc}
219 % makes the introductory paragraph stand out from the character program
220 % by placing it between a pair of horizontal rules and the final paragraph
221 % stand out from the surrounding code by prefixing each line with a percent
222 % sign (\MF's comment character).
223 %
224 % \begin{figure}[tp]
225 % \centering
226 % \begin{minipage}{0.9\linewidth}
227 % \let\\=\textit \parindent=0pt
228 % \begin{explaincode}
229 % \sloppy
230 % The following is the definition of the plus sign character (``+'').
231 % Admittedly, the glyph is so simple that it doesn't really need the
232 % depth of commentary that's I'm providing here. I mainly wanted to
233 % show how \textsf{mftinc} formats comments. Speaking of which, this is
234 % a block-level comment, created with \textsf{mftinc}'s
235 % \texttt{explaincode} environment.
236 % \end{explaincode}
237 % $\\{cmchar}\7"Plus sign";$\par
238 % $\2{beginarithchar}(\7"+");$\par
239 % \quad\quad$\9 This is an ordinary \MFT\ comment, entered with
240 % \verb+%+. Notice how only the first line starts with a percent sign,
241 % and the text isn't even properly indented. Yuck! \]\par
242 % \quad\quad$\2{pickup}\\{rule}_{nib};$\par
243 % \BL
244 % \quad\quad$\9 This is another ordinary \MFT, \verb+%+-prefixed comment.
245 % I had to \]\par
246 % \quad\quad$\9 break the lines manually and end each line with a
247 % \verb+\]+. While \]\par
248 % \quad\quad$\9 that's okay for one-liners, it's an immense bother for
249 % longer \]\par
250 % \quad\quad$\9 comments (like this one). \]\par
251 % \quad\quad$x_{1}=x_{2}=\\{good}.x\,.5w;$\par
252 % \quad\quad$\\{top}\,y_{1}=h+\\{eps};$\par
253 % \quad\quad$.5[y_{1},y_{2}]=\\{math\_axis};$\par
254 % \quad\quad$\\{lft}\,x_{3}=\1{hround}u-\\{eps};$\par
255 % \quad\quad$x_{4}=w-x_{3};$\par
256 % \quad\quad$y_{3}=y_{4}=\\{math\_axis};$\par
257 % \BL
258 % \quad\quad \begin{wrapcomment}
259 % \quad\quad Ah, much better! This comment was entered within one of
260 % \quad\quad \textsf{mftinc}'s \texttt{wrapcomment}
261 % \quad\quad environments. Notice how it's indented the correct amount, every
262 % line
263 % \quad\quad starts with a~\verb+%+, and the lines are fully justified---and
264 % none
265 % \quad\quad of this required any manual formatting. \textsf{mftinc} did all
266 % the
267 % \quad\quad work for us.
268 % \quad\quad \end{wrapcomment}
269 % \quad\quad$\2{draw}z_{1}\8{--}z_{2};\ \9 stem\par
270 % \quad\quad$\2{draw}z_{3}\8{--}z_{4};\ \9 crossbar\par
271 % \quad\quad$\2{labels}(1,2,3,4);$\par
272 % $\!\3{endchar};$\par
273 % \end{minipage}
274 % \caption{Computer Modern Roman's ``+'', formatted with \textsf{mftinc}}
275 % \label{mft:annotated-plus}
276 % \end{figure}
277 %
278 %
279 % \section{Usage}
280 %
281 % ^^A The following was swiped verbatim from ltxguide.cls.
282 % \DeleteShortVerb\|
283 % \newenvironment{decl}[1][]%
284 % {\par\small\addvspace{4.5ex plus 1ex}%
285 % \vskip -\parskip
286 % \ifx\relax#1\relax
287 % \def\@decl@date{}%
288 % \else
289 % \def\@decl@date{\NEWfeature{#1}}%
290 % \fi
291 % \noindent\hspace{-\leftmargini}%
292 % \begin{tabular}{|l|}\hline\ignorespaces}%
293 % {\\\hline\end{tabular}\nobreak\@decl@date\par\nobreak
294 % \vspace{2.3ex}\vskip -\parskip}
295 % \MakeShortVerb\|
296 %
297 % I hope the previous section and Figure~\ref{mft:annotated-plus} piqued
298 % your interest in \textsf{mftinc}. We'll now look at how to use all of
299 % \textsf{mftinc}'s features. Remember, the idea is that you use
300 % \textsf{mftinc}'s commands and environments within a |.mf| file
301 % (generally on lines beginning with |%%|, as \MFT\ passes such lines
302 % unmodified to the resulting |.tex| file). You then format the |.mf|
303 % file using \MFT\@. And finally, you include the resulting |.tex| file
304 % into your main \LaTeX\ document (which contains a
305 % |\usepackage{mftinc}| in its prologue to enable \textsf{mftinc}'s
306 % features).
307 %
308 % \begin{center}
309 % \begin{picture}(243,60)(54,0)
310 % \put(73,40){\texttt{.mf}}
311 % \put(89,42){\vector(1,0){34}}
312 % \put(123,24){\framebox(54,36){\texttt{mft}}}
313 % \put(177,42){\vector(1,0){36}}
314 % \put(182,46){\texttt{.tex}}
315 % \put(213,24){\framebox(54,36){\texttt{latex}}}
316 % \put(267,42){\vector(1,0){30}}
317 % \put(54,11){\parbox{63\unitlength}{^^A
318 % \raggedright(with \textsf{mftinc} macros and environments)}}
319 % \put(213,0){\makebox(54,3){\texttt{mftinc.sty}}}
320 % \put(240,7){\vector(0,1){17}}
321 % \end{picture}
322 % \end{center}
323 %
324 % \noindent
325 % Note that \textsf{mftinc}'s macros and environments do, in fact,
326 % work in the main \LaTeX\ document. It's just that some of them
327 % aren't particularly interesting outside of a \MF\ file.
328 %
329 %
330 % \subsection{File inclusion}
331 %
332 % \DeleteShortVerb{\|}\MakeShortVerb{\"}
333 % \begin{decl}
334 % "\mftinput" \marg{filename}
335 % \end{decl}
336 % \DeleteShortVerb{\"}\MakeShortVerb{\|}
337 %
338 % \noindent
339 % \DescribeMacro{\mftinput}
340 % |\mftinput| is used within the main \LaTeX\ document to incorporate
341 % an \MFT-produced |.tex| file. If a file extension is not supplied,
342 % |.tex| is assumed.
343 %
344 %
345 % \subsection{Improved comment handling}
346 %
347 % \DeleteShortVerb{\|}\MakeShortVerb{\"}
348 % \begin{decl}
349 % "\begin{explaincode}" \oarg{options} \\
350 % \meta{comment text} \\
351 % "\end{explaincode}"
352 % \end{decl}
353 % \DeleteShortVerb{\"}\MakeShortVerb{\|}
354 %
355 % \noindent
356 % \DescribeEnv{explaincode}
357 % \MF\ programs define one character program for each glyph in the font.
358 % It's good style to start each of these---and other top-level blocks of
359 % code---with a comment describing the code and its particular nuances.
360 % The |explaincode| environment typesets such comments between
361 % horizontal rules, so that the comments are more easily distinguishable
362 % from the code they describe. |explaincode| also adds a little
363 % stretchable space above the first rule to separate the comment from
364 % whatever precedes it. For example, the following lines in a |.mf| file:
365 %
366 % \begin{verbatim}
367 % %% \begin{explaincode}
368 % %% This text is set within an \texttt{explaincode} environment.
369 % %% \texttt{explaincode} is intended to be used before a character
370 % %% program or other large block of code.
371 % %% \end{explaincode}
372 % \end{verbatim}
373 % \unskip
374 % \noindent
375 % will look like this when run through |latex|:
376 %
377 % \begin{center}
378 % \begin{minipage}{0.85\textwidth}
379 % \begin{explaincode}
380 % This text is set within an \texttt{explaincode} environment.
381 % \texttt{explaincode} is intended to be used before a character
382 % program or other large block of code.
383 % \end{explaincode}
384 % \end{minipage}
385 % \end{center}
386 % \bigskip
387 %
388 % The optional argument to |\begin{explaincode}| provides control
389 % over the thickness of the two rules. This is discussed in
390 % Section~\ref{mft:options}.
391 %
392 %
393 % \DeleteShortVerb{\|}\MakeShortVerb{\"}
394 % \begin{decl}
395 % "\begin{wrapcomment}" \\
396 % \meta{comment text} \\
397 % "\end{wrapcomment}"
398 % \end{decl}
399 % \DeleteShortVerb{\"}\MakeShortVerb{\|}
400 %
401 % \noindent
402 % \DescribeEnv{wrapcomment}
403 % The |wrapcomment| environment is used for comments that describe a
404 % stanza---a logical chunk of code---within a character program or macro.
405 % The important features of comments that are typeset with |wrapcomment|
406 % are the following:
407 %
408 % \begin{itemize}
409 % \item They can be multiple lines long.
410 % \item They wrap text like any other piece of \LaTeX\ code.
411 % \item Each line of output begins with a percent line.
412 % \item The comments use the same indentation as the block of \MF\
413 % code they describe.
414 % \end{itemize}
415 %
416 % Here's an example of a |wrapcomment| that's indented within a \MF\
417 % \textbf{for} loop and the way that \textsf{mftinc} tells \LaTeX\
418 % to format it:
419 %
420 % \begin{verbatim}
421 % for i = 0 upto length cpath:
422 % %% \begin{wrapcomment}
423 % %% See how comments typeset within a \texttt{wrapcomment}
424 % %% environment are indented? They line up with the first
425 % %% \verb+%%+ within the environment. Just remember to use two
426 % %% percent signs instead of one, or bad things will happen.
427 % %% \end{wrapcomment}
428 % draw z[i]--z.c;
429 % endfor;
430 % \end{verbatim}
431 %
432 % \begin{center}
433 % \begin{minipage}{0.85\linewidth}
434 % \let\\=\textit \parindent=0pt
435 % $\2{for}i=0\4{upto}\1{length}\\{cpath}\?:$\par
436 % \quad\quad \begin{wrapcomment}
437 % \quad\quad See how comments typeset within a \texttt{wrapcomment}
438 % \quad\quad environment are indented? They line up with the first
439 % \quad\quad \verb+%%+ within the environment. Just remember to use two
440 % \quad\quad percent signs instead of one, or bad things will happen.
441 % \quad\quad \end{wrapcomment}\par
442 % \quad\quad$\2{draw}z[i]\8{--}z_{c};$\par
443 % $\!\3{endfor};$\par
444 % \end{minipage}
445 % \end{center}
446 %
447 %
448 % \DeleteShortVerb{\|}\MakeShortVerb{\"}
449 % \begin{decl}
450 % "\mfcomment"
451 % \end{decl}
452 % \DeleteShortVerb{\"}\MakeShortVerb{\|}
453 %
454 % \noindent
455 % \DescribeMacro{\mfcomment}
456 % One advantage that \MFT's |%| comments have over |%%| comments is that
457 % they format anything that's set between vertical bars as it if it were
458 % \MF\ code. For example, \verb+|draw z1--z2|+ is typeset as
459 % ``$\2{draw}z_{1}\8{--}z_{2}$''. The problem is that the |explaincode|
460 % and |wrapcomment| environments need to be typeset with~|%%|, so their
461 % contents gets passed directly to \LaTeX. To embed \MF\ code within
462 % |explaincode| or |wrapcomment|, one need only end the previous line with
463 % |\mfcomment| and put the \MF\ code on the next line, preceded by a~|%|:
464 %
465 % \begin{verbatim}
466 % %% \begin{wrapcomment}
467 % %% The reason we set \mfcomment
468 % % |x4 = w - x3|
469 % %% below is to ensure that when we later \mfcomment
470 % % do a ``|draw x4{up}..x1..{down}x3|'', the character
471 % %% will have equal left and right sidebearings.
472 % %% \end{wrapcomment}
473 % \end{verbatim}
474 %
475 % \begin{center}
476 % \begin{minipage}{0.9\linewidth}
477 % \let\\=\textit \parindent=0pt
478 % \quad \begin{wrapcomment}
479 % \quad The reason we set \mfcomment
480 % \quad$\9 $x_{4}=w-x_{3}$\par
481 % \quad below is to ensure that when we later \mfcomment
482 % \quad$\9 do a ``$\2{draw}x_{4}\{\\{up}\}\8{..}x_{1}\8{..}\{\\{down}%
483 % \}x_{3}$'', the character\par
484 % \quad will have equal left and right sidebearings.
485 % \quad \end{wrapcomment}
486 % \end{minipage}
487 % \end{center}
488 %
489 %
490 % \subsection{Font tables}
491 %
492 % Most \TeX\ distributions come with a program of Knuth's called
493 % |testfont.tex|, which can produce a variety of font samples. One of
494 % |testfont|'s more useful features is the ability to produce a table of
495 % all the characters in a given font:
496 %
497 % \begin{verbatim}
498 % % tex testfont
499 % This is TeX, Version 3.14159 (Web2C 7.3.2)
500 % (/usr/share/texmf/tex/plain/base/testfont.tex
501 %
502 % Name of the font to test = cmr10.mf
503 % Now type a test command (\help for help):)
504 % *\table
505 %
506 % *\bye
507 % [1]
508 % Output written on testfont.dvi (1 page, 5812 bytes).
509 % Transcript written on testfont.log.
510 % \end{verbatim}
511 % \unskip
512 %
513 % \def\oct#1{\hbox{\rm\'{}\kern-.2em\it#1\/\kern.05em}}%
514 % \def\hex#1{\hbox{\rm\H{}\tt#1}}%
515 %
516 % \noindent
517 % Table~\ref{mft:cmr10-full} depicts the table that this produces.
518 % Characters are numbered in both octal (\oct{000}--\oct{177}) and
519 % hexadecimal (\hex{00}--\hex{7F}). Empty rows---of which there aren't
520 % any in this example---are automatically omitted.
521 %
522 % \begin{table}[htbp]
523 % \caption{Complete \texttt{cmr10} character set}
524 % \label{mft:cmr10-full}
525 % \fonttable{cmr10}
526 % \end{table}
527 %
528 %
529 % \DescribeMacro{\fonttable}
530 % The problem is that |testfont.tex| was designed to be used
531 % interactively and stand-alone. But wouldn't it be nice to be able to
532 % include a font table in the same document that contains the annotated
533 % font source code? With \textsf{mftinc}, you can do just that.
534 % \textsf{mftinc} includes a |\fonttable| command, based on the one in
535 % |testfont.tex|---in fact, much of |\fonttable|'s code was taken verbatim
536 % from |testfont.tex|---but extended to provide more features and to
537 % interact better with \LaTeX.
538 %
539 % \DeleteShortVerb{\|}\MakeShortVerb{\"}
540 % \begin{decl}
541 % "\fonttable" \oarg{options} \marg{font name}
542 % \end{decl}
543 % \DeleteShortVerb{\"}\MakeShortVerb{\|}
544 %
545 % \noindent
546 % The mandatory argument, \meta{font name}, is the name of the font to
547 % chart. Note that this must be the \TeX, as opposed to \LaTeXe, font
548 % name. For example, to draw a font table of 11\,pt.\ Computer Modern
549 % Typewriter Text, one would have to write ``|\fonttable{cmtt10|
550 % \texttt{at 11pt}|}|'', because there is no 11\,pt.\ version of the
551 % font, only a 10\,pt.\ version scaled up to~11\,pt. The optional
552 % argument to |\fonttable|, \meta{options}, provides control over the
553 % width of the table and the range of characters included within it.
554 % This is discussed in Section~\ref{mft:options}.
555 %
556 %
557 % \subsection{Options}
558 % \label{mft:options}
559 %
560 % The |explaincode| environment and the |\fonttable| macro each take an
561 % optional argument containing zero or more comma-separated,
562 % \meta{key}=\meta{value} pairs. These allow for finer control over
563 % \textsf{mftinc}'s behavior.
564 %
565 % \DeleteShortVerb{\|}\MakeShortVerb{\"}
566 % \begin{decl}
567 % "toprule="\meta{dimen} \\
568 % "bottomrule="\meta{dimen}
569 % \end{decl}
570 % \DeleteShortVerb{\"}\MakeShortVerb{\|}
571 %
572 % \noindent
573 % The horizontal rules drawn above and below an |explaincode| comment
574 % are normally 1\,pt.\ thick. The |toprule| and |bottomrule| options
575 % enable you to change this default. For example:
576 %
577 % \begin{verbatim}
578 % %% \begin{explaincode}[toprule=3mm,bottomrule=5pt]
579 % %% The rule above this sentence is 3\,mm.\ thick, and the rule
580 % %% below this sentence is 5\,pt.\ thick.
581 % %% \end{explaincode}
582 % \end{verbatim}
583 % \unskip
584 %
585 % \begin{center}
586 % \begin{minipage}{0.85\textwidth}
587 % \begin{explaincode}[toprule=3mm,bottomrule=5pt]
588 % The rule above this sentence is 3\,mm.\ thick, and the rule
589 % below this sentence is 5\,pt.\ thick.
590 % \end{explaincode}
591 % \end{minipage}
592 % \end{center}
593 %
594 % \DeleteShortVerb{\|}\MakeShortVerb{\"}
595 % \begin{decl}
596 % "tablewidth="\meta{dimen}
597 % \end{decl}
598 % \DeleteShortVerb{\"}\MakeShortVerb{\|}
599 %
600 % \noindent
601 % The tables drawn by |\fonttable| normally expand to fill the width of
602 % the text. The |tablewidth| option lets you choose an arbitrary table
603 % width. For example:
604 %
605 % \begin{verbatim}
606 % \fonttable[tablewidth=0.5\linewidth]{logo10}
607 % \end{verbatim}
608 % \unskip
609 %
610 % \begin{center}
611 % \fonttable[tablewidth=0.5\linewidth]{logo10}
612 % \end{center}
613 %
614 % \DeleteShortVerb{\|}\MakeShortVerb{\"}
615 % \begin{decl}
616 % "charrange="\meta{range}
617 % \end{decl}
618 % \DeleteShortVerb{\"}\MakeShortVerb{\|}
619 %
620 % \noindent
621 % Knuth's original table code shows every character in a given font, and
622 % that's what |\fonttable| does by default. However, the |charrange|
623 % option lets you limit the range of characters that are output to a
624 % subset of the characters available in the font. \meta{range} is the
625 % range of character codes to output, specified as
626 % ``\meta{first}|-|\meta{last}''. \meta{first} and \meta{last} are both
627 % inclusive and can be specified in any number format that \TeX\
628 % accepts---decimal (|123|), hexadecimal (|"7B|), or octal (|'173|). If
629 % \meta{first} is omitted (|-123|), it defaults to the first character
630 % in the font. If \meta{last} is omitted (|123-|), it defaults to the
631 % last character in the font. Single numbers (|123|) are acceptable, as
632 % are comma-separated ranges of numbers
633 % (|65-96,|\linebreak[0]|123-127|). In the last case, the ranges must
634 % be specified within curly braces so that \textsf{mftinc} knows they
635 % are all part of |charrange|'s argument, and not the argument to a
636 % subsequent option.
637 %
638 % |charrange| is useful when typesetting font documentation, because a
639 % section can begin by showing a table of all the glyphs that will be
640 % defined in that section. For example |punct.mf| defines the
641 % following subset of the Computer Modern fonts, according to Knuth's
642 % comments at the top of that file:
643 %
644 % \begin{verbatim}
645 % \fonttable[tablewidth=0.75\linewidth,
646 % charrange={'41,'43,'45,'47-'54,'56-'57,'72-'73,'75,
647 % '100,'133,'135,'140}]{cmss10 at 11pt}
648 % \end{verbatim}
649 % \unskip
650 % \noindent
651 % Table~\ref{mft:punct-chars} shows the result of that |\fonttable|
652 % invocation. Note how only the specified characters are shown, and
653 % empty rows (more precisely, empty double-rows) are omitted from the
654 % table. Hence, the table ranges from hexadecimal \hex{20}--\hex{6F}
655 % instead of from \hex{00}--\hex{7F}.
656 %
657 % \begin{table}[htbp]
658 % \centering
659 % \caption{\texttt{cmss10} characters defined in \texttt{punct.mf}}
660 % \label{mft:punct-chars}
661 % \fonttable[tablewidth=0.75\linewidth,
662 % charrange={'41,'43,'45,'47-'54,'56,'57,'72,'73,'75,
663 % '100,'133,'135,'140}]{cmss10 at 11pt}
664 % \end{table}
665 %
666 %
667 % \DeleteShortVerb{\|}\MakeShortVerb{\"}
668 % \begin{decl}
669 % "\setmftdefaults" \marg{options}
670 % \end{decl}
671 % \DeleteShortVerb{\"}\MakeShortVerb{\|}
672 %
673 % \noindent
674 % \DescribeMacro{\setmftdefaults}
675 % It can be cumbersome to repeatedly pass the same arguments to
676 % |charexplain| or |\fonttable|. Hence, \textsf{mftinc} exports a
677 % |\setmftdefaults| macro. |\setmftdefaults| takes the same
678 % \meta{key}=\meta{value} pairs as |charexplain| and |\fonttable|, but
679 % uses them to change the default value of each option for all future
680 % invocations of |charexplain| and |\fonttable|:
681 %
682 % \begin{verbatim}
683 % \setmftdefaults{charrange=65-67,toprule=3pt,bottomrule=3pt}
684 % \begin{explaincode}
685 % \textsf{mftinc}'s default parameters have been altered.
686 % However, it's still possible to override those defaults
687 % on a case-by-case basis.
688 % \begin{center}
689 % \fonttable{cmsy10 at 17pt}
690 % \fonttable[charrange=68-70]{cmsy10 at 17pt}
691 % \fonttable{cmsy10 at 17pt}
692 % \end{center}
693 % \end{explaincode}
694 % \end{verbatim}
695 % \unskip
696 % \noindent
697 % The result is shown in Figure~\ref{mft:setmftdefaults}.
698 %
699 % \begin{figure}[htbp]
700 % \centering
701 % \begin{minipage}{0.85\textwidth}
702 % \setmftdefaults{charrange=65-67,toprule=3pt,bottomrule=3pt}
703 % \begin{explaincode}
704 % \textsf{mftinc}'s default parameters have been altered.
705 % However, it's still possible to override those defaults
706 % on a case-by-case basis.
707 % \begin{center}
708 % \fonttable{cmsy10 at 17pt}
709 % \fonttable[charrange=68-70]{cmsy10 at 17pt}
710 % \fonttable{cmsy10 at 17pt}
711 % \end{center}
712 % \end{explaincode}
713 % \end{minipage}
714 % \caption{Example of changing and overriding \textsf{mftinc}'s defaults}
715 % \label{mft:setmftdefaults}
716 % \end{figure}
717 %
718 %
719 % \section{Other information}
720 %
721 % This section contains miscellaneous commentary on \textsf{mftinc},
722 % \MFT, and other things that don't fit into any of the other sections.
723 %
724 % \subsection{\textsf{mftinc} copyright and license}
725 %
726 % Copyright \textcopyright\ 2005 Scott Pakin \texttt{<[email protected]>}.
727 % \bigskip
728 %
729 % This package may be distributed and/or modified under the
730 % conditions of the \LaTeX\ Project Public License, either version~1.2
731 % of this license or (at your option) any later version.
732 % The latest version of this license is in
733 % \begin{center}
734 % |http://www.latex-project.org/lppl.txt|
735 % \end{center}
736 % \noindent
737 % and version~1.2 or later is part of all distributions of \LaTeX\
738 % version~1999/12/01 or later.
739 %
740 %
741 % \subsection{Package dependencies}
742 %
743 % \textsf{mftinc} requires the \textsf{rawfonts} and \textsf{keyval}
744 % packages, both of which are included with virtually every \LaTeXe\
745 % distribution. The |wrapcomment| environment additionally requires
746 % \textsf{chngpage} and \textsf{lineno}, which are nonstandard but
747 % freely available from CTAN (\texttt{http://www.ctan.org/}). If
748 % \textsf{mftinc} can't find \textsf{chngpage} or \textsf{lineno}, it
749 % will issue a \emph{warning} message, which turns into an error message at
750 % the first |\begin{wrapcomment}|. Hence, if you merely want to include
751 % \MFT\ output, font tables, and character-level comments and are willing
752 % to sacrifice stanza-level comments, you can avoid the bother of
753 % downloading and installing two additional packages.
754 %
755 %
756 % \subsection{Including proof and smoke images}
757 %
758 % Knuth's \textit{Computer Modern Typefaces}~\cite{mft:CMT} shows
759 % proof-mode versions of each character next to the corresponding
760 % character program. One way to do this yourself for your own fonts is
761 % to use MetaPost, which can produce an Encapsulated PostScript (EPS)
762 % image of each character in a font. The exact details may differ
763 % slightly from system to system, but here's the basic approach: First,
764 % assuming you don't already have it, you have to produce a
765 % |mfplain.mem| file. The command to do this on a Unix-based system is
766 % usually:
767 %
768 % \bigskip
769 % \noindent
770 % | mpost -ini '\input mfplain; dump'|
771 % \bigskip
772 %
773 % \noindent
774 % On Windows, you'll probably need to use double quotes instead of single
775 % quotes. On other systems, you're on your own.
776 %
777 % The |mfplain.mem| files enables MetaPost to accept (most) \MF\ commands.
778 % The next step is to use MetaPost plus |mfplain.mem| to produce a proof-mode
779 % version of your font:
780 %
781 % \bigskip
782 % \noindent
783 % | mpost -mem mfplain '\mode:=proof; prologues:=2; input |\meta{filename}|'|
784 % \bigskip
785 %
786 % \noindent
787 % \dots or a smoke-mode version:
788 %
789 % \bigskip
790 % \noindent
791 % | mpost -mem mfplain '\mode:=smoke; prologues:=2; input |\meta{filename}|'|
792 % \bigskip
793 %
794 % In either case, MetaPost will produce a separate EPS file for each
795 % character in the font. These will be named
796 % \meta{filename}|.|\meta{character code}. For example, the EPS file
797 % for |cmr10.mf|'s letter ``A'' will be called |cmr10.65|, because ``A''
798 % is at position~65 in that font. You may want to give these files a
799 % |.eps| extension, so that \LaTeX\ and other programs realize that the
800 % files are EPS\@. The good news is that even pdf\LaTeX, which can't read
801 % arbitrary EPS files, can read MetaPost's EPS output. (By default,
802 % pdf\LaTeX\ expects the files to have a |.mps| extension, however.)
803 %
804 %
805 % \subsection{Known bugs}
806 %
807 % The first |%%| after a |\begin{wrapcomment}| must be indented at least
808 % one space. Otherwise, \LaTeX\ will abort with ``\texttt{! LaTeX Error:}
809 % |\begin{wrapcomment}| \texttt{on input line}~\meta{line} \texttt{ended
810 % by} |\end{linenumbers}|''.
811 %
812 %
813 % \subsection{A brief \MFT\ reference}
814 %
815 % \MFT\ processes comments beginning with one to four percent signs in
816 % different ways, as shown in Table~\ref{mft:mft-comments}. The \MFT\
817 % documentation says that comments starting with more than four percent
818 % signs are verboten. \textsf{mftinc} is normally used within
819 % double-percent comments, because those are passed directly to \LaTeX\
820 % with no additional processing on \MFT's part.
821 %
822 % \begin{table}[htbp]
823 % \centering
824 % \caption{\MFT\ comment types}
825 % \label{mft:mft-comments}
826 % \renewcommand{\arraystretch}{1.5}
827 % \begin{tabular}{@{}lp{0.7\textwidth}@{}} \toprule
828 % \multicolumn{1}{@{}c}{Type} &
829 % \multicolumn{1}{c@{}}{Description} \\ \midrule
830 %
831 % |%| &
832 % Format a comment using \TeX\ (or with \textsf{mftinc}, \LaTeX), with
833 % the addition that text within vertical bars is formatted as if it were
834 % outside of the comment (i.e., as if it were \MF\ code). Single-|%|
835 % comments are output right-justified with a leading percent sign.
836 % Ending a line with |\]| makes it left-justified, though. \\
837 %
838 % |%%| &
839 % Format a comment using \TeX\ (or with \textsf{mftinc}, \LaTeX), with
840 % none of single-|%|'s bells and whistles---no leading percent sign, no
841 % right-justification, and no support for embedded \MF\ code.
842 % \textsf{mftinc}'s |explaincode| and |wrapcomment| environments
843 % belong within double-|%| comments. \\
844 %
845 % |%%%| &
846 % Given a list of space-separated \MF\ tokens, make \MFT\ format all
847 % of them like the first one in the list. Hence ``|%%%|
848 % \texttt{addto mymacro}'' says to format the token |mymacro| just
849 % like \MF's |addto| primitive. \\
850 %
851 % |%%%%| &
852 % \MFT\ discards lines beginning with quadruple-|%| comments. \\
853 % \bottomrule
854 % \end{tabular}
855 % \end{table}
856 %
857 % |mftmac.tex|, which is |\input| by every |.tex| file that \MFT\
858 % produces, defines a number of macros for typesetting \MF\
859 % (Table~\ref{mft:additional-macros}). These may be used within a |%%|
860 % comment when doing so is more convenient than \textsf{mftinc}'s
861 % |\mfcomment| macro (e.g., if only a single symbol need be typeset).
862 % The following are the important things to note about these macros:
863 %
864 % \begin{itemize}
865 % \item They're defined to be used in math mode, so be sure to use
866 % them within |$|\dots|$|.
867 %
868 % \item The different boldfaced operators have different surrounding
869 % spacing (not always obvious from
870 % Table~\ref{mft:additional-macros}). To select the right operator,
871 % I usually look at the |.tex| file to see how it formats the
872 % operator in the font program listing.
873 %
874 % \item |\\| doesn't mean ``line break'', as it normally does in \LaTeX;
875 % use |\newline| instead.
876 % \end{itemize}
877 %
878 % \begin{table}[htbp]
879 % \centering
880 % \caption{Additional \MFT\ macros}
881 % \label{mft:additional-macros}
882 % \begin{tabular}{@{}ll@{}} \toprule
883 % \multicolumn{1}{@{}c}{Macro} &
884 % \multicolumn{1}{c@{}}{Example} \\ \midrule
885 %
886 % |\\|\marg{identifier} & \textit{i}, \textit{eps} \\
887 % |\1|\marg{operator} & $\1{length}$, $\1{hround}$ \\
888 % |\2|\marg{operator} & $\2{beginchar}$, $\2{for}$ \\
889 % |\3|\marg{closing operator} & $\3{fi}$, $\3{endgroup}$ \\
890 % |\4|\marg{binary operator} & $\4{step}$, $\4{at}$ \\
891 % |\5|\marg{constant} & $\5{true}$, $\5{nullpicture}$ \\
892 % |\6|\marg{binary operator} & $\6{++}$, $\6{scaled}$ \\
893 % |\7"|\meta{string}|"| & $\7"Hello, world!"$ \\
894 % |\8|\marg{relation} & $\8{..}$, $\8{--}$ \\
895 % |\?|\marg{relation} & \DeleteShortVerb{\|}
896 % $\?{::}$, $\?{||:}$
897 % \MakeShortVerb{\|} \\
898 % |\PS| & $\PS$ \\
899 % |\SH| & $\SH$ \\
900 % |\frac|\marg{num}|/|\marg{den} & $\frac{17}/{23}$ \\
901 % \bottomrule
902 % \end{tabular}
903 % \end{table}
904 %
905 %
906 % \StopEventually{^^A
907 % \begin{thebibliography}{1}
908 % \bibitem{mft:MFB}
909 % Donald~E. Knuth.
910 % \newblock {\em The \MF{}book}, volume~C of {\em Computers and Typesetting}.
911 % \newblock Addison-Wesley, Reading, Massachusetts, 1986.
912 %
913 % \bibitem{mft:CMT}
914 % Donald~E. Knuth.
915 % \newblock {\em Computer Modern Typefaces}, volume~E of {\em Computers and
916 % Typesetting}.
917 % \newblock Addison-Wesley, Reading, Massachusetts, 1986.
918 % \end{thebibliography}
919 % }
920 %
921 %
922 % \section{Implementation}
923 %
924 % Most users can stop reading at this point. The Implementation section
925 % contains the annotated source code for the \textsf{mftinc} package
926 % itself, which is useful only to people who want a detailed and precise
927 % explanation of how \textsf{mftinc} works. If you're planning on
928 % extending or customizing (or debugging!) the package, this is the
929 % section for you. (Note that \textsf{mftinc} is released under the
930 % \LaTeX\ Project Public License, which gives your the right to make
931 % whatever modifications you want, provided you don't call the result
932 % ``\textsf{mftinc}''.)
933 %
934 % \subsection{Including \MFT-formatted files}
935 %
936 % The following code provides the minimal amount of functionality
937 % that \textsf{mftinc} needs to be useful: the ability to include an
938 % \MFT-produced \TeX\ file in a \LaTeXe\ document. Because
939 % \textsf{mftmac} uses \TeX\ (and \LaTeX~2.09) font names, such
940 % as |\tenbf|, we have to load the \textsf{rawfonts} compatibility
941 % package to make it work. In addition, \textsf{mftmac} assumes that
942 % the |\bffam| and |\itfam| font families are predefined, which they
943 % aren't in \LaTeXe, so we have to define those, too.
944 %
945 % \begin{macrocode}
946 \RequirePackage{rawfonts}
947 \newfam\bffam
948 \newfam\itfam
949 % \end{macrocode}
950 %
951 % \begin{macro}{\mftinput}
952 % Fortunately, most of \textsf{mftmac}'s screwy macro definitions are
953 % defined in the local scope (i.e., with |\def| instead of |\gdef|).
954 % Hence, we can simply |\input| an \MFT-formatted file within a group,
955 % and most things will go back to normal at the |\endgroup|.
956 % \begin{macrocode}
957 \DeclareRobustCommand{\mftinput}[1]{\begingroup\input #1\endgroup}
958 % \end{macrocode}
959 % \end{macro}
960 %
961 %
962 % \subsection{Argument processing}
963 %
964 % The |explainchar| environment and the |\fonttable| command each take a
965 % few optional arguments. We use the \textsf{keyval} package to help
966 % process these arguments. Table~\ref{mft:supported-args} lists the
967 % arguments that are currently supported.
968 %
969 % \begin{table}[htbp]
970 % \centering
971 % \caption{Options supported by \textsf{mftinc}'s macros and environments}
972 % \label{mft:supported-args}
973 % \renewcommand{\arraystretch}{1.5}
974 % \begin{tabular}{@{}lllp{3cm}@{}} \toprule
975 % \multicolumn{1}{@{}c}{Key} &
976 % \multicolumn{1}{c}{Applies to} &
977 % \multicolumn{1}{c}{Affects} &
978 % \multicolumn{1}{c@{}}{Meaning} \\ \midrule
979 %
980 % |toprule| & |explainchar| & |\mft@top@rule| &
981 % Width of the rule above |explainchar| comments \\
982 %
983 % |bottomrule| & |explainchar| & |\mft@bot@rule| &
984 % Width of the rule below |explainchar| comments \\
985 %
986 % |tablewidth| & |\fonttable| & |\mft@table@width| &
987 % Width of the font table \\
988 %
989 % |charrange| & |\fonttable| &
990 % \multicolumn{1}{p{12em}}{\raggedright\texttt{\string\mft@ranges} and
991 % \texttt{\string\mft@expanded@ranges}} &
992 % Comma-delimited, hyphenated ranges of characters to include in
993 % the font table \\ \bottomrule
994 % \end{tabular}
995 % \end{table}
996 %
997 % \begin{macrocode}
998 \RequirePackage{keyval}
999 \define@key{mft}{toprule}{\setlength{\mft@top@rule}{#1}}
1000 \define@key{mft}{bottomrule}{\setlength{\mft@bot@rule}{#1}}
1001 \define@key{mft}{tablewidth}{\setlength{\mft@table@width}{#1}}%
1002 \define@key{mft}{charrange}{%
1003 \def\mft@ranges{}%
1004 \def\mft@expanded@ranges{}%
1005 \mft@parse@ranges#1,,%
1006 {\let\@elt=\mft@expand@range\mft@ranges}%
1007 }
1008 % \end{macrocode}
1009 %
1010 % \begin{macro}{\setmftdefaults}
1011 % Rather than repeatedly specify the same optional arguments, one can
1012 % use |\setmftdefaults| to specify default values for all
1013 % \textsf{mftinc} macros and environments that take optional arguments.
1014 % |\setmftdefaults| takes one mandatory argument, which has the same
1015 % effect globally as the various macros' and environments' optional
1016 % arguments have locally.
1017 % \begin{macrocode}
1018 \DeclareRobustCommand{\setmftdefaults}[1]{\setkeys{mft}{#1}}
1019 % \end{macrocode}
1020 % \end{macro}
1021 %
1022 %
1023 % \subsection{Improved comment formatting}
1024 %
1025 % There are three main places a font designer might want to insert
1026 % code comments:
1027 %
1028 % \begin{enumerate}
1029 % \item Before a character program or macro,
1030 % \item Before a stanza of a code within a character program or macro, and
1031 % \item On the same line as some \MF\ code.
1032 % \end{enumerate}
1033 %
1034 % \noindent
1035 %
1036 % \MFT\ has weak support for the first two of those. While \MFT\ passes
1037 % lines starting with ``|%%|'' directly to \TeX\ (or, when
1038 % \textsf{mftinc} is used, \LaTeX), text formatted this way doesn't
1039 % sufficiently stand stand out from the formatted \MF\ code, in my
1040 % opinion. Comments starting with~|%| are normally right-justified and
1041 % work well when used for brief phrases that share a line with \MF\
1042 % code, but they are cumbersome to use for longer, non-right-justified,
1043 % stanza-level comments. In order to make each output line start with a
1044 % |%| (to make it clear that the text is a comment and not code), the
1045 % author must manually break lines and, in addition, end each line with
1046 % |\]| to inhibit right-justification.
1047 %
1048 % The macros that will be introduced in this section solve all of these
1049 % problems.
1050 %
1051 %
1052 % \subsubsection{Character-level comments}
1053 %
1054 % To clearly separate commentary from the program text that follows, we
1055 % define a simple, |explaincode| environment that draws a horizontal
1056 % rule above and below the contained text.
1057 %
1058 % \begin{macro}{\mft@top@rule}
1059 % Specify the thickness of the rule above the |explaincode| text.
1060 % \begin{macrocode}
1061 \newlength{\mft@top@rule}
1062 \setlength{\mft@top@rule}{1pt}
1063 % \end{macrocode}
1064 % \end{macro}
1065 %
1066 % \begin{macro}{\mft@bot@rule}
1067 % Specify the thickness of the rule below the |explaincode| text.
1068 % \begin{macrocode}
1069 \newlength{\mft@bot@rule}
1070 \setlength{\mft@bot@rule}{1pt}
1071 % \end{macrocode}
1072 % \end{macro}
1073 %
1074 % \begin{environment}{explaincode}
1075 % Draw a rule above and below any text contained within
1076 % |\begin{explaincode}|\dots\linebreak[0]|\end{explaincode}|. For
1077 % \ae{}sethetics, we add a little stretchable glue above the first rule
1078 % and a little shrinkable glue below the bottom rule. We also prohibit
1079 % page breaks between the rules and the text.
1080 % \begin{macrocode}
1081 \newenvironment{explaincode}[1][]{%
1082 \setkeys{mft}{#1}%
1083 \par\vskip 4ex \@plus 2ex
1084 \hrule\@height\mft@top@rule
1085 \nobreak\medskip\nobreak\noindent\ignorespaces
1086 }{%
1087 \nobreak\medskip\nobreak
1088 \hrule\@height\mft@bot@rule
1089 \vskip 2ex \@minus 1ex
1090 }
1091 % \end{macrocode}
1092 % \end{environment}
1093 %
1094 %
1095 % \subsubsection{Stanza-level comments}
1096 %
1097 % We define a new environment for formatting stanza-level comments that
1098 % honors the following properties:
1099 %
1100 % \begin{itemize}
1101 % \item The comments can be multiple lines long.
1102 % \item They wrap text like an ordinary block of \LaTeX\ code.
1103 % \item Each line of output begins with a percent line.
1104 % \item The comments use the same indentation as the block of \MF\
1105 % code they describe.
1106 % \end{itemize}
1107 %
1108 % \begin{macro}{\mft@wc@indent}
1109 % This \meta{dimen} stores the indentation of a |wrapcomment|
1110 % environment, excluding the space occupied by the initial percent
1111 % signs.
1112 % \begin{macrocode}
1113 \newlength{\mft@wc@indent}
1114 % \end{macrocode}
1115 % \end{macro}
1116 %
1117 % \begin{macro}{\mft@eat@quads}
1118 % To figure out the correct indentation for the entire comment block, we
1119 % (tail-recursively) count the number of |\quad|s in the first line,
1120 % adding |1em| of space to |\mft@wc@indent| for each one encountered and
1121 % discarding the |\quad| as we go. At the end, we make |\quad| a no-op,
1122 % to prevent |\quad|s on subsequent lines from contributing unwanted
1123 % space, indent by |\mft@wc@indent| plus the width of a percent sign,
1124 % and use \textsf{lineno} to ``number'' the lines using percent signs.
1125 % \begin{macrocode}
1126 \def\mft@eat@quads#1{%
1127 \ifx#1\quad
1128 \global\addtolength{\mft@wc@indent}{1em}%
1129 \expandafter\mft@eat@quads
1130 \else
1131 \def\quad{}%
1132 \settowidth{\@tempdima}{\%~}%
1133 \advance\@tempdima by \mft@wc@indent
1134 \vspace{-2ex}%
1135 \begin{adjustwidth}{\@tempdima}{}%
1136 \begin{linenumbers}%
1137 \internallinenumbers
1138 \renewcommand{\makeLineNumber}{%
1139 \rlap{\hspace*{\mft@wc@indent}\%}}%
1140 \expandafter#1%
1141 \fi
1142 }
1143 % \end{macrocode}
1144 % \end{macro}
1145 %
1146 % \begin{environment}{wrapcomment}
1147 % Display a block of text that is indented to the same position as the
1148 % first text after the |\begin{wrapcomment}|. |\mft@eat@quads| does
1149 % most of the work. |wrapcomment| merely resets the indentation counter
1150 % and makes the first |\quad| consume the rest (via |\mft@eat@quads|).
1151 % The |\end{wrapcomment}| closes the |linenumbers| and |adjustwidth|
1152 % environments opened by |\mft@eat@quads|.
1153 % \begin{macrocode}
1154 \newenvironment{wrapcomment}{%
1155 \global\setlength{\mft@wc@indent}{0pt}%
1156 \def\quad{%
1157 \global\addtolength{\mft@wc@indent}{1em}%
1158 \mft@eat@quads
1159 }%
1160 }{%
1161 \end{linenumbers}%
1162 \end{adjustwidth}%
1163 }
1164 % \end{macrocode}
1165 % \end{environment}
1166 %
1167 % \begin{macro}{\mft@missing}
1168 % If we can't load one or both of the \textsf{chngpage} and
1169 % \textsf{lineno} packages, disable the |wrapcomment| environment and
1170 % issue a warning message. This is a little more user-friendly than
1171 % forcing the user to download and install two packages if all he wants
1172 % is to include an \MFT-formatted file in a \LaTeX\ document and has no
1173 % interest in ever using the |wrapcomment| environment.
1174 % \begin{macrocode}
1175 \def\mft@missing#1{%
1176 \PackageWarning{mftinc}{%
1177 Disabling the wrapcomment environment\MessageBreak
1178 (can't find #1.sty)%
1179 }
1180 \renewenvironment{wrapcomment}{%
1181 \PackageError{mftinc}{The wrapcomment environment is disabled}{%
1182 Your LaTeX installation is lacking #1.sty.\space\space
1183 The\MessageBreak mftinc package relies on both the chngpage
1184 package and\MessageBreak the lineno package in order to
1185 implement the wrapcomment \MessageBreak environment.\space\space
1186 Either install those packages, or refrain\MessageBreak from
1187 using wrapcomment in code that is formatted with
1188 mft\MessageBreak and included into LaTeX.
1189 }%
1190 }{}%
1191 \def\mft@missing##1{}%
1192 }
1193 \IfFileExists{chngpage.sty}{\RequirePackage{chngpage}}{\mft@missing{chngpage}}
1194 \IfFileExists{lineno.sty}{\RequirePackage{lineno}}{\mft@missing{lineno}}
1195 % \end{macrocode}
1196 % \end{macro}
1197 %
1198 %
1199 % \subsubsection{Other comment-related macros}
1200 %
1201 % \begin{macro}{\mfcomment}
1202 % One advantage that \MFT's |%| comments have over |%%| comments is that
1203 % they format anything that's set between vertical bars as it if it were
1204 % \MF\ code. For example, \verb+|draw z1--z2|+ is typeset as
1205 % ``$\2{draw}z_{1}\8{--}z_{2}$''. The problem is that the |explaincode|
1206 % and |wrapcomment| environments need to be typeset with~|%%|, so their
1207 % contents gets passed directly to \LaTeX. To embed \MF\ code within
1208 % one of those environments, one need only end the previous line with
1209 % |\mfcomment| and put the \MF\ code alone on the next line, preceded by
1210 % a~|%|.
1211 % \begin{macrocode}
1212 \long\def\mfcomment#1\9#2\par{\unskip#2 }
1213 % \end{macrocode}
1214 % \end{macro}
1215 %
1216 %
1217 % \subsection{Font tables}
1218 %
1219 % \TeX\ comes with a |testfont.tex| file that, among other things,
1220 % outputs a table of all the characters in a given font. This table can
1221 % be a useful addition to pretty-printed font documentation. However,
1222 % |testfont.tex| is intended to be run stand-alone. The code in this
1223 % section produces an identical-looking table to |testfont.tex|'s, but
1224 % it can be included easily in a \LaTeX\ document.
1225 % The core of |\fontable| was taken almost verbatim from |testfont.tex|.
1226 % I made the following key changes, however:
1227 %
1228 % \begin{itemize}
1229 % \item I put everything within a |minipage|, to make it easy to move
1230 % the table around and scale its width.
1231 %
1232 % \item I renamed all the global variables, so as to avoid potential
1233 % conflicts with other packages or the main document;
1234 %
1235 % \item I added argument parsing to set the table width and to limit
1236 % the character ranges.
1237 % \end{itemize}
1238 %
1239 %
1240 % \subsubsection{Range processing}
1241 %
1242 % |\fonttable| normally shows only nonempty rows of characters. The
1243 % macros in this section impose an additional limit: Only characters
1244 % within certain ranges are output; the rest are treated as if they
1245 % don't exist.
1246 %
1247 % \begin{macro}{\mft@ranges}
1248 % \begin{macro}{\mft@parse@ranges}
1249 % |\mft@parse@ranges| is the top-level range-parsing function. It
1250 % splits its argument into comma-separated ranges and uses |\@cons| to
1251 % store these ranges in |\mft@ranges| in the form ``|\@elt|
1252 % \meta{range${}_1$}|-!-!-!!| |\@elt| \meta{range${}_2$}|-!-!-!!|~\dots''.
1253 % (The exclamation marks are needed by |\mft@expand@range| to parse the
1254 % range into its components.)
1255 % \begin{macrocode}
1256 \def\mft@ranges{}
1257 \def\mft@parse@ranges#1,{%
1258 \def\mft@arg@i{#1}%
1259 \ifx\mft@arg@i\empty
1260 \else
1261 \@cons\mft@ranges{#1-!-!-!!}%
1262 \expandafter\mft@parse@ranges
1263 \fi
1264 }
1265 % \end{macrocode}
1266 % \end{macro}
1267 % \end{macro}
1268 %
1269 % \begin{macro}{\mft@expanded@ranges}
1270 % \begin{macro}{\mft@gobble@range}
1271 % \begin{macro}{\mft@expand@range}
1272 % Once |\mft@parse@ranges| has split comma-separated ranges into
1273 % elements in |\mft@ranges|, the next step is to canonicalize each
1274 % range, to simplify later range processing. That's what
1275 % |\mft@expand@range| does. It converts each range in |\mft@ranges| to
1276 % the form ``|\@elt| \meta{first}\verb!|!\meta{last}\verb!|!'', in which
1277 % neither \meta{first} nor \meta{last} is empty. Canonicalization works
1278 % in the following manner:
1279 %
1280 % \begin{center}
1281 % \begin{tabular}{r@{\texttt{-}}^^A
1282 % l@{\quad$\mapsto$\quad}^^A
1283 % r@{\texttt{\string|}}l@{\texttt{\string|}}}
1284 % \meta{first} & \meta{last} & \meta{first} & \meta{last} \\
1285 % \meta{first} & & \meta{first} & |65535| \\
1286 % & \meta{last} & |-1| & \meta{last} \\
1287 % \multicolumn{2}{c@{\quad$\mapsto$\quad}}{\meta{only}} & \meta{only} & \meta{only} \\
1288 % \end{tabular}
1289 % \end{center}
1290 %
1291 % \noindent
1292 % The resulting canonicalized list is stored in |\mft@expanded@ranges|.
1293 % The |\mft@expand@range| macro expects the input range to terminate
1294 % with ``|-!-!-!!|''. This is how it distinguishes missing components
1295 % from the end of the range. |\mft@gobble@range| discards any
1296 % exclamation marks that remain after processing.
1297 % \begin{macrocode}
1298 \def\mft@expanded@ranges{}
1299 \def\mft@gobble@range#1!!{}
1300 \def\mft@expand@range#1-#2-{%
1301 \def\mft@arg@i{#1}%
1302 \def\mft@arg@ii{#2}%
1303 \ifx\mft@arg@i\empty
1304 \def\mft@arg@i{-1}%
1305 \fi
1306 \ifx\mft@arg@ii\empty
1307 \def\mft@arg@ii{65535}%
1308 \fi
1309 \if\mft@arg@ii!%
1310 \def\mft@arg@ii{#1}%
1311 \fi
1312 \if\mft@arg@i!%
1313 \else
1314 \@cons\mft@expanded@ranges{\mft@arg@i|\mft@arg@ii|}%
1315 \fi
1316 \mft@gobble@range
1317 }
1318 % \end{macrocode}
1319 % \end{macro}
1320 % \end{macro}
1321 % \end{macro}
1322 %
1323 %
1324 % \subsubsection{Range checking}
1325 %
1326 % Once we know the set of ranges to output, we need to determine whether
1327 % any characters in the current row lie within any of the ranges
1328 % (|\mft@check@char|) and whether a character in a nonempty row lies
1329 % within any of the ranges (|\mft@char|). These macros actually belong
1330 % within |\fonttable|, but the macro nesting depth was starting to get
1331 % too large---I was getting lost amid long sequences of |#|s.
1332 %
1333 % \begin{macro}{\mft@check@char}
1334 % Given an octal digit, form a number by appending it to a sequence
1335 % |\mft@h| of octal digits. If the number lies within any of the ranges
1336 % listed in |\mft@expanded@ranges|, output the corresponding character.
1337 % Otherwise, output nothing.
1338 % \begin{macrocode}
1339 \def\mft@check@char#1{%
1340 \begingroup
1341 \def\@elt##1|##2|{%
1342 \ifnum"\mft@h#1<##1
1343 \else
1344 \ifnum"\mft@h#1>##2
1345 \else
1346 \char"\mft@h#1
1347 \fi
1348 \fi
1349 }%
1350 \mft@expanded@ranges
1351 \endgroup
1352 }
1353 % \end{macrocode}
1354 % \end{macro}
1355 %
1356 % \begin{macro}{\mft@char}
1357 % If a given number lies within any of the ranges listed in
1358 % |\mft@expanded@ranges|, output the corresponding character.
1359 % Otherwise, output nothing.
1360 % \begin{macrocode}
1361 \def\mft@char#1{%
1362 \begingroup
1363 \def\@elt##1|##2|{%
1364 \ifnum#1<##1
1365 \else
1366 \ifnum#1>##2
1367 \else
1368 \char#1
1369 \fi
1370 \fi
1371 }%
1372 \mft@expanded@ranges
1373 \endgroup
1374 }
1375 % \end{macrocode}
1376 % \end{macro}
1377 %
1378 %
1379 % \subsubsection{Table composition}
1380 %
1381 % Now that we've defined macros to parse |\fonttable|'s optional
1382 % argument, to process ranges of character codes, and to check for
1383 % numbers within ranges, we can finally proceed with defining
1384 % |\fonttable|, the macro that actually composes the font table.
1385 %
1386 % \begin{macro}{\mft@table@width}
1387 % |\mft@table@width| stores the width of the font table. Columns will
1388 % expand automatically to fill that width. If the specified width is
1389 % negative, |\fonttable| will instead use whatever column width is in
1390 % effect when |\fonttable| is invoked.
1391 % \begin{macrocode}
1392 \newlength{\mft@table@width}
1393 \setlength{\mft@table@width}{-1pt}
1394 % \end{macrocode}
1395 % \end{macro}
1396 %
1397 % \begin{macro}{\mft@expanded@ranges}
1398 % |\mft@expanded@ranges| stores a comma-separated list of hyphenated ranges.
1399 % The default is a single range, |0-65535|, which encompasses all character
1400 % positions.
1401 % \begin{macrocode}
1402 \def\mft@expanded@ranges{\@elt 0|65535|}
1403 % \end{macrocode}
1404 % \end{macro}
1405 %
1406 % \begin{macro}{\fonttable}
1407 % \begin{macro}{\mft@old@ranges}
1408 % \begin{macro}{\mft@old@expanded@ranges}
1409 % Display all the characters in a given font. The first (optional)
1410 % argument is a set of \meta{key}=\meta{value} pairs to specify the
1411 % table width and range of characters to output. The second (mandatory)
1412 % argument is the ``raw'' name of the font to use, e.g., |cmr10|.
1413 % \begin{macrocode}
1414 \DeclareRobustCommand{\fonttable}[2][]{%
1415 \begingroup
1416 \let\mft@old@ranges=\mft@ranges
1417 \let\mft@old@expanded@ranges=\mft@expanded@ranges
1418 \setkeys{mft}{#1}%
1419 \ifdim\mft@table@width<0pt
1420 \begin{minipage}{\linewidth}%
1421 \else
1422 \begin{minipage}{\mft@table@width}%
1423 \fi
1424 \font\testfont=#2\testfont
1425 % \end{macrocode}
1426 % \end{macro}
1427 % \end{macro}
1428 % \end{macro}
1429 % \begin{macro}{\mft@m}
1430 % \begin{macro}{\mft@n}
1431 % \begin{macro}{\mft@p}
1432 % \begin{macro}{\dim}
1433 % The first three of these were called |m|, |n|, and |p| in Knuth's code.
1434 % \begin{macrocode}
1435 \newcount\mft@m
1436 \newcount\mft@n
1437 \newcount\mft@p
1438 \newdimen\dim
1439 % \end{macrocode}
1440 % \end{macro}
1441 % \end{macro}
1442 % \end{macro}
1443 % \end{macro}
1444 % \begin{macro}{\oct}
1445 % Format an octal constant.
1446 % \begin{macrocode}
1447 \def\oct##1{\hbox{\rm\'{}\kern-.2em\it##1\/\kern.05em}}%
1448 % \end{macrocode}
1449 % \end{macro}
1450 % \begin{macro}{\hex}
1451 % Format a hexadecimal constant.
1452 % \begin{macrocode}
1453 \def\hex##1{\hbox{\rm\H{}\tt##1}}%
1454 % \end{macrocode}
1455 % \end{macro}
1456 % \begin{macro}{\setdigs}
1457 % \begin{macro}{\mft@h}
1458 % \begin{macro}{\mft@zero}
1459 % \begin{macro}{\mft@one}
1460 % |\mft@h| is the hex prefix. |\mft@zero\mft@one| is the corresponding
1461 % octal prefix. These were called |\h|, |\0|, and |\1| in Knuth's code.
1462 % \begin{macrocode}
1463 \def\setdigs##1"##2{\gdef\mft@h{##2}%
1464 \mft@m=\mft@n \divide\mft@m by 64 \xdef\mft@zero{\the\mft@m}%
1465 \multiply\mft@m by-64
1466 \advance\mft@m by\mft@n
1467 \divide\mft@m by 8
1468 \xdef\mft@one{\the\mft@m}}%
1469 % \end{macrocode}
1470 % \end{macro}
1471 % \end{macro}
1472 % \end{macro}
1473 % \end{macro}
1474 % \begin{macro}{\testrow}
1475 % Determine if a row is empty. |\mft@p|=1 if none of the characters
1476 % exist. Note that I modified the definition of |\\| to make use of
1477 % |\mft@check@char|.
1478 % \begin{macrocode}
1479 \def\testrow{\setbox0=\hbox{\penalty 1\let\\=\mft@check@char
1480 \\0\\1\\2\\3\\4\\5\\6\\7\\8\\9\\A\\B\\C\\D\\E\\F%
1481 \global\mft@p=\lastpenalty}} % \mft@p=1 if none of the characters exist
1482 % \end{macrocode}
1483 % \end{macro}
1484 % \begin{macro}{\oddline}
1485 % Draw an odd-numbered line.
1486 % \begin{macrocode}
1487 \def\oddline{\cr
1488 \noalign{\nointerlineskip}%
1489 \multispan{19}\hrulefill&
1490 \setbox0=\hbox{\lower 2.3pt\hbox{\hex{\mft@h x}}}\smash{\box0}\cr
1491 \noalign{\nointerlineskip}}%
1492 % \end{macrocode}
1493 % \end{macro}
1494 % \begin{macro}{\ifskipping}
1495 % Are we skipping empty rows?
1496 % \begin{macrocode}
1497 \newif\ifskipping
1498 % \end{macrocode}
1499 % \end{macro}
1500 % \begin{macro}{\evenline}
1501 % Draw an even-numbered line.
1502 % \begin{macrocode}
1503 \def\evenline{\loop\skippingfalse
1504 \ifnum\mft@n<256 \mft@m=\mft@n \divide\mft@m 16 \chardef\next=\mft@m
1505 \expandafter\setdigs\meaning\next \testrow
1506 \ifnum\mft@p=1 \skippingtrue \fi\fi
1507 \ifskipping \global\advance\mft@n 16 \repeat
1508 \ifnum\mft@n=256 \let\next=\endchart\else\let\next=\morechart\fi
1509 \next}%
1510 % \end{macrocode}
1511 % \end{macro}
1512 % \begin{macro}{\morechart}
1513 % \begin{macro}{\chartline}
1514 % \begin{macro}{\chartstrut}
1515 % Define a few more helper routines.
1516 % \begin{macrocode}
1517 \def\morechart{\cr\noalign{\hrule\penalty5000}%
1518 \chartline \oddline \mft@m=\mft@one \advance\mft@m 1
1519 \xdef\mft@one{\the\mft@m}%
1520 \chartline \evenline}%
1521 \def\chartline{&\oct{\mft@zero\mft@one x}%
1522 &&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&}%
1523 \def\chartstrut{\lower4.5pt\vbox to14pt{}}%
1524 % \end{macrocode}
1525 % \end{macro}
1526 % \end{macro}
1527 % \end{macro}
1528 % \begin{macro}{\table}
1529 % Draw the entire table. In |testfont.tex|, this was one of the
1530 % commands that a user would invoke at the \TeX\ prompt.
1531 % \begin{macrocode}
1532 \def\table{$$\global\mft@n=0
1533 \halign to\hsize\bgroup
1534 \chartstrut####\tabskip0pt plus10pt&
1535 &\hfil####\hfil&\vrule####\cr
1536 \lower6.5pt\null
1537 &&&\oct0&&\oct1&&\oct2&&\oct3&&\oct4&&\oct5&&\oct6&&\oct7&\evenline}%
1538 % \end{macrocode}
1539 % \end{macro}
1540 % \begin{macro}{\endchart}
1541 % Draw the last line of the table.
1542 % \begin{macrocode}
1543 \def\endchart{\cr\noalign{\hrule}%
1544 \raise11.5pt\null&&&\hex 8&&\hex 9&&\hex A&&\hex B&
1545 &\hex C&&\hex D&&\hex E&&\hex F&\cr\egroup$$\par}%
1546 \def\:{\setbox0=\hbox{\mft@char\mft@n}%
1547 \ifdim\ht0>7.5pt\reposition
1548 \else\ifdim\dp0>2.5pt\reposition\fi\fi
1549 \box0\global\advance\mft@n 1 }%
1550 % \end{macrocode}
1551 % \end{macro}
1552 % \begin{macro}{\reposition}
1553 % \begin{macro}{\centerlargechars}
1554 % Define a few more helper routines.
1555 % \begin{macrocode}
1556 \def\reposition{\setbox0=\vbox{\kern2pt\box0}\dim=\dp0
1557 \advance\dim 2pt \dp0=\dim}%
1558 \def\centerlargechars{
1559 \def\reposition{\setbox0=\hbox{$\vcenter{\kern2pt\box0\kern2pt}$}}}%
1560 % \end{macrocode}
1561 % \end{macro}
1562 % \end{macro}
1563 % Finally, we compose the table, finish off our |minipage|, and restore
1564 % the previous values of |\mft@ranges| and |\mft@expanded@ranges| (which
1565 % we had to save at the top of |\fonttable|, because |\@cons| contains
1566 % an |\xdef|). This concludes the definition of |\fonttable|.
1567 % \begin{macrocode}
1568 \table
1569 \end{minipage}%
1570 \global\let\mft@ranges=\mft@old@ranges
1571 \global\let\mft@expanded@ranges=\mft@old@expanded@ranges
1572 \endgroup
1573 }
1574 % \end{macrocode}
1575 %
1576 % \Finale
1577 \endinput