2 @setfilename web2c.info
3 @settitle Web2c: A @TeX{} implementation
6 \expandafter\ifx\csname url\endcsname\relax
7 \errhelp{You must update texinfo.tex to at least version 3.8.
8 The latest version is available from ftp://ftp.tug.org/tex/texinfo.tex.}
9 \errmessage{Your texinfo.tex is too old}
10 \csname bye\expandafter\endcsname
15 @set month-year May 2015
17 @c Define new indices for commands in auxiliary files, filenames, and options.
22 @c Put everything in one index (arbitrarily chosen to be the concept index).
33 * Web2c: (web2c). TeX, Metafont, and companion programs.
35 @dircategory Individual utilities
37 * bibtex: (web2c)bibtex invocation. Maintaining bibliographies.
38 * dvicopy: (web2c)dvicopy invocation. Virtual font expansion
39 * dvitomp: (web2c)dvitomp invocation. DVI to MPX (MetaPost pictures).
40 * dvitype: (web2c)dvitype invocation. DVI to human-readable text.
41 * gftodvi: (web2c)gftodvi invocation. Generic font proofsheets.
42 * gftopk: (web2c)gftopk invocation. Generic to packed fonts.
43 * gftype: (web2c)gftype invocation. GF to human-readable text.
44 * mf: (web2c)mf invocation. Creating typeface families.
45 * mft: (web2c)mft invocation. Prettyprinting Metafont source.
46 * mltex: (web2c)MLTeX. Multi-lingual TeX.
47 * mpost: (web2c)mpost invocation. Creating technical diagrams.
48 * patgen: (web2c)patgen invocation. Creating hyphenation patterns.
49 * pktogf: (web2c)pktogf invocation. Packed to generic fonts.
50 * pktype: (web2c)pktype invocation. PK to human-readable text.
51 * pltotf: (web2c)pltotf invocation. Property list to TFM.
52 * pooltype: (web2c)pooltype invocation. Display WEB pool files.
53 * tangle: (web2c)tangle invocation. WEB to Pascal.
54 * tex: (web2c)tex invocation. Typesetting.
55 * tftopl: (web2c)tftopl invocation. TFM -> property list.
56 * vftovp: (web2c)vftovp invocation. Virtual font -> virtual pl.
57 * vptovf: (web2c)vptovf invocation. Virtual pl -> virtual font.
58 * weave: (web2c)weave invocation. WEB to TeX.
62 This file documents the installation and use of the programs in Web2c,
63 an implementation of Donald Knuth's TeX system.
65 Copyright @copyright{} 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003,
66 2004, 2005, 2007, 2008, 2009 Karl Berry & Olaf Weber.
68 Permission is granted to make and distribute verbatim copies of this
69 manual provided the copyright notice and this permission notice are
70 preserved on all copies.
73 Permission is granted to process this file through TeX and print the
74 results, provided the printed document carries a copying permission
75 notice identical to this one except for the removal of this paragraph
76 (this paragraph not being relevant to the printed manual).
79 Permission is granted to copy and distribute modified versions of this
80 manual under the conditions for verbatim copying, provided that the
81 entire resulting derived work is distributed under the terms of a
82 permission notice identical to this one.
84 Permission is granted to copy and distribute translations of this manual
85 into another language, under the above conditions for modified versions,
86 except that this permission notice may be stated in a translation
93 @subtitle for version @value{version}
94 @subtitle @value{month-year}
97 @author @url{http://tug.org/web2c}
100 @vskip 0pt plus 1filll
110 This document describes how to install and use the programs in the Web2c
111 implementation of the @TeX{} system, especially for Unix systems. It
112 corresponds to Web2c version @value{version}, released in
116 * Introduction:: A brief introduction.
117 * Installation:: How to compile and install Web2c.
118 * Commonalities:: Option syntax, standard options, memory dumps.
120 * Metafont:: Typeface design.
121 * MetaPost:: Technical illustrations.
122 * BibTeX:: Reusable bibliographies.
123 * WEB:: Literate programming.
124 * DVI utilities:: DVI expansion.
125 * Font utilities:: Font format conversion.
126 * Legalisms:: Blah blah blah.
127 * References:: Books and such.
128 * Index:: General index.
134 @chapter Introduction
138 This manual corresponds to version @value{version} of Web2c, released in
141 @cindex Knuth, Donald E.
142 @cindex @TeX{}, Web2c implementation of
144 @cindex Breitenlohner, Peter
145 @dfn{Web2c} is the name of a @TeX{} implementation, originally for Unix,
146 but now also running under DOS, Amiga, and other operating systems. By
147 @dfn{@TeX{} implementation}, we mean all of the standard programs
148 developed by the Stanford @TeX{} project directed by Donald E. Knuth:
149 Metafont, DVItype, GFtoDVI, Bib@TeX{}, Tangle, etc., as well as @TeX{}
150 itself. Other programs are also included: DVIcopy, written by Peter
151 Breitenlohner, MetaPost and its utilities (derived from Metafont), by
154 @cindex translation from WEB to C
155 @cindex strategy, overall
156 General strategy: Web2c works, as its name implies, by translating the
157 WEB source in which @TeX{} is written into C source code. Its output is
158 not self-contained, however; it makes extensive use of many macros and
159 functions in a library (the @file{web2c/lib} directory in the sources).
160 Therefore, it will not work without change on an arbitrary WEB program.
162 @cindex licensing terms
163 @cindex freedom of Web2c
165 @cindex Henry, Patrick
166 Availability: All of Web2c is freely available---``free'' both in the
167 sense of no cost (free ice cream) and of having the source code to
168 modify and/or redistribute (free speech). @xref{unixtex.ftp,,,
169 kpathsea, Kpathsea}, for the practical details of how to obtain Web2c.
171 Different parts of the Web2c distribution have different licensing
172 terms, however, reflecting the different circumstances of their
173 creation; consult each source file for exact details. The main
174 practical implication for redistributors of Web2c is that the executables
175 are covered by the GNU General Public License, and therefore anyone
176 who gets a binary distribution must also get the sources, as explained
177 by the terms of the GPL (@pxref{Copying, , , kpathsea, Kpathsea}). The
178 GPL covers the Web2c executables, including @code{tex}, because the Free
179 Software Foundation sponsored the initial development of the Kpathsea
180 library that Web2c uses. The basic source files from Stanford, however,
181 have their own copyright terms or are in the public domain, and are not
185 @cindex Rokicki, Tomas
186 @cindex Trickey, Howard
187 @cindex Curtis, Pavel
191 History: Tomas Rokicki originated the @TeX{}-to-C system in 1987,
192 working from the first change files for @TeX{} under Unix, which were
193 done primarily by Howard Trickey and Pavel Curtis. Tim Morgan then took
194 over development and maintenance for a number of years; the name changed
195 to Web-to-C somewhere in there. In 1990, Karl Berry became the
196 maintainer. He made many changes to the original sources, and started
197 using the shorter name Web2c. In 1997, Olaf Weber took over. Dozens of
198 other people have contributed; their names are listed in the
199 @file{ChangeLog} files.
201 @cindex acknowledgements
204 @cindex Stallman, Richard
205 Other acknowledgements: The University of Massachusetts at Boston
206 (particularly Rick Martin and Bob Morris) provided computers and ftp
207 access to me for many years. Richard Stallman at the Free Software
208 Foundation employed me while I wrote the original path searching library
209 (for the GNU font utilities). (rms also gave us Emacs, GDB, and GCC,
210 without which I cannot imagine developing Web2c.) And, of course,
211 @TeX{} would not exist in the first place without Donald E. Knuth.
213 @cindex reading, additional
214 Further reading: @xref{References}.
217 @include install.texi
221 @chapter Commonalities
223 @cindex commonalities
225 Many aspects of the @TeX{} system are the same among more than one
226 program, so we describe all those pieces together, here.
229 * Option conventions:: -- or -, = or ` ' for values.
230 * Common options:: --help --version --verbose, and TeX/MF/MP options.
231 * Path searching:: Features of the common path searching library.
232 * Output file location:: TEXMFOUTPUT allows output in places other than `.'.
233 * Three programs:: TeX, Metafont, and MetaPost have a lot in common.
237 @node Option conventions
238 @section Option conventions
240 @cindex option conventions
241 @cindex conventions for options,
243 @findex getopt_long_only
244 To provide a clean and consistent behavior, we chose to have all these
245 programs use the GNU function @code{getopt_long_only} to parse command
246 lines. However, we do use in a restricted mode, where all the options
247 have to come before the rest of the arguments.
249 @opindex - @r{starts option names}
250 @opindex -- @r{starts option names}
251 As a result, you can:
254 use @samp{-} or @samp{--} to start an option name;
257 use any unambiguous abbreviation for an option name;
260 separate option names and values with either @samp{=} or one or more
264 @flindex - @r{starting a filename}
265 @cindex filenames starting with @samp{-}
266 use filenames that would otherwise look like options by putting them
267 after an option @samp{--}.
270 By convention, non-option arguments, if specified, generally define the
271 name of an input file, as documented for each program.
273 If a particular option with a value is given more than once, it is the
274 last value that counts.
276 For example, the following command line specifies the options
277 @samp{foo}, @samp{bar}, and @samp{verbose}; gives the value @samp{baz}
278 to the @samp{abc} option, and the value @samp{xyz} to the @samp{quux}
279 option; and specifies the filename @file{-myfile-}.
282 -foo --bar -verb -abc=baz -quux karl --quux xyz -- -myfile-
287 @section Common options
289 @cindex common options
290 All of these programs accept the standard GNU @samp{--help} and
291 @samp{--version} options, and several programs accept
292 @samp{--verbose}. Rather than writing identical descriptions for
293 every program, they are described here.
297 @opindex --help @r{common option}
299 Print a usage message listing basic usage and all available options to
300 standard output, then exit successfully.
303 @opindex --verbose @r{common option}
304 @cindex verbosity, enabling
305 Print progress reports to standard output.
308 @opindex --version @r{common option}
309 @cindex version number, finding
310 Print the version number to standard output, then exit successfully.
313 @TeX{}, Metafont, and MetaPost have a number of additional options in
317 @item -file-line-error
318 @opindex -file-line-error
319 @itemx -no-file-line-error
320 @opindex -no-file-line-error
321 @opindex -file-line-error-style
322 @cindex changing error messages style
323 Change (or do not change) the way error messages are printed. The
324 alternate style looks like error messages from many compilers and is
325 easier to parse for some editors that invoke @TeX{}. This option used
326 to be called @samp{-file-line-error-style}.
328 @item -fmt=@var{dumpname}
329 @itemx -base=@var{dumpname}
330 @itemx -mem=@var{dumpname}
331 @opindex -fmt=@var{dumpname}
332 @opindex -base=@var{dumpname}
333 @opindex -mem=@var{dumpname}
335 Use @var{dumpname} instead of the program name or a @samp{%&} line to
336 determine the name of the memory dump file read (@samp{fmt} for @TeX{},
337 @samp{base} for Metafont, @samp{mem} for MetaPost). @xref{Memory
338 dumps}. Also sets the program name to @var{dumpname} if no
339 @samp{-progname} option was given.
342 @opindex -halt-on-error
343 @cindex stopping at the first error
344 Stop processing and exit when an error occurs, as opposed to the normal
345 process of trying to recover and continue.
349 @cindex program names, special
350 @cindex initial form, enabling
351 Enable the ``initial'' form of the program (@pxref{Initial and
352 virgin}). This is implicitly set if the program name is @code{initex}
353 resp.@: @code{inimf}.
355 @item -interaction=@var{string}
356 @opindex -interaction=@var{string}
357 @cindex interaction mode
358 Set the interaction mode from the command line. The @var{string} must
359 be one of @samp{batchmode}, @samp{nonstopmode}, @samp{scrollmode}, or
360 @samp{errorstopmode}.
362 @item -jobname=@var{string}
363 @opindex -jobname=@var{string}
365 Set the job name to @var{string}, instead of deriving it from the name
368 @item -kpathsea-debug=@var{number}
369 @opindex -kpathsea-debug=@var{number}
370 @vindex KPATHSEA_DEBUG
371 @cindex debugging flags, specifying
372 @cindex path searching debugging
373 Set path searching debugging flags according to the bits of @var{number}
374 (@pxref{Debugging,,,kpathsea,Kpathsea}). You can also specify this in
375 @code{KPATHSEA_DEBUG} environment variable (for all Web2c programs).
376 (The command line value overrides.) The most useful value is @samp{-1},
377 to get all available output.
379 @item -output-directory=@var{dirname}
380 @opindex -output-directory
381 @cindex output directory, specifying
382 Specify the directory @var{dirname} to which output files are written.
383 Also look for input files in @var{dirname} first, before looking along
384 the normal search path. @xref{Output file location}.
386 @item -parse-first-line
387 @opindex -parse-first-line
388 @itemx -no-parse-first-line
389 @opindex -no-parse-first-line
390 @cindex parsing the first line
391 Check or disable checking whether the first line of the main input
392 file starts with @samp{%&}, and parse it if it does. This line can be
393 used specify the format and/or a TCX file.
395 @item -progname=@var{string}
396 @opindex -progname=@var{string}
397 @cindex binaries, linking
398 @cindex linking binaries
399 @cindex program names, special
400 Set program (and memory dump) name to @var{string}. This may affect the
401 search paths and other values used (@pxref{Config files,,, kpathsea,
402 Kpathsea}). Using this option is equivalent to making a link named
403 @var{string} to the binary and then invoking the binary under that
404 name. @xref{Memory dumps}.
408 @cindex file recorder
409 Enable the filename recorder. This makes the program save a list of the
410 opened files into a file with (by default) extension @samp{.fls}. For
411 Aleph, this option is always on, and the file has extension @samp{.ofl}.
413 Ordinarily, the @samp{.fls} file is written to the same location as
414 the @samp{.log} file, for example, respecting
415 @option{-output-directory} if it is given (@pxref{Output file
416 location}). However, if @TeX{} processing is done on the command line
417 (or in response to the @samp{**} prompt), the @samp{.fls} might be
418 written to the current directory, or include an integer (the current
419 pid), as in @file{texput1234.fls}. You can use @option{-jobname} to
420 explicitly set the basename.
422 @item -translate-file=@var{tcxfile}
423 @opindex -translate-file=@var{tcxfile}
424 @cindex translation file for @TeX{}, specifying
425 @flindex .tcx @r{character translation files}
426 @cindex first line of the main input file
427 Use @var{tcxfile} to define which characters are printable and translations
428 between the internal and external character sets. Moreover,
429 @var{tcxfile} can be explicitly declared in the first line of the main
430 input file @samp{%& -translate-file=@var{tcxfile}}.
431 This is the recommended method for portability reasons.
437 @flindex 8 bit clean output, specifying
438 This option specifies that by default all characters should be
439 considered printable. If @samp{-translate-file} was given as well, then the
440 TCX file may mark characters as non-printable.
446 @section Path searching
448 @cindex path searching
451 @cindex configuration file reading
452 All of the Web2c programs, including @TeX{}, which do path searching use
453 the Kpathsea routines to do so. The precise names of the environment
454 and configuration file variables which get searched for particular file
455 formatted are therefore documented in the Kpathsea manual
456 (@pxref{Supported file formats,,, kpathsea, Kpathsea}). Reading
457 @file{texmf.cnf} (@pxref{Config files,,, kpathsea, Kpathsea}), invoking
458 @code{mktex@dots{}} scripts (@pxref{mktex scripts,,, kpathsea,
459 Kpathsea}), and so on are all handled by Kpathsea.
462 @cindex aliases for fonts
463 @flindex texfonts.map
464 The programs which read fonts make use of another Kpathsea feature:
465 @file{texfonts.map}, which allows arbitrary aliases for the actual names
466 of font files; for example, @samp{Times-Roman} for @samp{ptmr8r.tfm}.
467 The distributed (and installed by default) @file{texfonts.map} includes
468 aliases for many widely available PostScript fonts by their PostScript
472 @node Output file location
473 @section Output file location
475 @cindex output file location
476 @cindex current directory, used for output
477 @flindex .@r{, used for output}
478 All the programs generally follow the usual convention for output files.
479 Namely, they are placed in the directory current when the program is
480 run, regardless of any input file location; or, in a few cases, output
481 is to standard output.
483 For example, if you run @samp{tex /tmp/foo}, for example, the output
484 will be in @file{./foo.dvi} and @file{./foo.log}, not
485 @file{/tmp/foo.dvi} and @file{/tmp/foo.log}.
487 @opindex -output-directory
488 @cindex output directory, specifying
489 @cindex readonly directory, running @TeX{} in
490 You can use the @samp{-output-directory} option to cause all output
491 files that would normally be written in the current directory to be
492 written in the specified directory instead. @xref{Common options}.
494 @vindex TEXMFOUTPUT@r{, used if @samp{.} unwritable}
495 @cindex readonly directory, running @TeX{} in
496 If the current directory is not writable, and @samp{-output-directory}
497 is not specified, the main programs (@TeX{}, Metafont, MetaPost, and
498 Bib@TeX{}) make an exception: if the config file or environment
499 variable value @code{TEXMFOUTPUT} is set (it is not by default),
500 output files are written to the directory specified.
502 @vindex TEXMFOUTPUT@r{, used for reading}
503 @code{TEXMFOUTPUT} is also checked for input files, as @TeX{} often
504 generates files that need to be subsequently read; for input, no
505 suffixes (such as @samp{.tex}) are added by default and no exhaustive
506 path searching is done, the input name is
507 simply checked as given.
511 @section Three programs: Metafont, MetaPost, and @TeX{}
513 @cindex three programs
514 @cindex @TeX{}, Metafont, and MetaPost
515 @cindex Metafont, MetaPost, and @TeX{}
516 @cindex MetaPost, @TeX{}, and Metafont
518 @TeX{}, Metafont, and MetaPost have a number of features in common.
519 Besides the ones here, the common command-line options are described in
520 the previous section. The configuration file options that let you
521 control some array sizes and other features are described in
522 @ref{Runtime options}.
525 * Initial and virgin:: Making memory dumps vs. production runs.
526 * Memory dumps:: .fmt/.base files for fast startup.
527 * Editor invocation:: The `e' response at errors.
528 * \input filenames:: ~ and $ expansion in TeX/MF/MP.
532 @node Initial and virgin
533 @subsection Initial and virgin
535 @cindex executables, shared initial and virgin
536 The @TeX{} and Metafont programs each have two main variants, called
537 @dfn{initial} and @dfn{virgin}. MetaPost no longer makes this
540 The initial form is enabled if:
544 the @samp{-ini} option was specified; or
546 the program name is @file{initex} resp.@: @file{inimf}; or
548 the first line of the main input file is @samp{%&ini};
551 otherwise, the virgin form is used.
553 @cindex virgin programs
554 @cindex production use
555 The @dfn{virgin} form is the one generally invoked for production use.
556 The first thing it does is read a memory dump (@pxref{Determining the
557 memory dump to use}), and then proceeds on with the main job.
559 @cindex initial programs
560 @cindex initializations, lengthy
561 The @dfn{initial} form is generally used only to create memory dumps
562 (see the next section). It starts up more slowly than the virgin form,
563 because it must do lengthy initializations that are encapsulated in the
568 @subsection Memory dumps
572 @cindex dumping memory
573 @cindex macros, predefining in memory dumps
574 @cindex predefined macros and memory dumps
575 In typical use, @TeX{} and Metafont require a large number of
576 macros to be predefined; therefore, they support @dfn{memory dump}
577 files, which can be read much more efficiently than ordinary source
581 * Creating memory dumps::
582 * Determining the memory dump to use::
583 * Hardware and memory dumps::
587 @node Creating memory dumps
588 @subsubsection Creating memory dumps
590 @cindex memory dumps, creating
591 @cindex creating memory dumps
592 @cindex writing memory dumps
594 The programs all create memory dumps in slightly idiosyncratic (thought
595 substantially similar) way, so we describe the details in separate
596 sections (references below). The basic idea is to run the initial
597 version of the program (@pxref{Initial and virgin}), read the source
598 file to define the macros, and then execute the @code{\dump} primitive.
600 Also, each program uses a different filename extension for its memory
601 dumps, since although they are completely analogous they are not
602 interchangeable (@TeX{} cannot read a Metafont memory dump, for
605 Here is a list of filename extensions with references to examples of
606 creating memory dumps:
610 (@samp{.fmt}) @xref{Initial TeX,,Initial @TeX{}}.
613 (@samp{.base}) @xref{Initial Metafont}.
616 When making memory dumps, the programs read environment variables and
617 configuration files for path searching and other values as usual. If
618 you are making a new installation and have environment variables
619 pointing to an old one, for example, you will probably run into
623 @node Determining the memory dump to use
624 @subsubsection Determining the memory dump to use
626 @cindex memory dump to use, determining
627 @cindex fmt file, determining
628 @cindex base file, determining
629 @cindex mem file, determining
631 The virgin form (@pxref{Initial and virgin}) of each program always
632 reads a memory dump before processing normal source input. All three
633 programs determine the memory dump to use in the same way:
637 If the first non-option command-line argument begins with @samp{&}, the
638 program uses the remainder of that argument as the memory dump name.
639 For example, running @samp{tex \&super} reads @file{super.fmt}. (The
640 backslash protects the @samp{&} against interpretation by the shell.)
643 @opindex -fmt=@var{fmt}
644 @opindex -base=@var{base}
645 If the @samp{-fmt} resp.@: @samp{-base} option is
646 specified, its value is used.
649 @opindex -progname=@var{string}
650 If the @samp{-progname} option is specified, its value is used.
653 @kindex %& @r{magic number}
654 If the first line of the main input file (which must be specified on the
655 command line, not in response to @samp{**}) is @code{%&@var{dump}}, and
656 @var{dump} is an existing memory dump of the appropriate type,
659 The first line of the main input file can also specify which character
660 translation file is to be used: @code{%&-translate-file=@var{tcxfile}}
663 These two roles can be combined: @code{%&@var{dump}
664 -translate-file=@var{tcxfile}}. If this is done, the name of the dump
668 @cindex program name, determines memory dump
669 @cindex links to binaries
670 Otherwise, the program uses the program invocation name, most commonly
671 @file{tex} resp.@: @file{mf}. For example, if @file{latex} is a link
672 to @file{tex}, and the user runs @samp{latex foo}, @file{latex.fmt}
678 @node Hardware and memory dumps
679 @subsubsection Hardware and memory dumps
681 @cindex hardware and memory dumps
682 @cindex memory dumps and hardware
683 @cindex sharing memory dumps
684 @cindex fmt files, sharing
685 @cindex base files, sharing
686 @cindex mem files, sharing
688 @cindex LittleEndian machines
689 @cindex BigEndian machines
690 @cindex endian dependencies
691 @cindex machine dependencies
692 @cindex architecture dependencies
693 @cindex dependencies, hardware
694 @opindex --disable-dump-share configure @r{option}
695 By default, memory dump files are generally sharable between
696 architectures of different types; specifically, on machines of different
697 endianness (@pxref{Byte order,,,libc,GNU C Library}). (This is a
698 feature of the Web2c implementation, and is not true of all @TeX{}
699 implementations.) If you specify @samp{--disable-dump-share} to
700 @code{configure}, however, memory dumps will be endian-dependent.
702 @cindex byte swapping
703 @cindex swapping bytes
704 The reason to do this is speed. To achieve endian-independence, the
705 reading of memory dumps on LittleEndian architectures, such as PC's and
706 DEC architectures, is somewhat slowed (all the multibyte values have to
707 be swapped). Usually, this is not noticeable, and the advantage of
708 being able to share memory dumps across all platforms at a site far
709 outweighs the speed loss. But if you're installing Web2c for use on
710 LittleEndian machines only, perhaps on a PC being used only by you, you
711 may wish to get maximum speed.
713 @cindex floating-point values
714 @cindex glue ratio representations
715 @TeX{}nically, even without @samp{--disable-dump-share}, sharing of
716 @file{.fmt} files cannot be guaranteed to work. Floating-point values
717 are always written in native format, and hence will generally not be
718 readable across platforms. Fortunately, @TeX{} uses floating point
719 only to represent glue ratios, and all common formats (plain,
720 @LaTeX{}, AMS@TeX{}, @dots{}) do not do any glue setting at
721 @file{.fmt}-creation time. Metafont does not use floating point in
722 any dumped value at all.
724 @cindex date and time, in memory dumps
725 @cindex time and date, in memory dumps
726 @cindex memory dumps, contain date and time
727 Incidentally, different memory dump files will never compare equal
728 byte-for-byte, because the program always dumps the current date and
729 time. So don't be alarmed by just a few bytes difference.
731 @cindex Harbison, Samuel P.
732 @cindex Steele Jr., Guy L.
733 If you don't know what endianness your machine is, and you're curious,
734 here is a little C program to tell you. (The @code{configure} script
735 contains a similar program.) This is from the book @cite{C: A Reference
736 Manual}, by Samuel P. Harbison and Guy L. Steele
737 Jr@:. (@pxref{References}).
742 /* Are we little or big endian? From Harbison&Steele. */
746 char c[sizeof (long)];
750 printf ("LittleEndian\n");
751 else if (u.c[sizeof (long) - 1] == 1)
752 printf ("BigEndian\n");
754 printf ("unknownEndian");
756 exit (u.c[sizeof (long) - 1] == 1);
761 @node Editor invocation
762 @subsection Editor invocation
764 @cindex editor invoked at error
765 @cindex errors, editor invoked at
766 @opindex e @r{response at error prompt}
768 @TeX{}, Metafont, and MetaPost all (by default) stop and ask for user
769 intervention at an error. If the input came from a file, and the user
770 responds with @kbd{e} or @kbd{E}, the program invokes an editor.
775 @opindex --with-editor=@var{cmd}
776 Specifying @samp{--with-editor=@var{cmd}} to @code{configure} sets the
777 default editor command string to @var{cmd}. The environment
778 variables/configuration values @code{TEXEDIT}, @code{MFEDIT}, and
779 @code{MPEDIT} (respectively) override this. If @samp{--with-editor} is
780 not specified, the default is @code{vi +%d %s} on Unix, and an
781 invocation of the @TeX{}works editor on Windows. (See
782 @file{texmf.cnf} for the precise values.)
784 In this string, @samp{%d} is replaced by the line number of the error,
785 and @samp{%s} is replaced by the name of the current input file.
788 @node \input filenames
789 @subsection @code{\input} filenames
791 @cindex input filenames
792 @cindex filename conventions, in input files
793 @findex \input @r{filenames}
795 @TeX{}, Metafont, and MetaPost source programs can all read other source
796 files with the @code{\input} (@TeX{}) and @code{input} (MF and MP)
799 \input @var{name} % in TeX
802 @cindex space-terminated filenames
803 @cindex whitespace-terminated filenames
804 @cindex terminator for filenames
805 The file @var{name} can always be terminated with whitespace; for
806 Metafont and MetaPost, the statement terminator @samp{;} also works.
807 (@LaTeX{} and other macro packages provide other interfaces to
808 @code{\input} that allow different notation; here we are concerned only
809 with the primitive operation.)
811 As of Web2c version 7.5.3, double-quote characters can be used to
812 include spaces or other special cases. In typical use, the @samp{"}
813 characters surround the entire filename:
815 \input "filename with spaces"
818 Technically, the quote characters can be used inside the name, and
819 can enclose any characters, as in:
821 \input filename" "with" "spaces
824 One more point. In @LaTeX{}, the quotes are needed inside the braces, thus
826 \input@{a b@} % fails
830 This quoting mechanism comes into play @emph{after} @TeX{} has
831 tokenized and expanded the input. So, multiple spaces and tabs may be
832 seen as a single space, active characters such as @samp{~} are
833 expanded first, and so on. (See below.)
835 @cindex NUL, not allowed in filenames
836 @cindex eight-bit characters in filenames
837 @cindex meta characters in filenames
838 On the other hand, various C library routines and Unix itself use the null
839 byte (character code zero, ASCII NUL) to terminate strings. So
840 filenames in Web2c cannot contain nulls, even though @TeX{} itself does
841 not treat NUL specially.
842 In addition, some older Unix variants do not allow eight-bit characters
843 (codes 128--255) in filenames.
845 @cindex portable filenames
846 For maximal portability of your document across systems, use only the
847 characters @samp{a}--@samp{z}, @samp{0}--@samp{9}, and @samp{.}, and
848 restrict your filenames to at most eight characters (not including the
849 extension), and at most a three-character extension. Do not use
850 anything but simple filenames, since directory separators vary among
851 systems; instead, add the necessary directories to the appropriate
854 @kindex ~ @r{expansion in filenames}
855 @kindex $ @r{expansion in filenames}
856 Finally, the present Web2c implementation does @samp{~} and @samp{$}
857 expansion on @var{name}, unlike Knuth's original implementation and
858 older versions of Web2c. Thus:
860 \input ~jsmith/$foo.bar
862 will dereference the environment variable or Kpathsea config file value
863 @samp{foo} and read that file extended with @samp{.bar} in user
864 @samp{jsmith}'s home directory. You can also use braces, as in
865 @samp{$@{foo@}bar}, if you want to follow the variable name with a letter,
866 numeral, or @samp{_}.
868 (So another way to get a program to read a filename containing
869 whitespace is to define an environment variable and dereference it.)
872 In all the common @TeX{} formats (plain @TeX{}, @LaTeX{}, AMS@TeX{}),
873 the characters @samp{~} and @samp{$} have special category codes, so to
874 actually use these in a document you have to change their catcodes or
875 use @code{\string}. (The result is unportable anyway, see the
876 suggestions above.) The place where they are most likely to be useful
877 is when typing interactively.
881 @chapter @TeX{}: Typesetting
883 @cindex @TeX{}, description of
885 @cindex mathematical typesetting
887 @TeX{} is a typesetting system: it was especially designed to handle
888 complex mathematics, as well as most ordinary text typesetting.
890 @cindex batch languages
891 @cindex word processor, not
892 @TeX{} is a batch language, like C or Pascal, and not an interactive
893 ``word processor'': you compile a @TeX{} input file into a corresponding
894 device-independent (DVI) file (and then translate the DVI file to the
895 commands for a particular output device). This approach has both
896 considerable disadvantages and considerable advantages. For a complete
897 description of the @TeX{} language, see @cite{The @TeX{}book}
898 (@pxref{References}). Many other books on @TeX{}, introductory and
899 otherwise, are available.
902 * tex invocation:: Invoking TeX.
903 * Initial TeX:: Making format files.
904 * Formats:: Major TeX macro packages.
905 * Languages and hyphenation:: TeX supports many human languages.
906 * Shell escapes:: Running subprograms from TeX.
907 * IPC and TeX:: DVI output to a socket.
908 * TeX extensions:: Changes to the TeX language.
913 @section @code{tex} invocation
916 @cindex @TeX{}, invocation
918 @TeX{} (usually invoked as @code{tex}) formats the given text and
919 commands, and outputs a corresponding device-independent representation
920 of the typeset document. This section merely describes the options
921 available in the Web2c implementation. For a complete description of
922 the @TeX{} typesetting language, see @cite{The @TeX{}book}
923 (@pxref{References}).
925 @TeX{}, Metafont, and MetaPost process the command line (described
926 here) and determine their memory dump (fmt) file in the same way
927 (@pxref{Memory dumps}). Synopses:
930 tex [@var{option}]@dots{} [@var{texname}[.tex]] [@var{tex-commands}]
931 tex [@var{option}]@dots{} \@var{first-line}
932 tex [@var{option}]@dots{} &@var{fmt} @var{args}
936 @cindex @TeX{}, input files found
937 @TeX{} searches the usual places for the main input file @var{texname}
938 (@pxref{Supported file formats,,, kpathsea, Kpathsea}), extending
939 @var{texname} with @file{.tex} if necessary. To see all the
940 relevant paths, set the environment variable @code{KPATHSEA_DEBUG} to
941 @samp{-1} before running the program.
943 After @var{texname} is read, @TeX{} processes any remaining
944 @var{tex-commands} on the command line as regular @TeX{} input. Also,
945 if the first non-option argument begins with a @TeX{} escape character
946 (usually @code{\}), @TeX{} processes all non-option command-line
947 arguments as a line of regular @TeX{} input.
949 If no arguments or options are specified, @TeX{} prompts for an
950 input file name with @samp{**}.
953 @TeX{} writes the main DVI output to the file
954 @file{@var{basetexname}.dvi}, where @var{basetexname} is the basename of
955 @var{texname}, or @samp{texput} if no input file was specified. A DVI
956 file is a device-independent binary representation of your @TeX{}
957 document. The idea is that after running @TeX{}, you translate the DVI
958 file using a separate program to the commands for a particular output
959 device, such as a PostScript printer
960 (@pxref{Top,,Introduction,dvips,Dvips}) or an X Window System display
964 @pindex mktextfM@r{, disabling}
965 @findex \font @r{and dynamic generation}
966 @TeX{} also reads TFM files for any fonts you load in your document with
967 the @code{\font} primitive. By default, it runs an external program
968 named @file{mktextfm} to create any nonexistent TFM files. You can
969 disable this at configure-time or runtime (@pxref{mktex
970 configuration,,, kpathsea, Kpathsea}). This is enabled mostly for the
971 sake of the EC fonts, which can be generated at any size.
973 @findex \openout @r{and security}
974 @cindex security, and @code{\openout}
975 @cindex output files, written by @TeX{} programs
976 @cindex Trojan horses and @TeX{} programs
977 @cindex dot files, written by @TeX{} programs
978 @cindex security, and output files
979 @TeX{} can write output files, via the @code{\openout} primitive; this opens
980 a security hole vulnerable to Trojan horse attack: an unwitting user could
981 run a @TeX{} program that overwrites, say, @file{~/.rhosts}. (MetaPost has
982 a @code{write} primitive with similar implications). To alleviate this and
983 similar problems the functions @code{kpathsea_out_name_ok} and
984 @code{kpathsea_in_name_ok} from the Kpathse library (@pxref{Calling
985 sequence,,, kpathsea, Kpathsea}) are used to determine if a given filename
986 is acceptable to be opened for output or input, depending on the setting of
987 the configuration variables @code{openout_any} and @code{openin_any}:
988 @samp{a} (for ``any'', the default for @code{openin_any}), @samp{r} (for
989 ``restricted''), or @samp{p} (for ``paranoid'', the default for
992 In any case, all @code{\openout} filenames are recorded in the log file,
993 except those opened on the first line of input, which is processed when
994 the log file has not yet been opened.
996 The program accepts the following options, as well as the standard
997 @samp{-help} and @samp{-version} (@pxref{Common options}):
1000 @itemx -[no]-file-line-error
1001 @itemx -fmt=@var{fmtname}
1002 @itemx -halt-on-error
1004 @itemx -interaction=@var{string}
1007 @itemx -jobname=@var{string}
1008 @itemx -kpathsea-debug=@var{number}
1009 @itemx -[no]parse-first-line
1010 @itemx -output-directory
1011 @itemx -progname=@var{string}
1013 @itemx -translate-file=@var{tcxfile}
1015 These options are common to @TeX{}, Metafont, and MetaPost.
1016 @xref{Common options}.
1020 @cindex Unicode input
1022 Enable enc@TeX{} extensions, such as @code{\mubyte}. This can be used
1023 to support Unicode UTF-8 input encoding. See
1024 @url{http://www.olsak.net/enctex.html}.
1030 @opindex --enable-ipc configure @r{option}
1031 With either option, @TeX{} writes its DVI output to a socket as well as
1032 to the usual @file{.dvi} file. With @samp{-ipc-start}, @TeX{} also
1033 opens a server program at the other end to read the output. @xref{IPC
1034 and TeX,,IPC and @TeX{}}.
1036 These options are available only if the @samp{--enable-ipc} option was
1037 specified to @code{configure} during installation of Web2c.
1039 @item -mktex=@var{filetype}
1040 @itemx -no-mktex=@var{filetype}
1041 @opindex -mktex=@var{filetype}
1042 @opindex -no-mktex=@var{filetype}
1043 Turn on or off the @samp{mktex} script associated with @var{filetype}.
1044 For @TeX{} proper, @var{filetype} can only be @samp{tex} and
1045 @samp{tfm}, but for pdf@TeX{} and lua@TeX{}, it can also be @samp{pk}.
1049 @cindex ML@TeX{}, enabling
1050 @cindex program names, special
1051 If we are @code{INITEX} (@pxref{Initial and virgin}), enable ML@TeX{}
1052 extensions such as @code{\charsubdef}. Implicitly set if the program
1053 name is @code{mltex}. @xref{MLTeX,,ML@TeX{}}.
1055 @item -output-comment=@var{string}
1056 @opindex -output-comment=@var{string}
1057 @vindex output_comment @r{for DVI files}
1058 @cindex DVI comment, specifying
1059 @cindex regression testing
1060 Use @var{string} as the DVI file comment. Ordinarily, this comment
1061 records the date and time of the @TeX{} run, but if you are doing
1062 regression testing, you may not want the DVI file to have this spurious
1063 difference. This is also taken from the environment variable and
1064 config file value @samp{output_comment}.
1067 @opindex -shell-escape
1068 @itemx -no-shell-escape
1069 @opindex -no-shell-escape
1070 @itemx -shell-restricted
1071 @opindex -shell-restricted
1072 Enable, or disable, or enable with restrictions the
1073 @code{\write18@{@var{shell-command}@}} feature for external executing
1074 shell commands. @xref{Shell escapes}.
1076 @item -enable-write18
1077 @opindex -enable-write18
1078 @itemx -disable-write18
1079 @opindex -disable-write18
1080 Synonyms for @option{-shell-escape} and @option{-no-shell-escape}, for
1081 compatibility with MiK@TeX{}. (MiK@TeX{} also accepts both pairs of
1082 options.) @xref{Shell escapes}.
1085 @itemx -src-specials=@var{string}
1086 @cindex generating source specials
1087 This option makes @TeX{} output specific source information using
1088 @samp{\special} commands in the DVI file. These @samp{\special} track
1089 the current file name and line number.
1091 Using the first form of this option, the @samp{\special} commands are
1092 inserted automatically.
1094 In the second form of the option, @var{string} is
1095 a comma separated list of the following values: @samp{cr},
1096 @samp{display}, @samp{hbox}, @samp{math}, @samp{par}, @samp{parend},
1097 @samp{vbox}. You can use this list to specify where you want @TeX{} to
1098 output such commands. For example, @samp{-src-specials=cr,math} will
1099 output source information every line and every math formula.
1101 These commands can be used with the appropriate DVI viewer and text
1102 editor to switch from the current position in the editor to the same
1103 position in the viewer and back from the viewer
1106 This option works by inserting @samp{\special} commands into the token
1107 stream, and thus in principle these additional tokens can be recovered
1108 or seen by the tricky-enough macros. If you run across a case, let us
1109 know, because this counts as a bug. However, such bugs are very hard
1110 to fix, requiring significant changes to @TeX{}, so please don't count
1113 Redefining @samp{\special} will not affect the functioning of this
1114 option. The commands inserted into the token stream are
1115 hard-coded to always use the @samp{\special} primitive.
1117 @TeX{} does not pass the trip test when this option is enabled.
1123 @section Initial @TeX{}
1125 @cindex initial @TeX{}
1126 @cindex @TeX{}, initial
1130 The @dfn{initial} form of @TeX{} is invoked by @samp{tex -ini}. It
1131 does lengthy initializations avoided by the ``virgin'' (@code{vir})
1132 form, so as to be capable of dumping @samp{.fmt} files (@pxref{Memory
1133 dumps}). For a detailed comparison of virgin and initial forms,
1134 @pxref{Initial and virgin}.
1136 For a list of options and other information, @pxref{tex invocation}.
1140 @cindex format files
1141 Unlike Metafont and MetaPost, many format files are commonly used with
1142 @TeX{}. The standard one implementing the features described in the
1143 @cite{@TeX{}book} is @samp{plain.fmt}, also known as @samp{tex.fmt}
1144 (again, @pxref{Memory dumps}). It is created by default during
1145 installation, but you can also do so by hand if necessary (e.g., if an
1146 update to @file{plain.tex} is issued):
1148 tex -ini '\input plain \dump'
1151 (The quotes prevent interpretation of the backslashes from the shell.)
1152 Then install the resulting @file{plain.fmt} in @samp{$(fmtdir)}
1153 (@file{/usr/local/share/texmf/web2c} by default), and link
1154 @file{tex.fmt} to it.
1156 The necessary invocation for generating a format file differs for each
1157 format, so instructions that come with the format should explain. The
1158 top-level @file{web2c} Makefile has targets for making most common
1159 formats: @t{plain latex amstex texinfo eplain}. @xref{Formats}, for
1160 more details on @TeX{} formats.
1166 @cindex formats for @TeX{}
1167 @cindex @TeX{}, format packages for
1168 @cindex macro packages, major @TeX{}
1170 @TeX{} @dfn{formats} are large collections of macros, often dumped
1171 into a @file{.fmt} file (@pxref{Memory dumps}) by @code{tex -ini}
1172 (@pxref{Initial TeX}). A number of formats are in reasonably
1173 widespread use, and the Web2c Makefile has targets to make the versions
1174 current at the time of release. You can change which formats are
1175 automatically built by setting the @code{fmts} Make variable; by default,
1176 only the @samp{plain} and @samp{latex} formats are made.
1178 You can get the latest versions of most of these formats from the CTAN
1179 archives in subdirectories of @file{@var{CTAN:}/macros} (for CTAN info,
1180 @pxref{unixtex.ftp,,, kpathsea, Kpathsea}). The archive
1181 @url{ftp://ftp.tug.org/tex/lib.tar.gz} (also available from CTAN)
1182 contains most of these formats (although perhaps not the absolute latest
1183 version), among other things.
1188 The most widely used format. The current release is named `@LaTeX{}
1189 2e'; new versions are released approximately every six months, with
1190 patches issued as needed. The old release was called `@LaTeX{} 2.09',
1191 and is no longer maintained or supported. @LaTeX{} attempts to provide
1192 generic markup instructions, such as ``emphasize'', instead of specific
1193 typesetting instructions, such as ``use the 10@dmn{pt} Computer Modern
1194 italic font''. The @LaTeX{} home page: @url{http://www.latex-project.org}.
1197 Con@TeX{}t is an independent macro package which has a basic document
1198 structuring approach similar to @LaTeX{}. It also supports creating
1199 interactive PDF files and has integrated MetaPost support, among many
1200 other interesting features. The Con@TeX{}t home page:
1201 @url{http://www.pragma-ade.com}.
1205 @cindex American Mathematical Society, typesetting system
1206 @cindex Mathematical Reviews
1207 The official typesetting system of the American Mathematical Society.
1208 Like @LaTeX{}, it encourages generic markup commands. The AMS also
1209 provides many @LaTeX{} package for authors who prefer @LaTeX{}. Taken
1210 together, they are used to produce nearly all AMS publications, e.g.,
1211 @cite{Mathematical Reviews}. The AMS@TeX{} home page:
1212 @url{http://www.ams.org/tex}.
1217 @cindex Free Software Foundation documentation system
1218 The documentation system developed and maintained by the Free Software
1219 Foundation for their software manuals. It can be automatically
1220 converted into plain text, a machine-readable on-line format called
1221 `info', HTML, etc. The Texinfo home page:
1222 @url{http://www.gnu.org/software/texinfo}.
1226 @cindex expanded plain format
1227 The ``expanded plain'' format provides various common features (e.g.,
1228 symbolic cross-referencing, tables of contents, indexing, citations
1229 using Bib@TeX{}), for those authors who prefer to handle their own
1230 high-level formatting. The Eplain home page:
1231 @url{http://www.tug.org/eplain}.
1235 @cindex slides, producing
1236 An obsolete @LaTeX{} 2.09 format for making slides. It is replaced by
1237 the @samp{slides} document class, along with the @samp{beamer},
1238 @samp{texpower}, and other packages.
1243 @node Languages and hyphenation
1244 @section Languages and hyphenation
1246 @cindex language support in @TeX{}
1247 @cindex human languages, supported in @TeX{}
1248 @cindex hyphenation and languages
1250 @TeX{} supports most natural languages. See also @ref{TeX extensions,,
1254 * MLTeX:: Multi-lingual TeX.
1255 * TCX files:: Support for different character sets & fonts.
1256 * patgen invocation:: Creating hyphenation patterns.
1261 @subsection ML@TeX{}: Multi-lingual @TeX{}
1264 @cindex Multi-lingual @TeX{}
1266 @cindex Ferguson, Michael
1267 @cindex Raichle, Bernd
1268 @cindex accents, hyphenating words with
1269 @cindex glyph substitutions
1270 @cindex substitutions of font glyphs
1271 Multi-lingual @TeX{} (@code{mltex}) is an extension of @TeX{} originally
1272 written by Michael Ferguson and now updated and maintained by Bernd
1273 Raichle. It allows the use of non-existing glyphs in a font by
1274 declaring glyph substitutions. These are restricted to substitutions of
1275 an accented character glyph, which need not be defined in the current
1276 font, by its appropriate @code{\accent} construction using a base and
1277 accent character glyph, which do have to exist in the current font.
1278 This substitution is automatically done behind the scenes, if necessary,
1279 and thus ML@TeX{} additionally supports hyphenation of words containing
1280 an accented character glyph for fonts missing this glyph (e.g., Computer
1281 Modern). Standard @TeX{} suppresses hyphenation in this case.
1283 ML@TeX{} works at @file{.fmt}-creation time: the basic idea is to
1284 specify the @samp{-mltex} option to @TeX{} when you @code{\dump} a
1285 format. Then, when you subsequently invoke @TeX{} and read that
1286 @code{.fmt} file, the ML@TeX{} features described below will be enabled.
1288 Generally, you use special macro files to create an ML@TeX{} @code{.fmt}
1291 The sections below describe the two new primitives that ML@TeX{} defines.
1292 Aside from these, ML@TeX{} is completely compatible with standard @TeX{}.
1295 * \charsubdef:: Character substitution definitions.
1296 * \tracingcharsubdef:: Tracing substitutions.
1301 @subsubsection @code{\charsubdef}: Character substitutions
1303 @findex \charsubdef @r{and ML@TeX{}}
1305 The most important primitive ML@TeX{} adds is @code{\charsubdef}, used
1306 in a way reminiscent of @code{\chardef}:
1308 \charsubdef @var{composite} [=] @var{accent} @var{base}
1311 Each of @var{composite}, @var{accent}, and @var{base} are font glyph
1312 numbers, expressed in the usual @TeX{} syntax: @t{`\e} symbolically,
1313 @t{'145} for octal, @t{"65} for hex, @t{101} for decimal.
1315 ML@TeX{}'s @code{\charsubdef} declares how to construct an accented
1316 character glyph (not necessarily existing in the current font) using two
1317 character glyphs (that do exist). Thus it defines whether a character
1318 glyph code, either typed as a single character or using the @code{\char}
1319 primitive, will be mapped to a font glyph or to an @code{\accent} glyph
1322 For example, if you assume glyph code 138
1323 @cindex e-circumflex
1324 (decimal) for an e-circumflex
1328 and you are using the Computer Modern fonts, which have the circumflex
1329 accent in position 18 and lowercase `e' in the usual ASCII position 101
1330 decimal, you would use @code{\charsubdef} as follows:
1333 \charsubdef 138 = 18 101
1336 For the plain @TeX{} format to make use of this substitution, you have
1337 to redefine the circumflex accent macro @code{\^} in such a way that if
1338 its argument is character `e' the expansion @code{\char138 } is used
1339 instead of @code{\accent18 e}. Similar @code{\charsubdef} declaration
1340 and macro redefinitions have to be done for all other accented
1343 To disable a previous @code{\charsubdef @var{c}}, redefine @var{c}
1344 as a pair of zeros. For example:
1346 \charsubdef '321 = 0 0 % disable N tilde
1350 (Octal @t{'321} is the ISO Latin-1 value for the Spanish N tilde.)
1352 @code{\charsubdef} commands should only be given once. Although in
1353 principle you can use @code{\charsubdef} at any time, the result is
1354 unspecified. If @code{\charsubdef} declarations are changed, usually
1355 either incorrect character dimensions will be used or ML@TeX{} will
1356 output missing character warnings. (The substitution of a
1357 @code{\charsubdef} is used by @TeX{} when appending the character node
1358 to the current horizontal list, to compute the width of a horizontal box
1359 when the box gets packed, and when building the @code{\accent}
1360 construction at @code{\shipout}-time. In summary, the substitution is
1361 accessed often, so changing it is not desirable, nor generally useful.)
1364 @node \tracingcharsubdef
1365 @subsubsection @code{\tracingcharsubdef}: Substitution diagnostics
1367 @findex \tracingcharsubdef @r{and ML@TeX{}}
1368 @cindex redefined character substitutions
1369 To help diagnose problems with @samp{\charsubdef}, ML@TeX{} provides a
1370 new primitive parameter, @code{\tracingcharsubdef}. If positive, every
1371 use of @code{\charsubdef} will be reported. This can help track down
1372 when a character is redefined.
1374 @findex \tracinglostchars @r{and ML@TeX{}}
1375 In addition, if the @TeX{} parameter @code{\tracinglostchars} is 100 or
1376 more, the character substitutions actually performed at
1377 @code{\shipout}-time will be recorded.
1381 @subsection TCX files: Character translations
1383 @flindex TCX @r{character translation files}
1384 @flindex .tcx @r{character translation files}
1385 @cindex character translation files
1387 @cindex international characters
1388 @cindex 8-bit characters
1389 @cindex accented character
1390 TCX (@TeX{} character translation) files help @TeX{} support direct
1391 input of 8-bit international characters if fonts containing those
1392 characters are being used. Specifically, they map an input (keyboard)
1393 character code to the internal @TeX{} character code (a superset of
1396 Of the various proposals for handling more than one input encoding,
1397 TCX files were chosen because they follow Knuth's original ideas for
1398 the use of the @samp{xchr} and @samp{xord} tables. He ventured that
1399 these would be changed in the WEB source in order to adjust the actual
1400 version to a given environment. It turns out, however, that
1401 recompiling the WEB sources is not as simple a task as Knuth may have
1402 imagined; therefore, TCX files, providing the possibility of changing
1403 of the conversion tables on on-the-fly, have been implemented instead.
1405 This approach limits the portability of @TeX{} documents, as some
1406 implementations do not support it (or use a different method for
1407 input-internal reencoding). It may also be problematic to determine
1408 the encoding to use for a @TeX{} document of unknown provenance; in
1409 the worst case, failure to do so correctly may result in subtle errors
1410 in the typeset output. But we feel the benefits outweigh these
1413 This is entirely independent of the ML@TeX{} extension (@pxref{MLTeX}):
1414 whereas a TCX file defines how an input keyboard character is mapped to
1415 @TeX{}'s internal code, ML@TeX{} defines substitutions for a
1416 non-existing character glyph in a font with a @code{\accent}
1417 construction made out of two separate character glyphs. TCX files
1418 involve no new primitives; it is not possible to specify
1419 that an input (keyboard) character maps to more than one character.
1421 @vindex WEB2C@r{, search path for TCX files}
1422 Information on specifying TCX files:
1426 The best way to specify a TCX file is to list it explicitly in the
1427 first line of the main document:
1429 %& -translate-file=@var{tcxfile}
1433 You can also specify a TCX file to be used on a particular @TeX{} run
1434 with the command-line option @samp{-translate-file=@var{tcxfile}}.
1437 TCX files are searched for along the @code{WEB2C} path.
1440 Initial @TeX{} (@pxref{Initial TeX,,Initial @TeX{}}) ignores TCX files.
1446 @cindex Cork encoding and ISO input
1447 @cindex T1 encoding and ISO input
1448 The Web2c distribution comes with a number of TCX files. Two
1449 important ones are @file{il1-t1.tcx} and @file{il2-t1.tcx}, which
1450 support ISO Latin 1 and ISO Latin 2, respectively, with Cork-encoded
1451 fonts (a.k.a.@ the @LaTeX{} T1 encoding). TCX files for Czech,
1452 Polish, and Slovak are also provided.
1454 One other notable TCX file is @file{empty.tcx}, which is, well,
1455 empty. Its purpose is to reset Web2C's behavior to the default (only
1456 visible ASCII being printable, as described below) when a format was
1457 dumped with another TCX being active---which is in fact the case for
1458 everything but plain @TeX{} in the TeX Live and other distributions.
1463 @result{} terminal etc. output with 8-bit chars
1464 latex --translate-file=empty.tcx somefile8.tex
1465 @result{} terminal etc. output with ^^ notation
1468 @cindex syntax of TCX files
1469 Syntax of TCX files:
1472 @cindex blank lines, in TCX files
1473 Line-oriented. Blank lines are ignored.
1476 @cindex whitespace, in TCX files
1477 Whitespace is ignored except as a separator.
1480 @cindex comments, in TCX files
1481 Comments start with @samp{%} and continue to the end of the line.
1484 Otherwise, a line consists of one or two character codes, optionally
1485 followed by 0 or 1. The last number indicates whether @var{dest} is
1486 considered printable.
1488 @var{src} [@var{dest} [@var{prnt}]]
1492 @cindex character codes, in TCX files
1493 @cindex octal character codes, in TCX files
1494 @cindex hex character codes, in TCX files
1495 @cindex decimal character codes, in TCX files
1496 Each character code may be specified in octal with a leading @samp{0},
1497 hexadecimal with a leading @samp{0x}, or decimal otherwise. Values must
1498 be between 0 and 255, inclusive (decimal).
1501 If the @var{dest} code is not specified, it is taken to be the same as
1505 If the same @var{src} code is specified more than once, it is the last
1506 definition that counts.
1509 @cindex printable characters, specifying
1510 @kindex ^^ @r{notation, avoiding}
1511 Finally, here's what happens: when @TeX{} sees an input character with
1512 code @var{src}, it 1) changes @var{src} to @var{dest}; and 2) makes the
1513 @var{dest} code ``printable'', i.e., printed as-is in diagnostics and the
1514 log file rather than in @samp{^^} notation.
1516 By default, no characters are translated, and character codes between 32
1517 and 126 inclusive (decimal) are printable.
1519 Specifying translations for the printable ASCII characters (codes
1520 32--127) will yield unpredictable results. Additionally you shouldn't
1521 make the following characters printable: @code{^^I} (TAB), @code{^^J}
1522 (line feed), @code{^^M} (carriage return), and @code{^^?} (delete),
1523 since @TeX{} uses them in various ways.
1525 @cindex font character code, translating
1526 @cindex keyboard character code, translating
1527 Thus, the idea is to specify the input (keyboard) character code for
1528 @var{src}, and the output (font) character code for @var{dest}.
1530 @cindex interaction between TCX files and @samp{-8bit}.
1531 By default, only the printable ASCII characters are considered printable
1532 by @TeX{}. If you specify the @samp{-8bit} option, all characters are
1533 considered printable by default. If you specify both the @samp{-8bit}
1534 option and a TCX file, then the TCX can set specific characters to be
1537 Both the specified TCX encoding and whether characters are printable
1538 are saved in the dump files (like @file{tex.fmt}). So by giving these
1539 options in combination with @samp{-ini}, you control the defaults seen
1540 by anyone who uses the resulting dump file.
1542 When loading a dump, if the @samp{-8bit} option was given, then all
1543 characters become printable by default.
1545 When loading a dump, if a TCX file was specified, then the TCX data from
1546 the dump is ignored and the data from the file used instead.
1549 @node patgen invocation
1550 @subsection Patgen: Creating hyphenation patterns
1553 @cindex hyphenation patterns, creating
1554 @cindex languages, hyphenation rules for
1556 Patgen creates hyphenation patterns from dictionary files for use with
1560 patgen @var{dictionary} @var{patterns} @var{output} @var{translate}
1563 Each argument is a filename. No path searching is done. The output is
1564 written to the file @var{output}.
1568 @c @cindex dictionary file
1569 @c @findex \lefthyphemmin
1570 @c @findex \righthyphenmin
1571 @c The first line contains the values of @code{}\lefthyphenmin} and
1572 @c @code{\righthyphenmin} in columns 1--2 and 3--4. Columns 5, 6, and 7 may
1573 @c optionally contain replacements for the default characters @samp{.},
1574 @c @samp{-}, and @samp{*} respectively used in the word lists.
1576 @c Subsequent lines are either comments (if they start with two identical
1577 @c characters, e.g., @samp{%%}), or contain the external representation of
1578 @c the lower case version of a letter, followed by an arbitrary number of
1579 @c upper case versions, preceded and separated by a delimiter and followed
1580 @c by two consecutive delimiters. The delimiter may be any character not
1581 @c occurring in either version.
1583 In addition, Patgen prompts interactively for other values.
1585 For more information, see @cite{Word hy-phen-a-tion by com-puter} by
1586 Frank Liang (@pxref{References}), and also the @file{patgen.web} source file.
1588 The only options are @samp{-help} and @samp{-version} (@pxref{Common
1593 @section Shell escapes
1595 @cindex shell commands in @TeX{}
1596 @cindex security, and shell escapes
1597 @cindex restricted shell escapes
1598 @cindex system command
1599 @vindex shell_escape @r{enabling in @TeX{}}
1600 @findex \immediate\write18
1601 @findex \write18 @r{shell escape extension}
1602 @findex system @r{C library function}
1604 @TeX{} can execute @dfn{shell escapes}, that is, arbitrary shell
1605 commands. Although tremendously useful, this also has obvious
1606 security implications. Therefore, as of @TeX{} Live 2009, a
1607 @dfn{restricted} mode for shell escapes is the default mode of
1608 operation, which allows executing only certain commands, as specified
1609 in the @file{texmf.cnf} configuration file.
1613 Unrestricted shell escapes are allowed if the option
1614 @option{--shell-escape} is specified, or if the environment variable
1615 or config file value @code{shell_escape} is set to @samp{t} or
1616 @samp{y} and @samp{1}.
1619 Restricted shell escapes are allowed if @code{shell_escape} is set to
1620 @samp{p}. This is the default.
1623 Shell escapes are completely disabled if @option{--no-shell-escape} is
1624 specified, or if @code{shell_escape} is set to anything else.
1627 When enabled, the @TeX{} construct to execute a system command is
1628 @code{\write18@{@var{shell-command}@}}; for example:
1631 \write18@{echo "hello, world"@}
1634 @findex \output @r{routine, and @code{\write}}
1635 From @TeX{}'s point of view, this is a normal @code{\write} command,
1636 and is therefore subject to the usual @TeX{} expansions. Also, the
1637 system call either happens during the @samp{\output} routine or right
1638 away, according to the absence or presence of the @code{\immediate}
1639 prefix, as usual for @code{\write}.
1641 @cindex exit status, of shell escape
1642 The @var{shell-command} string is passed to the command shell (via the
1643 C library function @code{system}). The output of @var{shell-command}
1644 is not diverted anywhere, so it will not appear in the log file, or
1645 anywhere but the terminal output. The exit status of the system call
1646 is also not available to @TeX{}.
1648 In unrestricted mode, the argument is simply passed straight to
1649 @code{system} unaltered.
1651 In restricted mode, ASCII double quote characters (@verb{|"|}) should
1652 always be used in the argument to @code{\write18} where quoting of
1653 arguments is needed, as in the example above. This is to achieve some
1654 measure of system independence. On Unix systems, these are replaced
1655 with single quote (@verb{|'|}) characters to avoid insecure further
1656 expansion. Care is also taken on Windows to avoid additional
1657 expansions (from, e.g., @verb{|`...`|}). Mismatched quotation marks
1658 in the command string result in a diagnostic message in the log file;
1659 no execution is performed.
1661 @findex shell_escape_commands
1662 After quotation processing, if the first word (delimited by a space or
1663 tab) of the command is in the list specified by the
1664 @code{shell_escape_commands} configuration value, the command is
1665 executed. Otherwise it is not. In any case, a message is written to
1668 The @code{shell_escape_commands} value is a comma-separated list of
1669 words. Whitespace is significant, and typically should not be
1670 present. The default definition looks like this, but with more
1674 shell_escape_commands = bibtex,dvips,epstopdf,...,tex
1677 @cindex pipes, reading and writing
1678 @findex \openin@r{, and pipes}
1679 @findex \input@r{, and pipes}
1680 @findex \openout@r{, and pipes}
1681 @findex \pdfshellescape
1682 pdf@TeX{} and lua@TeX{} support reading (via @code{\input} and
1683 @code{\openin}) and writing (via @code{\openout}) from pipes if the
1684 first character is @samp{|}. The following command is then treated
1685 exactly the same as the argument to @code{\write18}. In these
1686 engines, the primitive variable @code{\pdfshellescape} is set to 0 if
1687 shell escapes are disabled, 1 if they are enabled, and 2 if they are
1688 enabled with restrictions.
1690 @cindex web environments, and security
1691 The purpose of this feature is to make it possible for @TeX{}
1692 documents to perform useful external actions in the common case of an
1693 individual user running a known document on his or her own machine.
1694 In such environments as CGI scripts or wikis where the input has to be
1695 considered untrustworthy, shell escapes should be completely disabled.
1699 @section IPC and @TeX{}
1703 (If anyone uses this feature and needs documentation, write
1704 @email{tex-k@@tug.org}.)
1706 This functionality is available only if the @samp{--enable-ipc} option
1707 was specified to @code{configure} during installation of Web2c
1708 (@pxref{Installation}).
1711 If you define @code{IPC_DEBUG} before compilation (e.g., with @samp{make
1712 XCFLAGS=-DIPC_DEBUG}), @TeX{} will print messages to standard error
1713 about its socket operations. This may be helpful if you are, well,
1717 @node TeX extensions
1718 @section @TeX{} extensions
1720 @cindex extensions to @TeX{}
1721 @cindex @TeX{}, extensions to
1723 The base @TeX{} program has been extended in many ways. Here's a
1729 @cindex primitives, new
1730 Adds many new primitives, including right-to-left typesetting and more
1731 registers. Now frozen.
1736 This adds Unicode support, right-to-left typesetting, and more. Omega
1737 was the original program. Aleph is an updated version with a variety
1738 of bug fixes, and includes e-@TeX{}. Aleph is not actively maintained.
1743 @cindex micro-typography
1745 Can produce PDF as well as DVI files. It also incorporates the
1746 e-@TeX{} extensions, new primitives for hypertext and
1747 micro-typography, reading/writing from pipes, and much more. Home
1748 page: @url{http://pdftex.org}.
1753 Based on pdf@TeX{}, this also embeds the Lua programming language
1754 (@url{http://lua.org}) and opens up the @TeX{} typesetting engine to
1755 control from Lua. Home page: @url{http://luatex.org}.
1760 Combines support for Unicode input and OpenType- and system fonts
1761 with the capabilities of pdf@TeX{}.
1762 Home page: @url{http://tug.org/xetex}.
1768 @chapter Metafont: Creating typeface families
1771 @cindex typeface families
1772 @cindex geometric designs
1776 Metafont is a system for producing shapes; it was designed for producing
1777 complete typeface families, but it can also produce geometric designs,
1778 dingbats, etc. And it has considerable mathematical and
1779 equation-solving capabilities which can be useful entirely on their own.
1781 Metafont is a batch language, like C or Pascal: you compile a Metafont
1782 program into a corresponding font, rather than interactively drawing
1783 lines or curves. This approach has both considerable disadvantages
1784 (people unfamiliar with conventional programming languages will be
1785 unlikely to find it usable) and considerable advantages (you can make
1786 your design intentions specific and parameterizable). For a complete
1787 description of the Metafont language, see @cite{The METAFONTbook}
1788 (@pxref{References}).
1791 * mf invocation:: Invoking Metafont.
1792 * Initial Metafont:: Making bases.
1793 * Modes:: Device definitions for Metafont.
1794 * Online Metafont graphics:: Seeing MF output online.
1795 * gftodvi invocation:: Making proofsheets for fonts.
1796 * mft invocation:: Prettyprinting Metafont sources.
1801 @section @code{mf} invocation
1804 @cindex Metafont invocation
1806 Metafont (usually invoked as @code{mf}) reads character definitions
1807 specified in the Metafont programming language, and outputs the
1808 corresponding font. This section merely describes the options available
1809 in the Web2c implementation. For a complete description of the Metafont
1810 language, see @cite{The Metafontbook} (@pxref{References}).
1812 Metafont processes its command line and determines its memory dump
1813 (base) file in a way exactly analogous to MetaPost and @TeX{}
1814 (@pxref{tex invocation}, and @pxref{Memory dumps}). Synopses:
1817 mf [@var{option}]@dots{} [@var{mfname}[.mf]] [@var{mf-commands}]
1818 mf [@var{option}]@dots{} \@var{first-line}
1819 mf [@var{option}]@dots{} &@var{base} @var{args}
1822 Most commonly, a Metafont invocation looks like this:
1824 mf '\mode:=@var{mode}; mag:=@var{magnification}; input @var{mfname}'
1827 (The single quotes avoid unwanted interpretation by the shell.)
1830 @cindex Metafont input files
1832 @pindex mktexmf@r{, disabling}
1833 Metafont searches the usual places for the main input file @var{mfname}
1834 (@pxref{Supported file formats,,, kpathsea, Kpathsea}), extending
1835 @var{mfname} with @file{.mf} if necessary. To see all the relevant
1836 paths, set the environment variable @code{KPATHSEA_DEBUG} to @samp{-1}
1837 before running the program. By default, Metafont runs an external
1838 program named @file{mktexmf} to create any nonexistent Metafont source
1839 files you input. You can disable this at configure-time or runtime
1840 (@pxref{mktex configuration,,, kpathsea, Kpathsea}). This is mostly
1841 for the sake of the EC fonts, which can be generated at any size.
1843 @flindex .@var{nnn}gf @r{generic fonts}
1846 @cindex GF files, output by Metafont
1847 @cindex PK files, not output by Metafont
1848 Metafont writes the main GF output to the file
1849 @file{@var{basemfname}.@var{nnn}gf}, where @var{nnn} is the font
1850 resolution in pixels per inch, and @var{basemfname} is the basename of
1851 @var{mfname}, or @samp{mfput} if no input file was specified. A GF file
1852 contains bitmaps of the actual character shapes. Usually GF files are
1853 converted immediately to PK files with GFtoPK (@pxref{gftopk
1854 invocation}), since PK files contain equivalent information, but are
1855 more compact. (Metafont output in GF format rather than PK for only
1856 historical reasons.)
1858 @flindex .tfm @r{output}
1859 @cindex TFM files, output by Metafont
1860 Metafont also usually writes a metric file in TFM format to
1861 @file{@var{basemfname}.tfm}. A TFM file contains character dimensions,
1862 kerns, and ligatures, and spacing parameters. @TeX{} reads only this
1863 @t{.tfm} file, not the GF file.
1865 @cindex mode needed to run Metafont
1866 @findex proof @r{mode}
1869 The @var{mode} in the example command above is a name referring to a
1870 device definition (@pxref{Modes}); for example, @code{localfont} or
1871 @code{ljfour}. These device definitions must generally be precompiled
1872 into the base file. If you leave this out, the default is @code{proof}
1873 mode, as stated in @cite{The Metafontbook}, in which Metafont outputs at
1874 a resolution of 2602@dmn{dpi}; this is usually not what you want. The
1875 remedy is simply to assign a different mode---@code{localfont}, for
1878 The @var{magnification} assignment in the example command above is a
1879 magnification factor; for example, if the device is 600@dmn{dpi} and you
1880 specify @code{mag:=2}, Metafont will produce output at 1200@dmn{dpi}.
1881 Very often, the @var{magnification} is an expression such as
1882 @code{magstep(.5)}, corresponding to a @TeX{} ``magstep'', which are
1891 After running Metafont, you can use the font in a @TeX{} document as
1894 \font\myfont = newfont
1895 \myfont Now I am typesetting in my new font (minimum hamburgers).
1898 The program accepts the following options, as well as the standard
1899 @samp{-help} and @samp{-version} (@pxref{Common options}):
1901 @item -[no]-file-line-error
1902 @itemx -fmt=@var{fmtname}
1903 @itemx -halt-on-error
1905 @itemx -interaction=@var{string}
1906 @itemx -jobname=@var{string}
1907 @itemx -kpathsea-debug=@var{number}
1908 @itemx -[no]parse-first-line
1909 @itemx -output-directory
1910 @itemx -progname=@var{string}
1912 @itemx -translate-file=@var{tcxfile}
1914 These options are common to @TeX{}, Metafont, and MetaPost.
1915 @xref{Common options}.
1917 @item -mktex=@var{filetype}
1918 @itemx -no-mktex=@var{filetype}
1919 @opindex -mktex=@var{filetype}
1920 @opindex -no-mktex=@var{filetype}
1921 Turn on or off the @samp{mktex} script associated with @var{filetype}.
1922 The only value that makes sense for @var{filetype} is @samp{mf}.
1926 @node Initial Metafont
1927 @section Initial Metafont
1929 @cindex initial Metafont
1930 @cindex Metafont, initial
1934 @code{inimf} is the ``initial'' form of Metafont, which does lengthy
1935 initializations avoided by the ``virgin'' (@code{vir}) form, so as to
1936 be capable of dumping @samp{.base} files (@pxref{Memory dumps}). For
1937 a detailed comparison of virgin and initial forms, see @ref{Initial
1940 For a list of options and other information, see @ref{mf invocation}.
1944 The only memory dump file commonly used with Metafont is the default
1945 @samp{plain.base}, also known as @samp{mf.base} (again, @pxref{Memory
1946 dumps}). It is created by default during installation, but you can also
1947 do so by hand if necessary (e.g., if a Metafont update is issued):
1949 mf -ini '\input plain; input modes; dump'
1952 (The quotes prevent interpretation of the backslashes from the shell.)
1953 Then install the resulting @file{plain.base} in @samp{$(basedir)}
1954 (@file{/usr/local/share/texmf/web2c} by default), and link
1955 @file{mf.base} to it.
1957 For an explanation of the additional @file{modes.mf} file,
1958 see @ref{Modes}. This file has no counterpart in @TeX{} or MetaPost.
1960 @flindex cmmf.base @r{not recommended}
1963 @cindex Computer Modern macros
1964 @cindex base files, plain only
1965 In the past, it was sometimes useful to create a base file
1966 @file{cmmf.base} (a.k.a.@: @file{cm.base}), with the Computer Modern
1967 macros also included in the base file. Nowadays, however, the
1968 additional time required to read @file{cmbase.mf} is exceedingly small,
1969 usually not enough to be worth the administrative hassle of updating the
1970 @file{cmmf.base} file when you install a new version of @file{modes.mf}.
1971 @cindex type design, personal
1972 People actually working on a typeface may still find it worthwhile to
1973 create their own base file, of course.
1977 @section Modes: Device definitions for Metafont
1979 @cindex modes file needed for Metafont
1980 @cindex base files, need mode definitions
1981 @cindex device definitions, for Metafont
1982 @cindex printer characteristics, for Metafont
1983 Running Metafont and creating Metafont base files requires information
1984 that @TeX{} and MetaPost do not: @dfn{mode} definitions which specify
1985 device characteristics, so Metafont can properly rasterize the shapes.
1987 @flindex modes.mf @r{recommended modes file}
1988 When making a base file, a file containing modes for locally-available
1989 devices should be input after @file{plain.mf}. One commonly used file
1990 is @url{ftp://ftp.tug.org/tex/modes.mf}; it includes all known
1993 @cindex small Metafont memory and modes
1996 If, however, for some reason you have decreased the memory available in
1997 your Metafont, you may need to copy @file{modes.mf} and remove the
1998 definitions irrelevant to you (probably most of them) instead of using
1999 it directly. (Or, if you're a Metafont hacker, maybe you can suggest a
2000 way to redefine @code{mode_def} and/or @code{mode_setup}; right now, the
2001 amount of memory used is approximately four times the total length of
2002 the @code{mode_def} names, and that's a lot.)
2004 If you have a device not included in @file{modes.mf}, please see
2005 comments in that file for how to create the new definition, and please
2006 send the definition to @email{tex-fonts@@math.utah.edu} to get it included
2007 in the next release of @file{modes.mf}.
2009 @findex smode @r{and dynamic Metafont mode definition}
2010 @cindex dynamic Metafont mode definitions with @code{smode}
2011 Usually, when you run Metafont you must supply the name of a mode that
2012 was dumped in the base file. But you can also define the mode
2013 characteristics dynamically, by invoking Metafont with an assignment to
2014 @code{smode} instead of @code{mode}, like this:
2016 mf '\smode:="newmode.mf"; mag:=@var{magnification}; input @var{mfname}'
2019 This is most useful when you are working on the definition of a new
2022 The @var{magnification} and @var{mfname} arguments are explained in
2023 @ref{mf invocation}. In the file @file{newmode.mf}, you should have the
2024 following (with no @code{mode_def} or @code{enddef}), if you are using
2025 @file{modes.mf} conventions:
2027 mode_param (pixels_per_inch, @var{dpi});
2028 mode_param (blacker, @var{b});
2029 mode_param (fillin, @var{f});
2030 mode_param (o_correction, @var{o});
2034 (Of course, you should use real numbers for @var{dpi}, @var{b}, @var{f},
2037 For more information on the use of @code{smode}, or if you are not using
2038 @file{modes.mf}, see page 269 of @cite{The Metafontbook}.
2041 @node Online Metafont graphics
2042 @section Online Metafont graphics
2044 @cindex online Metafont graphics
2045 @cindex Metafont graphics
2047 The Web2c implementation of Metafont can do online graphics with a
2048 number of devices. (See the Metafont manual for more information about
2049 how to draw on your screen.) By default, no graphics support is
2054 Metafont examines the @code{MFTERM} environment variable or config file
2055 value at runtime, or the @code{TERM} environment variable if
2056 @code{MFTERM} is not set, to determine the device support to use.
2057 Naturally, only the devices for which support has been compiled in can
2060 Here is a table of the possibilities, showing the @code{MFTERM} value
2061 and the corresponding @code{configure} option(s) in parentheses.
2065 @cindex Herberts, Mathias
2066 @opindex --enable-epsfwin
2067 (@samp{--enable-epsfwin}) Pseudo-window server for Encapsulated
2068 PostScript (see @file{web2c/window/epsf.c}). This device produces an
2069 EPS file containing the graphics which would be displayed online on
2070 other devices. The name of the EPS file defaults to metafont.eps but
2071 can be changed by setting the MFEPSF environment variable to the new
2072 filename. Contributed by Mathias Herberts.
2075 @opindex --enable-hp2627win
2076 (@samp{--enable-hp2627win}) HP2627a color graphics terminals.
2079 @opindex --enable-mftalkwin
2080 (@samp{--enable-mftalkwin}) Generic window server (see
2081 @file{web2c/window/mftalk.c}).
2084 @pindex DrawingServant
2085 @opindex --enable-next
2086 (@samp{--enable-next}) NeXT window system. This requires a separate
2087 program, called @code{DrawingServant}, available separately. See the
2088 @file{web2c/window/next.c}.
2091 @opindex --enable-regiswin
2092 @cindex Regis graphics support
2093 (@samp{--enable-regiswin}) Regis terminals.
2098 @opindex --enable-suntoolswin
2100 (@samp{--enable-suntoolswin}) The old Suntools (not any flavor of X)
2101 window system. (You can get the even older SunWindows @code{gfx} system
2102 by using @file{sun-gfx.c}.)
2106 @opindex --enable-tektronixwin
2107 (@samp{--enable-tektronixwin}) Tektronix terminals.
2109 @cindex Poole, Simon
2111 @cindex Tektronix 4014
2112 @opindex --enable-unitermwin
2113 (@samp{--enable-unitermwin}) Uniterm, Simon Poole's emulator of a smart
2114 Tektronix 4014 terminal. This may work with regular Tektronix terminals
2115 as well; it's faster than the driver @samp{--enable-tektronixwin} selects.
2122 @samp{--with-x} The X window system (version 11).
2124 @opindex --with-mf-x-toolkit=@var{kit}
2126 @cindex X toolkits and Metafont
2128 @cindex Xlib support
2129 There are two variants of the X11 support, one that works with the Xt
2130 toolkit, and another that works directly with Xlib. The Xt support is
2131 more efficient and has more functionality, so it is the default. If you
2132 must use the Xlib support, use @samp{configure --with-x
2133 --with-kf-x-toolkit=no}.
2135 @opindex --disable-mf-nowin
2136 @cindex non-windows-capable Metafont
2137 Specify @samp{--disable-mf-nowin} in order not to build a separate
2138 non-windows-capable Metafont executable @code{mf-nowin} (or
2139 @code{mf-nowin.exe}).
2142 @cindex X class name for Metafont
2143 @cindex class name for Metafont
2144 @cindex geometry for Metafont
2145 @cindex Metafont geometry
2147 @flindex .Xresources
2148 @opindex -geometry@r{, supported with Xt}
2149 You cannot specify any of the usual X options (e.g., @samp{-geometry})
2150 on the Metafont command line, but you can specify X resources in your
2151 @file{~/.Xdefaults} or @file{~/.Xresources} file. The class name is
2152 @code{Metafont}. If you're using the Xt support, all the usual X toolkit
2153 resources are supported. If you're using the Xlib support, only the
2154 @code{geometry} resource is supported.
2157 You specify the X display to which Metafont connects in the
2158 @code{DISPLAY} environment variable, as usual.
2162 @cindex Metafont online support, new devices
2163 @cindex new graphics support for Metafont
2165 Writing support for a new device is straightforward. Aside from defining
2166 the basic drawing routines that Metafont uses (see @file{mf.web}), you
2167 only have to add another entry to the tables on the last page of
2168 @file{web2c/lib/texmfmp.c}. Or you can write an independent program and
2169 use MFtalk (see @file{web2c/window/mftalk.c}).
2172 @node gftodvi invocation
2173 @section GFtoDVI: Character proofs of fonts
2176 @cindex character proofs of fonts
2178 @cindex proof sheets, of fonts
2180 GFtoDVI makes @dfn{proof sheets} from a GF bitmap file as output by, for
2181 example, Metafont (@pxref{Metafont}). This is an indispensable aid for
2182 font designers or Metafont hackers. Synopsis:
2185 gftodvi [@var{option}]@dots{} @var{gfname}[gf]
2188 The font @var{gfname} is searched for in the usual places (@pxref{Glyph
2189 lookup,,, kpathsea, Kpathsea}). To see all the relevant paths, set the
2190 environment variable @code{KPATHSEA_DEBUG} to @samp{-1} before running
2193 The suffix @samp{gf} is supplied if not already present. This suffix is
2194 not an extension, no @samp{.} precedes it; for instance, @file{cmr10.600gf}.
2196 The output filename is the basename of @var{gfname} extended with
2197 @file{.dvi}, e.g., @samp{gftodvi /wherever/foo.600gf} creates
2200 The characters from @var{gfname} appear one per page in the DVI output,
2201 with labels, titles, and annotations, as specified in Appendix H
2202 (Hardcopy Proofs) of @cite{The Metafontbook}.
2204 GFtoDVI uses several fonts besides @var{gfname} itself:
2209 @dfn{gray font} (default @file{gray}): for the pixels that actually make
2210 up the character. Simply using black is not right, since then labels,
2211 key points, and other information could not be shown.
2215 @dfn{title font} (default @file{cmr8}): for the header information at
2216 the top of each output page.
2220 @dfn{label font} (default @file{cmtt10}): for the labels on key points
2225 @dfn{slant font} (no default): for diagonal lines, which are otherwise
2226 simulated using horizontal and vertical rules.
2229 To change the default fonts, you must use @code{special} commands in
2230 your Metafont source file, typically via commands like @code{slantfont
2231 slantlj4}. There is no default slant font since no one printer is
2232 suitable as a default. You can make your own by copying one of the
2233 existing files, such as
2234 @file{.../fonts/source/public/misc/slantlj4.mf} and then running
2237 For testing purposes, you may it useful to run @code{mf-nowin rtest}
2238 (hit RETURN when it stops) to get a @file{gf} file of a thorn glyph.
2239 Or use @command{mf} instead of @command{mf-nowin} to have the glyph(s)
2240 displayed on the screen. After that, @code{gftodvi rtest.2602gf}
2241 should produce @file{rtest.dvi}, which you process as usual.
2243 The program accepts the following option, as well as the standard
2244 @samp{-verbose}, @samp{-help}, and @samp{-version} (@pxref{Common
2248 @item -overflow-label-offset=@var{points}
2249 @opindex -overflow-label-offset=@var{points}
2250 @cindex overflow label offset
2251 @cindex offset for overflow labels
2252 Typeset the so-called overflow labels, if any, @var{points} @TeX{}
2253 points from the right edge of the character bounding box. The default
2254 is a little over two inches (ten million scaled points, to be precise).
2255 Overflow equations are used to locate coordinates when their actual
2256 position is too crowded with other information.
2260 @node mft invocation
2261 @section MFT: Prettyprinting Metafont source
2264 @cindex Metafont source, prettyprinting
2265 @cindex prettyprinting Metafont source
2266 @cindex @TeX{}, creating from Metafont
2269 MFT translates a Metafont program into a @TeX{} document suitable for
2270 typesetting, with the aid of @TeX{} macros defined in the file
2271 @file{mftmac.tex}. Synopsis:
2274 mft [@var{option}]@dots{} @var{mfname}[.mf]
2277 MFT searches the usual places for @var{mfname} (@pxref{Supported file
2278 formats,,, kpathsea, Kpathsea}). To see all the relevant paths, set the
2279 environment variable @code{KPATHSEA_DEBUG} to @samp{-1} before running
2280 the program. The output goes to the basename of @var{mfname} extended
2281 with @file{.tex}, e.g., @samp{mft /wherever/foo.mf} creates
2284 Line breaks in the input are carried over into the output; moreover,
2285 blank spaces at the beginning of a line are converted to quads of
2286 indentation in the output. Thus, you have full control over the
2287 indentation and line breaks. Each line of input is translated
2288 independently of the others.
2290 Further control is allowed via Metafont comments:
2291 @cindex comments, MFT control
2294 Metafont comments following a single @samp{%} should be valid @TeX{}
2295 input. But Metafont material can be included within vertical bars in a
2296 comment; this will be translated by MFT as if it were regular Metafont
2297 code. For example, a comment like @samp{% |x2r| is the tip of the bowl}
2298 will be translated into the @TeX{} @samp{% $x_@{2r@}$ is the @dots{}},
2299 i.e., the @samp{x2r} is treated as an identifier.
2302 @samp{%%} indicates that the remainder of an input line should be copied
2303 verbatim to the output. This is typically used to introduce additional
2304 @TeX{} material at the beginning or an MFT job, e.g. code to modify the
2305 standard layout or the formatting macros defined in @file{mftmac.tex},
2306 or to add a line saying @samp{%%\bye} at the end of the job. (MFT
2307 doesn't add this automatically in order to allow processing several
2308 files produces by MFT in the same @TeX{} job.)
2311 @samp{%%% @var{token1} @var{other-tokens}}
2312 introduces a change in MFT's formatting rules; all the @var{other-tokens}
2313 will henceforth be translated according to the current conventions for
2314 @var{token1}. The tokens must be symbolic (i.e., not
2315 numeric or string tokens). For example, the input line
2317 %%% addto fill draw filldraw
2320 says to format the @samp{fill}, @samp{draw}, and @samp{filldraw}
2321 operations of plain Metafont just like the primitive token @samp{addto},
2322 i.e., in boldface type. Without such reformatting commands, MFT would
2323 treat @samp{fill} like an ordinary tag or variable name. In fact, you
2324 need a @samp{%%%} command even to get parentheses to act like
2328 @samp{%%%%} introduces an MFT comment, i.e., MFT ignores the remainder
2332 Five or more @samp{%} signs should not be used.
2335 @cindex Knuth, Donald E.
2336 (The above description was edited from @file{mft.web}, written by
2339 The program accepts the following options, as well as the standard
2340 @samp{-help} and @samp{-version} (@pxref{Common options}):
2342 @item -change=@var{chfile}[.ch]
2343 @opindex -change=@var{chfile}
2344 @cindex change files, and MFT
2345 Apply the change file @var{chfile} as with Tangle and Weave
2348 @item -style=@var{mftfile}[.mft]
2349 @opindex -style=@var{mftfile}
2352 Read @var{mftfile} before anything else; a MFT style file typically
2353 contains only MFT directives as described above. The default style file
2354 is named @file{plain.mft}, which defines this properly for programs
2355 using plain Metafont. The MFT files is searched along the
2356 @code{MFTINPUTS} path; see @ref{Supported file formats,,, kpathsea, Kpathsea}.
2360 @cindex @cite{Computer Modern Typefaces}, production of
2361 Other examples of MFT style files are @file{cmbase.mft}, which defines
2362 formatting rules for the macros defined in @file{cm.base}, and
2363 @file{e.mft}, which was used in the production of Knuth's Volume@w{ }E,
2364 @cite{Computer Modern Typefaces}.
2366 @cindex MetaPost source, prettyprinting
2367 Using an appropriate MFT style file, it is also possible to configure
2368 MFT for typesetting MetaPost sources. However, MFT does not search
2369 the usual places for MetaPost input files.
2372 If you use eight-bit characters in the input file, they are
2373 passed on verbatim to the @TeX{} output file; it is up to you to
2374 configure @TeX{} to print these properly.
2378 @chapter MetaPost: Creating technical illustrations
2381 @cindex PostScript meets Metafont
2382 @cindex Metafont meets PostScript
2383 MetaPost is a picture-drawing language similar to Metafont
2384 (@pxref{Metafont}), but instead of outputting bitmaps in a ``font'', it
2385 outputs PostScript commands. It's primarily intended for creating
2386 technical illustrations.
2388 MetaPost also provides for arbitrary integration of text and graphics in
2389 a natural way, using any typesetter (@TeX{} and Troff are both
2390 supported) and a number of other subsidiary programs, described below.
2393 * mpost invocation:: Invoking MetaPost.
2394 * Initial MetaPost:: Making mems.
2395 * dvitomp invocation:: DVI-to-MPX translation.
2399 @node mpost invocation
2400 @section @code{mpost} invocation
2403 @cindex MetaPost invocation
2406 MetaPost (installed as @code{mpost}) reads a series of pictures
2407 specified in the MetaPost programming language, and outputs
2408 corresponding PostScript code. This section merely describes the
2409 options available in the Web2c implementation. For a complete
2410 description of the MetaPost language, see AT&T technical report
2411 CSTR-162, generally available in @file{@var{texmf}/doc/metapost/},
2412 where @var{texmf} is the root of @TeX{} directory structure. See
2415 @item @url{http://cm.bell-labs.com/who/hobby/MetaPost.html} (the
2416 MetaPost author's home page);
2417 @item @url{http://tug.org/metapost} (papers, packages, and
2418 related information).
2422 Also, a standard MetaPost package for drawing graphs is documented in
2423 AT&T technical report CSTR-164, available as the file @file{mpgraph.ps},
2424 generally stored alongside @file{mpman.ps}.
2426 MetaPost processes its command line and determines its memory dump (mem)
2427 file in a way exactly analogous to Metafont and @TeX{} (@pxref{tex
2428 invocation,,@code{tex} invocation}, and @pxref{Memory dumps}).
2432 mpost [@var{option}]@dots{} [@var{mpname}[.mp]] [@var{mp-commands}]
2433 mpost [@var{option}]@dots{} \@var{first-line}
2434 mpost [@var{option}]@dots{} &@var{mem} @var{args}
2438 @cindex MetaPost input files
2439 MetaPost searches the usual places for the main input file @var{mpname}
2440 (@pxref{Supported file formats,,, kpathsea, Kpathsea}), extending
2441 @var{mpname} with @file{.mp} if necessary. To see all the relevant
2442 paths, set the environment variable @code{KPATHSEA_DEBUG} to @samp{-1}
2443 before running the program.
2446 @flindex .@var{nnn} @r{PostScript figures}
2447 @flindex .tfm @r{output}
2449 @cindex TFM files, output by MetaPost
2450 @cindex PostScript output
2451 MetaPost writes its PostScript output to a series of files
2452 @file{@var{basempname}.@var{nnn}} (or perhaps
2453 @file{@var{basempname}.ps}, very occasionally
2454 @file{@var{basempname}.tfm}), where @var{nnn} are the figure numbers
2455 specified in the input, typically to the @code{beginfig} macro, and
2456 @var{basempname} is the basename of @var{mpname}, or @samp{mpout} if no
2457 input file was specified. MetaPost uses the @samp{.ps} extension when
2458 the figure number is out of range, e.g., if you say @code{beginfig(-1)}.
2460 You can use the output files as figures in a @TeX{} document just as
2461 with any other PostScript figures. For example, with this @TeX{} command:
2463 \special@{psfile="@var{filename}"@}
2466 or by using @file{epsf.tex} (@pxref{EPSF macros,,, dvips, Dvips}).
2468 @findex btex @r{for MetaPost labels}
2469 @findex etex @r{for MetaPost labels}
2470 The MetaPost construct
2472 btex @dots{} @var{tex-input} @dots{} etex
2475 generates a MetaPost picture expression corresponding to
2480 verbatimtex @dots{} @var{tex-input} @dots{} etex
2483 simply passes the @var{tex-input} through to
2484 @TeX{}. For example, if you are using @LaTeX{}, your MetaPost input file
2485 must start with a @code{verbatimtex} block that gives the necessary
2486 @code{\documentclass} (or @code{\documentstyle})
2487 @code{\begin@{document@}} command. You will also need to set the
2488 enviroment variable @code{TEX} to @samp{latex}.
2490 @var{tex-input} need not be specifically @TeX{} input; it could also be
2491 Troff. In that case, you will need the @samp{-m pictures} Troff macro
2492 package (unfortunately absent from many Troff implementations), or an
2493 equivalent such as the @samp{-m pspic} macros from GNU groff described
2496 @cindex PostScript fonts, and Troff
2497 @cindex Troff, and MetaPost
2498 @cindex Computer Modern fonts, and Troff
2499 Naturally, you must use fonts that are supported by the typesetter;
2500 specifically, you'll probably want to use standard PostScript fonts with
2501 Troff. And only the @TeX{} system understands Computer Modern or other
2502 Metafont fonts; you can also use PostScript fonts with @TeX{}, of course.
2505 @cindex downloading of fonts for MetaPost labels
2506 @cindex font downloading for MetaPost labels
2507 MetaPost-generated PostScript figures which do use Computer Modern fonts
2508 for labels cannot be directly previewed or printed. Instead, you must
2509 include them in a @TeX{} document and run the resulting DVI file through
2510 Dvips to arrange for the downloading of the required fonts (@pxref{Fonts
2511 in figures,,, dvips, Dvips}). To help with this, the MetaPost
2512 distribution provides a small @TeX{} file @file{mproof.tex} which is
2513 typically called as:
2515 tex mproof @var{mp-output-files}... ; dvips mproof -o
2518 The resulting file @file{mproof.ps} can then be printed or previewed.
2520 @vindex prologues@r{, and EPSF output}
2521 @flindex psfonts.map@r{, read by MetaPost}
2522 To generate EPSF files, set the internal MetaPost variable
2523 @code{prologues} positive. To make the output files self-contained, use
2524 only standard PostScript fonts. MetaPost reads the same
2525 @file{psfonts.map} file as Dvips, to determine PostScript fonts that
2526 need to be downloaded (@pxref{psfonts.map,,, dvips, Dvips}).
2528 @cindex PDF, and @code{.mps} files
2529 @cindex @code{.mps} files and PDF
2530 It is posible for pdf@TeX{} to read MetaPost output directly; this is
2531 in contrast to general EPSF files, which have to be converted for use
2532 with PDF output. The easiest way is to name the MetaPost output files
2533 with the @code{.mps} extension. Then the @LaTeX{}
2534 @code{\includegraphics} command, for example, will be able to read
2535 them, even when outputting PDF.
2537 @cindex security, and @code{write}
2538 MetaPost can write output files, via the @code{write} primitive; this
2539 opens a security hole. @xref{tex invocation}.
2541 The program accepts the following options, as well as the standard
2542 @samp{-help} and @samp{-version} (@pxref{Common options}):
2544 @item -[no]-file-line-error
2545 @itemx -fmt=@var{fmtname}
2546 @itemx -halt-on-error
2548 @itemx -interaction=@var{string}
2549 @itemx -jobname=@var{string}
2550 @itemx -kpathsea-debug=@var{number}
2551 @itemx -[no]parse-first-line
2552 @itemx -output-directory
2553 @itemx -progname=@var{string}
2555 @itemx -translate-file=@var{tcxfile}
2557 These options are common to @TeX{}, Metafont, and MetaPost.
2558 @xref{Common options}.
2565 Set the @code{prologues} internal variable to @code{1}.
2567 @item -tex=@var{texprogram}
2568 @opindex -tex=@var{texprogram}
2569 When this option is given, the program @var{texprogram} is used to
2575 @node Initial MetaPost
2576 @section Initial MetaPost
2578 @cindex initial MetaPost
2579 @cindex MetaPost, initial
2581 As of MetaPost 1.504 (@TeX{} Live 2011), MetaPost no longer dumps
2582 @file{.mem} files (@pxref{Memory dumps}) and does not distinguish
2583 virgin and initial forms (@pxref{Initial and virgin}). Instead, the
2584 ``initial'' file name is read in its source form---that is,
2585 @file{mpost.mp} when the program is invoked as @command{mpost}.
2587 For a list of options and other information, see @ref{mpost invocation}.
2589 @cindex Metafont, compatibility in MetaPost
2590 @cindex plain Metafont, compatibility in MetaPost
2591 @cindex MetaPost and plain Metafont compatibility
2593 MetaPost provides a format with all the features of plain Metafont,
2594 called @file{mfplain}. You can use that in the same way; just run
2595 @command{mfplain} instead of @command{mpost}. This lets you directly
2596 process Metafont source files with MetaPost, producing character
2597 proofs (one file for each character) similar to those produced with
2598 Metafont in proof mode and GFtoDVI (@pxref{gftodvi invocation}).
2601 @node dvitomp invocation
2602 @section DVItoMP: DVI to MPX conversion
2605 @cindex DVI files, converting to MPX
2606 @cindex MPX files, converting from DVI files
2608 DVItoMP converts DVI files into low-level MetaPost commands in a
2609 so-called MPX file. Synopsis:
2612 dvitomp @var{dvifile}[.dvi] [@var{mpxfile}[.mpx]]
2616 If @var{mpxfile} is not specified, the output goes to the basename of
2617 @var{dvifile} extended with @file{.mpx}, e.g., @samp{dvitomp
2618 /wherever/foo.dvi} creates @file{./foo.mpx}.
2620 @cindex color, in DVItoMP
2621 DVItoMP supports Dvips-style color specials, such as @samp{color push
2622 @var{name}} and @samp{color pop}, outputting them as @code{withcolor}
2625 The only options are @samp{-help} and @samp{-version} (@pxref{Common
2630 @chapter Bib@TeX{}: Bibliographies
2632 @cindex bibliographies, creating
2635 Bib@TeX{} automates much of the job of typesetting bibliographies, and
2636 makes bibliography entries reusable in many different contexts.
2639 * bibtex invocation::
2640 * Basic BibTeX style files:: The standard and semi-standard styles.
2644 @node bibtex invocation
2645 @section Bib@TeX{} invocation
2649 @flindex .bbl @r{bibliography files}
2650 @flindex .aux @r{cross-reference files}
2651 @flindex .bib @r{bibliography databases}
2652 Bib@TeX{} creates a printable bibliography (@file{.bbl}) file from
2653 references in a @file{.aux} file, generally written by @TeX{} or
2654 @LaTeX{}. The @file{.bbl} file is then incorporated on a subsequent
2655 run. The basic bibliographic information comes from @file{.bib} files,
2656 and a Bib@TeX{} style (@file{.bst}) file controls the precise contents
2657 of the @file{.bbl} file. Synopsis:
2660 bibtex [@var{option}]@dots{} @var{auxfile}[.aux]
2663 @flindex .blg @r{Bib@TeX{} log file}
2664 @cindex log file, Bib@TeX{}
2666 The output goes to the basename of @var{auxfile} extended with
2667 @file{.bbl}; for example, @samp{bibtex /wherever/foo.aux} creates
2668 @file{./foo.bbl}. Bib@TeX{} also writes a log file to the basename of
2669 @var{auxfile} extended with @samp{.blg}.
2671 @findex \bibliography
2672 @findex \bibliographystyle
2673 @vindex TEXBIB@r{, search path for bib files}
2674 @vindex BIBINPUTS@r{, search path for bib files}
2675 @vindex BSTINPUTS@r{, search path for bst files}
2676 The names of the @file{.bib} and @file{.bst} files are specified in the
2677 @file{.aux} file as well, via the @file{\bibliography} and
2678 @file{\bibliographystyle} (La)@TeX{} macros. Bib@TeX{} searches for
2679 @file{.bib} files using the @code{BIBINPUTS} and @code{TEXBIB} paths,
2680 and for @file{.bst} files using @code{BSTINPUTS} (@pxref{Supported file
2681 formats,,,kpathsea,Kpathsea}). It does no path searching for
2684 The program accepts the following options, as well as the standard
2685 @samp{-help} and @samp{-version} (@pxref{Common options}):
2689 @cindex terse output
2690 @cindex verbose Bib@TeX{} output, suppressing
2691 Suppress the program banner and progress reports normally output.
2693 @item -min-crossrefs=@var{n}
2694 @opindex -min-crossrefs=@var{n}
2695 @cindex cross-referenced bibliography items
2696 @cindex bibliography items, cross-referenced
2697 If at least @var{n} (2 by default) bibliography entries refer to another
2698 entry @var{e} via their @code{crossref} field, include @var{e} in the
2699 @t{.bbl} file, even if it was not explicitly referenced in the @t{.aux}
2700 file. For example, @var{e} might be a conference proceedings as a whole,
2701 with the cross-referencing entries being individual articles published
2702 in the proceedings. In some circumstances, you may want to avoid these
2703 automatic inclusions altogether; to do this, make @var{n} a sufficiently
2711 Basic @LaTeX{}able documentation for general Bib@TeX{} users.
2715 @cindex style design, for Bib@TeX{}
2716 @LaTeX{}able documentation for style designers.
2720 Bib@TeX{} database file for the two above documents.
2724 Example database file with all the standard entry types.
2726 @item @url{ftp://ftp.math.utah.edu/pub/tex/bib/}
2727 @flindex ftp.math.utah.edu
2728 @cindex Bib@TeX{} collection
2729 @cindex TUGboat bibliography
2730 @cindex @TeX{}, bibliographies for
2731 A very large @file{.bib} and @file{.bst} collection, including
2732 references for all the standard @TeX{} books and a complete bibliography
2737 @node Basic BibTeX style files
2738 @section Basic Bib@TeX{} style files
2740 @cindex basic Bib@TeX{} style files
2741 @cindex Bib@TeX{} style files
2743 Here are descriptions of the four standard and four semi-standard basic
2744 Bib@TeX{} styles. @file{@var{CTAN:}/biblio/bibtex} contains these and
2745 many more (for CTAN info, @pxref{unixtex.ftp,,, kpathsea, Kpathsea}).
2750 Sorts entries alphabetically, with numeric labels. Generally formatted
2751 according to van Leunen's @cite{A Handbook for Scholars}. The other
2752 style files listed here are based on @code{plain}.
2756 First names, month names, and journal names are abbreviated.
2760 Names are printed in small caps.
2764 Alphanumeric labels, e.g., @samp{Knu66}.
2767 @flindex apalike.bst
2768 No labels at all; instead, the year appears in parentheses after the author.
2769 Use this in conjunction with @file{apalike.tex} (plain @TeX{}) or
2770 @file{apalike.sty} (@LaTeX{}), which also changes the citations in the
2771 text to be @samp{(@var{author}, @var{year})}.
2775 Numeric labels, entries in citation order, @sc{ieee} abbreviations,
2776 article titles in quotes.
2780 Numeric labels, alphabetic order, @cite{Math.@: Reviews}
2781 abbreviations, names in small caps.
2785 Lists entries in citation order, i.e., unsorted.
2788 The template file and documentation for the standard styles.
2794 @chapter WEB: Literate programming
2797 @cindex literate programming
2799 @dfn{WEB} languages allow you to write a single source file that can
2800 produce both a compilable program and a well-formatted document
2801 describing the program in as much detail as you wish to prepare.
2802 Writing in this kind of dual-purpose language is called @dfn{literate
2803 programming}. (The Usenet newsgroup @file{comp.programming.literate}
2804 is devoted to this subject.)
2810 @cindex Awk, WEB for
2811 @cindex Ada, WEB for
2812 @cindex Troff, WEB for
2813 WEB-like languages have been implemented with many pairs of base
2814 languages: Cweb provides C and Troff (@pxref{References}); CWEB provides
2815 C and @TeX{} (@file{@var{CTAN:}/web/c_cpp/cweb}); Spiderweb provides C,
2816 C++, Awk, Ada, many others, and @TeX{}
2817 (@file{@var{CTAN:}/web/spiderweb}); and, of course, the original WEB
2818 provides Pascal and @TeX{}, the implementation languages for the
2819 original @TeX{}, Metafont, MetaPost, and related programs to come from
2820 the @TeX{} project at Stanford.
2822 The original WEB language is documented in the file @file{webman.tex},
2823 which is included in the @url{ftp://ftp.tug.org/tex/lib.tar.gz} archive
2824 (and available in many other places, of course).
2827 * tangle invocation::
2828 * weave invocation::
2829 * pooltype invocation::
2833 @node tangle invocation
2834 @section Tangle: Translate WEB to Pascal
2837 @cindex Pascal, creating from WEB
2838 @cindex WEB programs, compiling
2840 Tangle creates a compilable Pascal program from a WEB source file
2841 (@pxref{WEB}). Synopsis:
2844 tangle [@var{option}]@dots{} @var{webfile}[.web] [@var{changefile}[.ch]]
2847 @cindex change files, and Tangle
2849 The Pascal output is written to the basename of @var{webfile} extended
2850 with @samp{.p}; for example, @samp{tangle /wherever/foo.web} creates
2851 @file{./foo.p}. Tangle applies @var{changefile} to @var{webfile} before
2852 writing the output; by default, there is no change file.
2854 @cindex pool file, writing
2855 @cindex string pool, writing
2856 If the program makes use of the WEB string facility, Tangle writes the
2857 string pool to the basename of @var{webfile} extended with @samp{.pool}.
2859 The Pascal output is packed into lines of 72 characters or less, with
2860 the only concession to readability being the termination of lines at
2861 semicolons when this can be done conveniently.
2863 The program accepts the following options, as well as the standard
2864 @samp{--help} and @samp{--version} (@pxref{Common options}):
2867 @item -length=@var{number}
2868 @opindex -length=@var{number}
2869 @cindex identifier length
2870 The number of characters that are considered significant in an
2871 identifier. Whether underline characters are counted depends on the
2872 @samp{-underline} option. The default value is 32, the original tangle
2873 used 7, but this proved too restrictive for use by Web2c.
2881 @cindex identifier case
2882 These options specify the case of identifiers in the output of tangle.
2883 If @samp{-uppercase} (@samp{-lowercase}) is specified, tangle will
2884 convert all identfiers to uppercase (lowercase). The default is
2885 @samp{-mixedcase}, which specifies that the case will not be changed.
2889 @cindex identifiers with underlines
2890 When this option is given, tangle does not strip underline characters
2897 @cindex identifier collisions
2898 These options specify how strict tangle must be when checking
2899 identifiers for equality. The default is @samp{-loose}, which means
2900 that tangle will follow the rules set by the case-smashing and underline
2901 options above. If @samp{-strict} is set, then identifiers will always
2902 be stripped of underlines and converted to uppercase before checking
2903 whether they collide.
2907 @node weave invocation
2908 @section Weave: Translate WEB to @TeX{}
2911 @cindex @TeX{}, creating from WEB
2912 @cindex WEB programs, typesetting
2913 @cindex prettyprinting WEB programs
2915 Weave creates a @TeX{} document from a WEB source file (@pxref{WEB}),
2916 assuming various macros defined in @file{webmac.tex}. It takes care of
2917 typographic details such as page layout, indentation, and italicizing
2918 identifiers. It also automatically gathers and outputs extensive
2919 cross-reference information. Synopsis:
2922 weave [@var{option}]@dots{} @var{webfile}[.web] [@var{changefile}[.ch]]
2925 @cindex change files, and Weave
2927 The output is to the basename of @var{webfile} extended with
2928 @samp{.tex}; for example, @samp{weave /wherever/foo.web} creates
2929 @file{./foo.tex}. Weave applies @var{changefile} to @var{webfile}
2930 before writing the output; by default, there is no change file.
2932 The program accepts the following option, as well as the standard
2933 @samp{-verbose}, @samp{-help} and @samp{-version} (@pxref{Common
2938 @cindex cross-references, omitting
2939 @flindex CONTENTS.tex
2941 Omit the cross-reference information: the index, the list of WEB module
2942 names, and the table of contents (an empty @file{CONTENTS.tex} file will
2943 still be written when the Weave output file is processed by @TeX{} using
2944 the default @file{webmac.tex}, though).
2947 Conventionally, WEB programmers should define the @TeX{} @code{\title}
2948 macro at the beginning of the source file. Also, to get output of only
2949 changed modules, one can say @code{\let\maybe=\iffalse} (usually as the
2950 first change in the change file).
2953 @node pooltype invocation
2954 @section Pooltype: Display WEB pool files
2957 @cindex type programs, pool
2958 @cindex string numbers, displaying
2959 @cindex WEB pool files, displaying
2961 Pooltype shows the so-called @dfn{string number} of each string in a WEB
2962 pool file (@pxref{WEB}), as output by Tangle (@pxref{tangle
2963 invocation}), including the first 256 strings corresponding to the
2964 possible input characters. Pooltype primarily serves as an example of
2965 WEB conventions to implementors of the @TeX{} system. Synopsis:
2968 pooltype [@var{option}]@dots{} @var{poolfile}[.pool]
2972 No path searching is done for @var{poolfile}. Output is to standard
2975 The only options are @samp{--help} and @samp{--version} (@pxref{Common
2978 As an example of the output, here is the (edited) output for @file{tex.pool}:
2986 1314: "Using character substitution: "
2987 (23617 characters in all.)
2990 @cindex representation of strings
2991 @cindex string representation
2992 In Metafont and MetaPost, the first 256 characters are actually
2993 represented as single bytes (i.e., themselves), not in the @samp{^^}
2994 notation. Consider Pooltype as showing the results after conversion for
2999 @chapter DVI utilities
3001 @cindex DVI utilities
3003 @TeX{} outputs a file in @dfn{DVI} (DeVice Independent) format as a
3004 compact representation of the original document. DVI files can be
3005 translated to meet the requirements of a real physical device, such as
3006 PostScript printers (@pxref{Top,, Introduction, dvips, Dvips}), PCL
3007 printers (see dvilj(1)), and X displays (see xdvi(1)). In fact, DVI
3008 translators are available for virtually all common devices: see
3009 @file{@var{CTAN:}/dviware} (for CTAN info, @pxref{unixtex.ftp,,,
3010 kpathsea, Kpathsea}).
3012 @flindex dvitype.web
3013 @cindex DVI format definition
3014 For the precise definition of the DVI file format, see (for example) the
3015 source file @file{web2c/dvitype.web}.
3017 The DVI-processing programs in the Web2c distribution are not device
3018 drivers; they perform generic utility functions.
3021 * dvicopy invocation:: Expand virtual fonts.
3022 * dvitype invocation:: DVI to human-readable text.
3025 @node dvicopy invocation
3026 @section DVIcopy: Canonicalize virtual font references
3029 @cindex virtual fonts, expanding
3031 DVIcopy reads a DVI file, expands any references to virtual fonts
3032 (@pxref{Virtual fonts,,, dvips, Dvips}) to base fonts, and writes the
3033 resulting DVI file. Thus you can use virtual fonts even if your DVI
3034 processor does not support them, by passing the documents through
3035 DVIcopy first. Synopsis:
3038 dvicopy [@var{option}]@dots{} [@var{indvi}[.dvi] [@var{outdvi}[.dvi]]]
3041 DVIcopy reads standard input if @var{indvi} is not specified, and writes
3042 standard output if @var{outdvi} is not specified.
3044 The program accepts the following options, as well as the standard
3045 @samp{-help} and @samp{-version} (@pxref{Common options}):
3047 @item -magnification=@var{integer}
3048 @opindex -magnification=@var{integer}
3049 @cindex magnification
3051 Override existing magnification in @var{indvi} with @var{integer}; 1000
3052 specifies no magnification. This is equivalent to setting @TeX{}'s
3053 @code{\mag} parameter.
3055 @item -max-pages=@var{n}
3056 @opindex -max-pages=@var{n}
3057 Process @var{n} pages; default is one million.
3059 @item -page-start=@var{page-spec}
3060 @opindex -page-start=@var{page-spec}
3061 @cindex starting page
3062 @cindex page, starting
3063 @findex \count@var{n}
3064 Start at the first page matching @var{page-spec}, which is one or more
3065 (signed) integers separated by periods, corresponding to @TeX{}'s
3066 @code{\count0@dots{}9} parameters at @code{\shipout} time; @samp{*}
3067 matches anything. Examples: @samp{3}, @samp{1.*.-4}.
3071 @node dvitype invocation
3072 @section DVItype: Plain text transliteration of DVI files
3074 @pindex dvitype @r{DVI validation}
3075 @cindex conversion, DVI to plain text
3076 @cindex plain text, converting DVI to
3077 @cindex human-readable text, converting DVI to
3078 @cindex type programs, DVI
3079 @cindex validation, of DVI files
3081 DVItype translates a DeVice Independent (DVI) file (as output by @TeX{},
3082 for example) to a plain text file that humans can read. It also serves
3083 as a DVI-validating program, i.e., if DVItype can read a file, it's
3087 dvitype [@var{option}]@dots{} @var{dvifile}[.dvi]
3091 DVItype does not read any bitmap files, but it does read TFM files for
3092 fonts referenced in @var{dvifile}. The usual places are searched
3093 (@pxref{Supported file formats,,, kpathsea, Kpathsea}). To see all the
3094 relevant paths, set the environment variable @code{KPATHSEA_DEBUG} to
3095 @samp{-1} before running the program.
3097 Output goes to standard output.
3099 The program accepts the following options, as well as the standard
3100 @samp{-help} and @samp{-version} (@pxref{Common options}):
3102 @item -dpi=@var{real}
3103 @opindex -dpi=@var{real}
3104 Do pixel movement calculations at @var{real} pixels per inch; default
3107 @item -magnification=@var{integer}
3108 @opindex -magnification=@var{integer}
3109 @cindex magnification
3111 Override existing magnification in @var{indvi} with @var{integer}; 1000
3112 specifies no magnification. This is equivalent to setting @TeX{}'s
3113 @code{\mag} parameter.
3115 @item -max-pages=@var{n}
3116 @opindex -max-pages=@var{n}
3117 Process @var{n} pages; default is one million.
3119 @item -output-level=@var{n}
3120 @opindex -output-level=@var{n}
3121 Verbosity level of output, from 0 to 4 (default 4):
3123 @item 0: Global document information only.
3124 @item 1: Most DVI commands included, and typeset characters summarized.
3125 @item 2: Character and movement commands explicitly included.
3126 @item 3: DVI stack and current position calculations included.
3127 @item 4: Same information as level 3, but DVItype does random positioning
3128 in the file, reading the DVI postamble first.
3131 @item -page-start=@var{page-spec}
3132 @opindex -page-start=@var{page-spec}
3133 @cindex starting page
3134 @cindex page, starting
3135 @findex \count@var{n}
3136 Start at the first page matching @var{page-spec}, which is one or more
3137 (signed) integers separated by periods, corresponding to @TeX{}'s
3138 @code{\count0@dots{}9} parameters at @code{\shipout} time; @samp{*}
3139 matches anything. Examples: @samp{1}, @samp{5.*.-9}.
3142 @opindex -show-opcodes
3143 @cindex opcodes, showing DVI
3144 @cindex DVI opcodes, showing
3145 @cindex debugging DVI utilities
3146 Show numeric opcode values (in decimal) for DVI commands, in braces
3147 after the command name. This can help in debugging DVI utilities. We
3148 use decimal because in the DVI format documentation (in
3149 @file{dvitype.web}, among others) the opcodes are shown in decimal.
3153 * dvitype output example::
3157 @node dvitype output example
3158 @subsection DVItype output example
3160 @cindex dvitype output example
3161 As an example of the output from DVItype (see section above), here is
3162 its (abridged) translation of the @file{story.dvi} resulting from
3163 running the example in @cite{The @TeX{}book}, with
3164 @samp{-output-level=4} and @samp{-show-opcodes} on.
3170 Maximum number of pages = 1000000
3171 Output level = 4 (the works)
3172 Resolution = 300.00000000 pixels per inch
3173 numerator/denominator=25400000/473628672
3174 magnification=1000; 0.00006334 pixels per DVI unit
3175 ' TeX output 1992.05.17:0844'
3176 Postamble starts at byte 564.
3177 maxv=43725786, maxh=30785863, maxstackdepth=3, totalpages=1
3178 Font 33: cmsl10---loaded at size 655360 DVI units
3179 Font 23: cmbx10---loaded at size 655360 DVI units
3180 Font 0: cmr10---loaded at size 655360 DVI units
3182 42: beginning of page 1
3184 level 0:(h=0,v=0,w=0,x=0,y=0,z=0,hh=0,vv=0)
3185 88: down3 -917504 @{159@} v:=0-917504=-917504, vv:=-58
3188 104: putrule @{137@} height 26214, width 30785863 (2x1950 pixels)
3189 113: down3 5185936 @{159@} v:=655360+5185936=5841296, vv:=370
3191 level 1:(h=0,v=5841296,w=0,x=0,y=0,z=0,hh=0,vv=370)
3192 118: right4 12265425 @{146@} h:=0+12265425=12265425, hh:=777
3194 123: fntdef1 23 @{243@}: cmbx10
3195 145: fntnum23 @{194@} current font is cmbx10
3196 146: setchar65 h:=12265425+569796=12835221, hh:=813
3197 147: w3 251220 @{150@} h:=12835221+251220=13086441, hh:=829
3198 151: setchar83 h:=13086441+418700=13505141, hh:=856
3200 164: setchar82 h:=17448202+565245=18013447, hh:=1142
3201 165: x0 -62805 @{152@} h:=18013447-62805=17950642, hh:=1138
3202 166: setchar89 h:=17950642+569796=18520438, hh:=1174
3205 level 1:(h=0,v=5841296,w=0,x=0,y=0,z=0,hh=0,vv=370)
3208 level 0:(h=0,v=42152922,w=0,x=0,y=0,z=0,hh=0,vv=2670)
3209 551: down3 1572864 @{159@} v:=42152922+1572864=43725786, vv:=2770
3211 level 0:(h=0,v=43725786,w=0,x=0,y=0,z=0,hh=0,vv=2770)
3212 556: right4 15229091 @{146@} h:=0+15229091=15229091, hh:=965
3213 561: setchar49 h:=15229091+327681=15556772, hh:=986
3216 level 0:(h=0,v=43725786,w=0,x=0,y=0,z=0,hh=0,vv=2770)
3224 The DVItype options are recorded at the beginning, followed by
3225 global information about the document, including fonts used.
3228 Each DVI command is preceded by its byte position in the file
3229 (@samp{42:}, @samp{87:}, @dots{}), and (because of the
3230 @samp{-show-opcodes}) followed by its decimal opcode value in braces
3231 (@samp{@{141@}}, @samp{@{142@}}, @dots{}).
3234 The @samp{level} lines record information about the DVI stack; @samp{h}
3235 and @samp{v} define the current position in DVI units, while @samp{hh}
3236 and @samp{vv} are the same in pixels.
3239 Text sequences are summarized in brackets, as in @samp{[A SHORT
3240 STORY]} and the @samp{[ 1]}.
3244 @node Font utilities
3245 @chapter Font utilities
3247 @cindex font utilities
3249 The Web2c programs described here convert between various @TeX{}-related
3250 font formats; the first section below briefly describes the
3251 formats. GFtoPK is the only one that is routinely used, as Metafont
3252 outputs GF format, but it's most efficient for device drivers to use PK.
3256 @cindex PK format definition
3257 @cindex GF format definition
3258 The precise definitions of the PK, GF, TFM, PL, VF, and VPL formats
3259 mentioned below are in the source files that read them;
3260 @file{pktype.web}, @file{gftype.web}, @file{tftopl.web}, etc.
3263 * Font file formats:: Explanations of GF, PK, TFM, VF, ...
3264 * gftopk invocation:: GF -> PK (compact)
3265 * pktogf invocation:: PK -> GF (expand).
3266 * pktype invocation:: PK -> human-readable text.
3267 * gftype invocation:: GF -> human-readable text.
3268 * tftopl invocation:: TFM -> PL (for editing TFM).
3269 * pltotf invocation:: PL -> TFM (make editing results usable).
3270 * vftovp invocation:: VF -> VPL (tftopl for virtual fonts).
3271 * vptovf invocation:: VPL -> VF (pltotf for virtual fonts).
3272 * Font utilities available elsewhere:: Type 1, BDF, editors, etc.
3276 @node Font file formats
3277 @section Font file formats
3279 @cindex font file formats
3280 @cindex file formats for fonts
3282 (For another perspective on this, @pxref{Font concepts,,, dvips,
3285 Font files come in several varieties, with suffixes like:
3287 .tfm .*pk .*gf .*pxl@r{ (obsolete)} .pl .mf .vf .vpl
3290 Each represents a file format.
3292 @cindex TFM files, explained
3293 A TFM (@TeX{} font metric) file is a compact binary file that contains
3294 information about each character in a font, about combinations of
3295 characters within that font, and about the font as a whole. The font
3296 metric information contained in TFM files is device-independent units is
3297 used by @TeX{} to do typesetting. Unlike the bitmap (raster) fonts
3298 described below, TFM font files contain no information about the shapes
3299 of characters. They describe rectangular areas and combinations
3300 thereof, but not what will eventually be printed in those areas.
3302 @cindex scaling of fonts
3303 @cindex optical font scaling
3304 @cindex geometric font scaling
3305 @cindex PostScript, and font scaling
3306 Since @TeX{} does scaling calculations, one TFM file serves for all
3307 magnifications of a given typeface. On the other hand, the best printed
3308 results are obtained when magnified (or reduced fonts) are not produced
3309 geometrically (as done by PostScript, for example) but rather optically,
3310 with each size a separate design (as done with Computer Modern and the
3311 EC fonts, for example); then a separate TFM file is needed for each
3314 @cindex DVI files, explained
3315 At any rate, @TeX{} produces a DVI (DeVice Independent) file from your
3316 source document. In order to print DVI files on real devices, you need
3317 font files defining digitized character shapes and other data. Then
3318 previewers and printer-driver programs can translate your DVI files into
3319 something usable by your monitor or printer. Bitmap fonts come with
3320 suffixes such as @samp{.600pk} or @samp{.600gf} or @samp{.3000pxl}, where
3321 the @samp{600} is the horizontal dots-per-inch resolution at which the
3322 font was produced, and the @samp{pk} or @samp{gf} or @samp{pxl}
3323 indicates the font format. Outline fonts in PostScript Type 1 format
3324 have suffixes such as @samp{.pfa} or @samp{.pfb}.
3326 @cindex PXL files, explained
3327 @cindex PK files, explained
3328 @cindex GF files, explained
3329 Fonts in pk (packed) format are in the tightly packed raster format that
3330 is pretty much the standard today. They take up less space than fonts
3331 in the gf (generic font) format that Metafont generates, and far less
3332 space than fonts in pxl format. Fonts in pxl format take up gross
3333 amounts of disk space and permit only 128 characters. They are
3336 @cindex PL files, explained
3337 Font files with the @samp{.pl} (property list) suffix are the plain text
3338 (human-readable) analog of the binary @samp{.tfm} files.
3339 The TFtoPL and PLtoTF programs convert between the two formats
3340 (@pxref{tftopl invocation} and @ref{pltotf invocation}).
3342 Font files with the @samp{.mf} suffix are in Metafont source format.
3343 These are the files used by Metafont to generate rastered fonts for
3344 specific typefaces at specific magnifications for the specific
3345 resolution and type of mapping used by your device.
3347 @flindex virtual-fonts.knuth
3348 @flindex virtualfonts.txt
3349 The suffix @samp{.vf} identifies ``virtual font'' files, for which
3350 @samp{.vpl} is the human-readable analog. See @xref{vftovp invocation},
3351 and @ref{vptovf invocation}. For further discussion of virtual fonts,
3352 see @file{@var{CTAN:}/doc/virtual-fonts.knuth},
3353 @file{@var{CTAN:}/help/virtualfonts.txt}, and @ref{Virtual fonts,,,
3356 @cindex MacKay, Pierre
3357 @cindex Tachikawa, Elizabeth
3358 (This section is based on documentation in the original Unix @TeX{}
3359 distribution by Pierre MacKay and Elizabeth Tachikawa.)
3362 @node gftopk invocation
3363 @section GFtoPK: Generic to packed font conversion
3366 @cindex conversion, GF to PK
3367 @cindex PK, converting GF to
3368 @cindex GF, converting to PK
3370 GFtoPK converts a generic font (GF) file output by, for example,
3371 Metafont (@pxref{mf invocation}) to a packed font (PK) file. PK files
3372 are considerably smaller than the corresponding gf files, so they are
3373 generally the bitmap font format of choice. Some DVI-processing
3374 programs, notably Dvips, only support PK files and not GF files.
3378 gftopk [@var{option}]@dots{} @var{gfname}.@var{dpi}[gf] [@var{pkfile}]
3382 The font @var{gfname} is searched for in the usual places (@pxref{Glyph
3383 lookup,,, kpathsea, Kpathsea}). To see all the relevant paths, set the
3384 environment variable @code{KPATHSEA_DEBUG} to @samp{-1} before running
3387 The suffix @samp{gf} is supplied if not already present. This suffix is
3388 not an extension; no @samp{.} precedes it: for instance,
3391 If @var{pkfile} is not specified, the output is written to the basename
3392 of @samp{@var{gfname}.@var{dpi}pk}, e.g., @samp{gftopk
3393 /wherever/cmr10.600gf} creates @file{./cmr10.600pk}.
3395 The only options are @samp{--verbose}, @samp{--help}, and
3396 @samp{--version} (@pxref{Common options}).
3399 @node pktogf invocation
3400 @section PKtoGF: Packed to generic font conversion
3403 @cindex conversion, PK to GF
3404 @cindex GF, converting PK to
3405 @cindex PK, converting to GF
3407 PKtoGF converts a packed font (PK) file to a generic font (GF) file.
3408 Since PK format is much more compact than GF format, the most likely
3409 reason to do this is to run GFtype (@pxref{gftype invocation}) on the
3410 result, so you can see the bitmap images. Also, a few old utility
3411 programs do not support PK format. Synopsis:
3414 pktogf [@var{option}]@dots{} @var{pkname}.@var{dpi}[pk] [@var{gffile}]
3418 The font @var{pkname} is searched for in the usual places (@pxref{Glyph
3419 lookup,,, kpathsea, Kpathsea}). To see all the relevant paths, set the
3420 environment variable @code{KPATHSEA_DEBUG} to @samp{-1} before running
3423 The suffix @samp{pk} is supplied if not already present. This suffix is
3424 not an extension; no @samp{.} precedes it: for instance,
3427 If @var{gffile} is not specified, the output is written to the basename
3428 of @samp{@var{pkname}.@var{dpi}gf}, e.g., @samp{pktogf
3429 /wherever/cmr10.600pk} creates @file{./cmr10.600gf}.
3431 The only options are @samp{--verbose}, @samp{--help}, and
3432 @samp{--version} (@pxref{Common options}).
3435 @node pktype invocation
3436 @section PKtype: Plain text transliteration of packed fonts
3438 @pindex pktype @r{PK validation}
3439 @cindex conversion, PK to plain text
3440 @cindex plain text, converting PK to
3441 @cindex human-readable text, converting PK to
3442 @cindex type programs, PK
3443 @cindex validation, of PK files
3445 PKtype translates a packed font (PK) bitmap file (as output by GFtoPK,
3446 for example) to a plain text file that humans can read. It also serves
3447 as a PK-validating program, i.e., if PKtype can read a file, it's
3451 pktype @var{pkname}.@var{dpi}[pk]
3454 The font @var{pkname} is searched for in the usual places (@pxref{Glyph
3455 lookup,,, kpathsea, Kpathsea}). To see all the relevant paths, set the
3456 environment variable @code{KPATHSEA_DEBUG} to @samp{-1} before running
3459 The suffix @samp{pk} is supplied if not already present. This suffix is
3460 not an extension; no @samp{.} precedes it: for instance, @file{cmr10.600pk}.
3462 The translation is written to standard output.
3464 The only options are @samp{-help} and @samp{-version}
3465 (@pxref{Common options}).
3467 As an example of the output, here is the (abridged) translation of the
3468 letter `K' in @samp{cmr10}, as rendered at 600@dmn{dpi} with the mode
3469 @samp{ljfour} from @url{modes.mf} (available from
3470 @file{ftp://ftp.tug.org/tex/modes.mf}).
3473 955: Flag byte = 184 Character = 75 Packet length = 174
3474 Dynamic packing variable = 11
3475 TFM width = 815562 dx = 4259840
3476 Height = 57 Width = 57 X-offset = -3 Y-offset = 56
3477 [2]23(16)17(8)9(25)11(13)7(27)7(16)7(28)4(18)7(28)2(20)7(27)@dots{}
3479 (14)9(24)12(5)[2]23(13)21
3487 @cindex byte position
3488 The byte position in the file where this character starts.
3491 @itemx Dynamic packing variable
3493 @cindex dynamic packing variable
3494 Related to the packing for this character; see the source code.
3497 @cindex character codes, in PKtype output
3498 The character code, in decimal.
3501 @cindex packet length
3502 The total length of this character definition, in bytes.
3505 @cindex TFM width of characters
3506 @cindex device-independent width
3507 @cindex width, device-independent
3508 The device-independent (TFM) width of this character. It is 2^24
3509 times the ratio of the true width to the font's design size.
3512 @cindex horizontal escapement
3513 @cindex escapement, horizontal
3514 @cindex scaled pixels
3515 @cindex dx @r{horizontal escapement}
3516 The device-dependent width, in @dfn{scaled pixels}, i.e., units of
3517 horizontal pixels times 2^16.
3521 @cindex height, in pixels
3522 @cindex pixel height
3524 @cindex width, in pixels
3525 The bitmap height and width, in pixels.
3532 @cindex reference pixel
3533 @cindex side bearings
3534 @cindex left side bearing
3535 @cindex right side bearing
3536 Horizontal and vertical offset from the upper left pixel to the
3537 reference (origin) pixel for this character, in pixels (right and down
3538 are positive). The @dfn{reference pixel} is the pixel that occupies the
3539 unit square in Metafont; the Metafont reference point is the lower left
3540 hand corner of this pixel. Put another way, the x-offset is the negative
3541 of the left side bearing; the right side bearing is the horizontal
3542 escapement minus the bitmap width plus the x-offset.
3544 @item [2]23(16)@dots{}
3545 @cindex run length encoded bitmaps
3546 @cindex repeated rows
3547 Finally, run lengths of black pixels alternate with parenthesized run
3548 lengths of white pixels, and brackets indicate a repeated row.
3552 @node gftype invocation
3553 @section GFtype: Plain text transliteration of generic fonts
3555 @pindex gftype @r{GF validation}
3556 @cindex conversion, GF to plain text
3557 @cindex plain text, converting GF to
3558 @cindex human-readable text, converting GF to
3559 @cindex type programs, GF
3560 @cindex validation, of GF files
3562 GFtype translates a generic font (GF) bitmap file (as output by
3563 Metafont, for example) to a plain text file that humans can read. It
3564 also serves as a GF-validating program, i.e., if GFtype can read a file,
3565 it's correct. Synopsis:
3568 gftype [@var{option}]@dots{} @var{gfname}.@var{dpi}[gf]
3571 The font @var{gfname} is searched for in the usual places (@pxref{Glyph
3572 lookup,,, kpathsea, Kpathsea}). To see all the relevant paths, set the
3573 environment variable @code{KPATHSEA_DEBUG} to @samp{-1} before running
3576 The suffix @samp{gf} is supplied if not already present. This suffix is
3577 not an extension; no @samp{.} precedes it: for instance, @file{cmr10.600gf}.
3579 The translation is written to standard output.
3581 The program accepts the following options, as well as the standard
3582 @samp{-help} and @samp{-version} (@pxref{Common options}):
3586 Show the characters' bitmaps using asterisks and spaces.
3590 Translate all commands in the GF file.
3593 As an example of the output, here is the (abrdiged) translation of the
3594 letter `K' in @samp{cmr10}, as rendered at 600@dmn{dpi} with the mode
3595 @samp{ljfour} from @file{modes.mf} (available from
3596 @url{ftp://ftp.tug.org/tex/modes.mf}), with both @samp{-mnemonics} and
3597 @samp{-images} enabled.
3599 GFtype outputs the information about a character in two places: a main
3600 definition and a one-line summary at the end. We show both. Here is the
3604 2033: beginning of char 75: 3<=m<=60 0<=n<=56
3605 (initially n=56) paint (0)24(12)20
3606 2043: newrow 0 (n=55) paint 24(12)20
3607 2047: newrow 0 (n=54) paint 24(12)20
3608 2051: newrow 0 (n=53) paint 24(12)20
3609 2055: newrow 7 (n=52) paint 10(21)13
3610 2059: newrow 8 (n=51) paint 8(23)9
3612 2249: newrow 8 (n=5) paint 8(23)11
3613 2253: newrow 7 (n=4) paint 10(22)12
3614 2257: newrow 0 (n=3) paint 24(11)22
3615 2261: newrow 0 (n=2) paint 24(11)22
3616 2265: newrow 0 (n=1) paint 24(11)22
3617 2269: newrow 0 (n=0) paint 24(11)22
3620 .<--This pixel's lower left corner is at (3,57) in METAFONT coordinates
3621 ************************ ********************
3622 ************************ ********************
3623 ************************ ********************
3624 ************************ ********************
3625 ********** *************
3628 ******** ***********
3629 ********** ************
3630 ************************ **********************
3631 ************************ **********************
3632 ************************ **********************
3633 ************************ **********************
3634 .<--This pixel's upper left corner is at (3,0) in METAFONT coordinates
3645 @cindex byte position
3646 The byte position in the file where each GF command starts.
3648 @item beginning of char 75
3649 @cindex character codes, in GFtype output
3650 The character code, in decimal.
3652 @item 3<=m<=60 0<=n<=56
3653 @cindex left side bearing
3654 @cindex right side bearing
3655 @cindex side bearings
3656 The character's bitmap lies between 3 and 60 (inclusive) horizontally,
3657 and between 0 and 56 (inclusive) vertically. (@math{m} is a column
3658 position and @math{n} is a row position.) Thus, 3 is the left side
3659 bearing. The right side bearing is the horizontal escapement (given
3660 below) minus the maximum @math{m}.
3662 @item (initially n=56) paint (0)24(12)20
3663 @cindex run length encoded bitmaps
3664 The first row of pixels: 0 white pixels, 24 black pixels, 12 white
3667 @item newrow 0 (n=55) paint 24(12)20
3668 @findex newrow @r{GF command}
3669 The second row of pixels, with zero leading white pixels on the row.
3672 @findex eoc @r{GF command}
3673 The end of the main character definition.
3677 Here is the GF postamble information that GFtype outputs at the end:
3680 Character 75: dx 4259840 (65), width 815562 (64.57289), loc 2033
3687 @cindex horizontal escapement
3688 @cindex escapement, horizontal
3689 @cindex vertical escapement
3690 @cindex escapement, vertical
3691 @cindex scaled pixels
3692 @cindex dx @r{horizontal escapement}
3693 @cindex dy @r{vertical escapement}
3694 The device-dependent width, in @dfn{scaled pixels}, i.e., units of
3695 horizontal pixels times 2^16. The @samp{(65)} is simply the same number
3696 rounded. If the vertical escapement is nonzero, it would appear here as
3700 @cindex TFM width of characters
3701 @cindex device-independent width
3702 @cindex width, device-independent
3703 The device-independent (TFM) width of this character. It is 2^24
3704 times the ratio of the true width to the font's design size. The
3705 @samp{64.57289} is the same number converted to pixels.
3708 The byte position in the file where this character starts.
3713 @node tftopl invocation
3714 @section TFtoPL: @TeX{} font metric to property list conversion
3717 @cindex conversion, TFM to property list
3718 @cindex validation, of TFM files
3719 @cindex property list, converting TFM to
3720 @cindex human-readable text, converting TFM to
3721 @cindex plain text, converting TFM to
3723 TFtoPL translates a @TeX{} font metric (TFM, @pxref{Metric
3724 files,,,dvips,Dvips}) file (as output by Metafont, for example) to
3725 @dfn{property list format} (a list of parenthesized items describing the
3726 font) that humans can edit or read. This program is mostly used by
3727 people debugging @TeX{} implementations, writing font utilities, etc.
3731 tftopl [@var{option}]@dots{} @var{tfmname}[.tfm] [@var{plfile}[.pl]]
3734 The font @var{tfmname} (extended with @samp{.tfm} if necessary) is
3735 searched for in the usual places (@pxref{Supported file formats,,,
3736 kpathsea, Kpathsea}). To see all the relevant paths, set the
3737 environment variable @code{KPATHSEA_DEBUG} to @samp{-1} before running
3740 If @var{plfile} (which is extended with @samp{.pl} if necessary) is not
3741 specified, the property list file is written to standard output. The
3742 property list file can be converted back to TFM format by the companion
3743 program TFtoPL (see the next section).
3745 The program accepts the following option, as well as the standard
3746 @samp{-verbose}, @samp{-help} and @samp{-version} (@pxref{Common
3749 @item -charcode-format=@var{type}
3750 @opindex -charcode-format=@var{type}
3751 Output character codes in the PL file according to @var{type}: either
3752 @samp{octal} or @samp{ascii}. Default is @samp{ascii} for letters and
3753 digits, octal for all other characters. Exception: if the font's coding
3754 scheme starts with @samp{TeX math sy} or @samp{TeX math ex}, all
3755 character codes are output in octal.
3757 In @samp{ascii} format, character codes that correspond to graphic
3758 characters, except for left and right parentheses, are output as a
3759 @samp{C} followed by the single character: @samp{C K}, for example. In
3760 octal format, character codes are output as the letter @samp{O} followed
3761 by octal digits, as in @samp{O 113} for @samp{K}.
3763 @samp{octal} format is useful for symbol and other non-alphabetic fonts,
3764 where using ASCII characters for the character codes is merely
3768 @cindex property list format
3769 As an example of the output, here is the (abridged) property list
3770 translation of @file{cmr10.tfm}:
3775 (CODINGSCHEME TEX TEXT)
3777 (COMMENT DESIGNSIZE IS IN POINTS)
3778 (COMMENT OTHER SIZES ARE MULTIPLES OF DESIGNSIZE)
3779 (CHECKSUM O 11374260171)
3783 (STRETCH R 0.166667)
3785 (XHEIGHT R 0.430555)
3787 (EXTRASPACE R 0.111112)
3795 (KRN O 47 R 0.077779)
3796 (KRN O 77 R 0.077779)
3797 (KRN O 41 R 0.077779)
3798 (KRN O 51 R 0.077779)
3799 (KRN O 135 R 0.077779)
3812 (KRN O 47 R 0.077779)
3813 (KRN O 77 R 0.077779)
3820 As you can see, the general format is a list of parenthesized
3821 @dfn{properties}, nested where necessary.
3825 @findex FAMILY @r{property}
3826 @findex FACE @r{property}
3827 @findex headerbyte @r{information}
3828 The first few items (@code{FAMILY}, @code{FACE}, and so on) are
3829 the so-called @dfn{headerbyte} information from Metafont, giving general
3830 information about the font.
3833 @findex FAMILY @r{property}
3835 The @code{FONTDIMEN} property defines the @TeX{} @code{\fontdimen}
3839 @findex LIGTABLE @r{property}
3840 @findex LABEL @r{property}
3841 @findex LIG @r{property}
3842 @findex KRN @r{property}
3843 @cindex ligature table, in TFM files
3844 @cindex kerning table, in TFM files
3845 @cindex design-size units
3846 The @code{LIGTABLE} property defines the ligature and kerning table.
3847 @code{LIG} properties define ligatures: in the example above, an
3848 @samp{f} (in the @samp{LABEL}) followed by an @samp{i} is a ligature,
3849 i.e., a typesetting program like @TeX{} replaces those two consecutive
3850 characters by the character at position octal '014 in the current
3851 font---presumably the `fi' ligature. @code{KRN} properties define
3852 kerns: if an @samp{f} is followed by character octal '047 (an
3853 apostrophe), @TeX{} inserts a small amount of space between them:
3854 0.077779 times the design size the font was loaded at (about
3855 three-quarters of a printer's point by default in this case, or .001
3859 @findex CHARACTER @r{property}
3860 @findex CHARWD @r{property}
3861 @findex CHARHT @r{property}
3862 @findex CHARDP @r{property}
3863 @findex CHARIC @r{property}
3864 The @code{CHARACTER} property defines the dimensions of a character: its
3865 width, height, depth, and italic correction, also in design-size units,
3866 as explained in the previous item. For our example `f', the depth is
3867 zero, so that property is omitted. TFtoPL also inserts any kerns and
3868 ligatures for this character as a comment.
3873 @node pltotf invocation
3874 @section PLtoTF: Property list to @TeX{} font metric conversion
3877 @cindex conversion, property list to TFM
3878 @cindex TFM files, converting property lists to
3879 @cindex machine-readable, converting property lists to
3881 PLtoTF translates a property list file (as output by TFtoPL, for
3882 example) to @TeX{} font metric (TFM, @pxref{Metric files,,,dvips,Dvips})
3883 format. It's much easier for both programs and humans to create the
3884 (plain text) property list files and let PLtoTF take care of creating
3885 the binary TFM equivalent than to output TFM files directly. Synopsis:
3888 pltotf [@var{option}]@dots{} @var{plfile}[.pl] [@var{tfmfile}[.tfm]]
3891 If @var{tfmfile} (extended with @samp{.tfm} if necessary) is
3892 not specified, the TFM file is written to the basename of
3893 @samp{@var{plfile}.tfm}, e.g., @samp{pltotf /wherever/cmr10.pl} creates
3894 @file{./cmr10.tfm}. (Since TFM files are binary, writing to standard
3895 output by default is undesirable.)
3897 The only options are @samp{-verbose}, @samp{-help}, and
3898 @samp{-version} (@pxref{Common options}).
3900 For an example of property list format, see the previous section.
3903 @node vftovp invocation
3904 @section VFtoVP: Virtual font to virtual property lists
3907 @cindex conversion, VF to VPL
3908 @cindex validation, of VF files
3909 @cindex property list, converting VF to virtual
3910 @cindex human-readable text, converting VF to
3911 @cindex plain text, converting VF to
3913 VFtoVP translates a virtual font metric (VF, @pxref{Virtual
3914 fonts,,,dvips,Dvips}) file and its accompanying @TeX{} font metric (TFM,
3915 @pxref{Metric files,,,dvips,Dvips}) file (as output by VPtoVF, for
3916 example) to @dfn{virtual property list format} (a list of parenthesized
3917 items describing the virtual font) that humans can edit or read. This
3918 program is mostly used by people debugging virtual font utilities.
3922 vftovp [@var{option}]@dots{} @var{vfname}[.vf] [@var{tfmname}[.tfm] @c
3923 [@var{vplfile}[.vpl]]]
3926 The fonts @var{vfname} and @var{tfmname} (extended with @samp{.vf} and
3927 @samp{.tfm} if necessary) are searched for in the usual places
3928 (@pxref{Supported file formats,,, kpathsea, Kpathsea}). To see all the
3929 relevant paths, set the environment variable @code{KPATHSEA_DEBUG} to
3930 @samp{-1} before running the program. If @var{tfmname} is not
3931 specified, @var{vfname} (without a trailing @samp{.vf}) is used.
3933 If @var{vplfile} (extended with @samp{.vpl} if necessary) is
3934 not specified, the property list file is written to standard output.
3935 The property list file can be converted back to VF and TFM format by the
3936 companion program VFtoVP (see the next section).
3938 The program accepts the following option, as well as the standard
3939 @samp{-verbose}, @samp{-help} and @samp{-version} (@pxref{Common
3942 @item -charcode-format=@var{type}
3943 @opindex -charcode-format=@var{type}
3944 Output character codes in the PL file according to @var{type}: either
3945 @samp{octal} or @samp{ascii}. Default is @samp{ascii} for letters and
3946 digits, octal for all other characters. Exception: if the font's coding
3947 scheme starts with @samp{TeX math sy} or @samp{TeX math ex}, all
3948 character codes are output in octal.
3950 In @samp{ascii} format, character codes that correspond to graphic
3951 characters, except for left and right parentheses, are output as a
3952 @samp{C} followed by the single character: @samp{C K}, for example. In
3953 octal format, character codes are output as the letter @samp{O} followed
3954 by octal digits, as in @samp{O 113} for @samp{K}.
3956 @samp{octal} format is useful for symbol and other non-alphabetic fonts,
3957 where using ASCII characters for the character codes is merely
3962 @node vptovf invocation
3963 @section VPtoVF: Virtual property lists to virtual font
3966 @cindex conversion, property list to VF
3967 @cindex VF files, converting property lists to
3968 @cindex machine-readable, converting property lists to
3970 VPtoVF translates a virtual property list file (as output by VFtoVP, for
3971 example) to virtual font (VF, @pxref{Virtual fonts,,,dvips,Dvips}) and
3972 @TeX{} font metric (TFM, @pxref{Metric files,,,dvips,Dvips}) files.
3973 It's much easier for both programs and humans to create the (plain text)
3974 property list files and let VPtoVF take care of creating the binary VF
3975 and TFM equivalents than to output them directly. Synopsis:
3978 vptovf [@var{option}]@dots{} @var{vplfile}[.vpl] [@var{vffile}[.vf] @c
3979 [@var{tfmfile}[.tfm]]]
3982 If @var{vffile} (extended with @samp{.vf} if necessary) is not
3983 specified, the VF output is written to the basename of
3984 @samp{@var{vplfile}.vf}; similarly for @var{tfmfile}. For example,
3985 @samp{vptovf /wherever/ptmr.vpl} creates @file{./ptmr.vf} and
3988 The only options are @samp{-verbose}, @samp{-help}, and @samp{-version}
3989 (@pxref{Common options}).
3992 @node Font utilities available elsewhere
3993 @section Font utilities available elsewhere
3995 @cindex font utilities, non-Web2c
3997 The Web2c complement of font utilities merely implements a few basic
3998 conversions. Many other more sophisticated font utilities exist; most
3999 are in @file{@var{CTAN:}/fonts/utilities} (for CTAN info,
4000 @pxref{unixtex.ftp,,, kpathsea, Kpathsea}). Here are some of the most
4001 commonly-requested items:
4005 @cindex AFM to TFM conversion
4008 AFM (Adobe font metric) to TFM conversion: @pxref{Invoking afm2tfm,,,
4009 dvips, Dvips}, and @file{@var{CTAN:}/fonts/utilities/afmtopl}.
4012 @cindex X bitmap fonts
4013 @cindex BDF and GF conversion
4014 BDF (the X bitmap format) conversion:
4015 @url{ftp://ftp.tug.org/tex/bdf.tar.gz}.
4019 @cindex Latin Modern
4020 Creating fonts using MetaPost: MetaType1.
4021 @url{ftp://bop.eps.gda.pl/pub/metatype1}. This is used to create
4022 the excellent Latin Modern font family (@file{@var{CTAN:}/fonts/lm}),
4023 which extends Computer Modern to a vast repertoire of scripts.
4026 @cindex editing of bitmap fonts
4027 @pindex xbfe@r{, bitmap font editor}
4028 @pindex xfed@r{, bitmap font editor}
4029 @pindex xfedor@r{, bitmap font editor}
4033 Editing of bitmap fonts: Xbfe from the GNU font utilities mentioned
4034 below; the X BDF-editing programs available from
4035 @url{ftp://ftp.x.org/R5contrib/xfed.tar.Z} and
4036 @url{ftp://ftp.x.org/R5contrib/xfedor.tar.Z}; and finally, if your
4037 fonts have only 128 characters, you can use the old @code{gftopxl},
4038 @code{pxtoch}, and @code{chtopx} programs from
4039 @url{ftp://ftp.tug.org/tex/web}.
4044 Editing of outline fonts: FontForge, @url{fontforge.sourceforge.net}.
4045 This is a very elaborate program with support for many outline formats
4046 (Type@tie{}1, OpenType, TrueType, @dots{}), and many advanced font
4050 @cindex PK bitmaps from PostScript
4051 @cindex PostScript to PK bitmaps
4054 PK bitmaps from PostScript outline fonts: gsftopk from the @samp{xdvi}
4055 distribution. Alternatively, @code{ps2pk}, from
4056 @file{@var{CTAN:}/fonts/utilities/ps2pk}.
4059 @cindex Type 1 conversion
4060 @cindex PFA and PFB conversion
4061 @cindex PostScript Type 1 font conversion
4062 PostScript Type 1 font format conversion (i.e., between PFA and PFB
4063 formats): @url{http://www.lcdf.org/type}.
4066 @cindex scanned images of fonts
4067 @cindex typeface specimen sheets
4069 Scanned image conversion: the (aging) GNU font utilities convert type
4070 specimen images to Metafont, PostScript, etc.:
4071 @url{http://www.gnu.org/software/fontutils/}.
4076 Tracing bitmaps to fitted outlines: Autotrace
4077 (@url{http://autotrace.sourceforge.net}), Potrace
4078 (@url{http://potrace.sourceforge.net}). For Metafont fonts, either of
4079 the two programs @code{mftrace}
4080 (@url{http://www.xs4all.nl/~hanwen/mftrace}) or @code{textrace}
4081 (@url{http://textrace.sourceforge.net}) make the job easier.
4084 @cindex virtual font creation
4085 @pindex fontinst@r{, for creating virtual fonts}
4086 Virtual font creation: @file{@var{CTAN:}/fonts/utilities/fontinst}.
4094 @cindex copyright notices
4095 @cindex permissions, legal
4097 In general, each file has its own copyright notice stating the copying
4098 permissions for that file. Following is a summary.
4100 The Web2c system itself and most of the original WEB source files are
4103 @file{tex.web}, the ML@TeX{} code, @file{mf.web}, and @file{bibtex.web},
4104 are copyrighted by their authors. They may be copied verbatim, but may
4105 be modified only through a @file{.ch} file.
4107 MetaPost-related files, including @file{mp.web} itself, are copyrighted
4108 under X-like terms; the precise notice is included below.
4110 Finally, the Kpathsea library is covered by the GNU Lesser General
4111 Public License (@pxref{Introduction,,, kpathsea, Kpathsea}). Therefore,
4112 the @emph{binaries} resulting from a standard Web2c compilation are also
4113 covered by the LGPL; so if you (re)distribute the binaries, you must
4114 also (offer to) distribute the complete source that went into those
4115 binaries. See the file @file{LGPL} for complete details on the LGPL.
4117 The following notice must be included by the terms of the MetaPost
4121 Permission to use, copy, modify, and distribute this software and its
4122 documentation for any purpose and without fee is hereby granted,
4123 provided that the above copyright notice appear in all copies and that
4124 both that the copyright notice and this permission notice and warranty
4125 disclaimer appear in supporting documentation, and that the names of
4126 AT&T Bell Laboratories or any of its entities not be used in advertising
4127 or publicity pertaining to distribution of the software without
4128 specific, written prior permission.
4130 AT&T disclaims all warranties with regard to this software, including
4131 all implied warranties of merchantability and fitness. In no event
4132 shall AT&T be liable for any special, indirect or consequential damages
4133 or any damages whatsoever resulting from loss of use, data or profits,
4134 whether in an action of contract, negligence or other tortious action,
4135 arising out of or in connection with the use or performance of this
4141 @appendix References
4144 @cindex bibliography
4148 Kpathsea: @xref{Top, Introduction,, kpathsea, Kpathsea}.
4151 Dvips and Afm2tfm: @xref{Top, Introduction,, dvips, Dvips}.
4154 The @TeX{} Users Group: @url{http://www.tug.org}. For an introduction
4155 to the @TeX{} system, see @url{http://tug.org/begin.html}.
4158 TUGboat: @url{http://tug.org/TUGboat}.
4161 @TeX{} and computer typesetting in general:@*
4162 @url{ftp://ftp.math.utah.edu/pub/tex/bib/texbook1.bib}.
4165 For a bibliography of formal articles and technical reports on the
4166 @TeX{} project, see the books @cite{@TeX{}: The Program} or
4167 @cite{Metafont: The Program} cited below.