diff options
Diffstat (limited to 'Build/source/texk/web2c/doc/web2c.texi')
-rw-r--r-- | Build/source/texk/web2c/doc/web2c.texi | 4353 |
1 files changed, 0 insertions, 4353 deletions
diff --git a/Build/source/texk/web2c/doc/web2c.texi b/Build/source/texk/web2c/doc/web2c.texi deleted file mode 100644 index f96ed0d6a0a..00000000000 --- a/Build/source/texk/web2c/doc/web2c.texi +++ /dev/null @@ -1,4353 +0,0 @@ -\input texinfo -@setfilename web2c.info -@settitle Web2c: A @TeX{} implementation - -@tex -\expandafter\ifx\csname url\endcsname\relax - \errhelp{You must update texinfo.tex to at least version 3.8. -The latest version is available from ftp://ftp.tug.org/tex/texinfo.tex.} - \errmessage{Your texinfo.tex is too old} - \csname bye\expandafter\endcsname -\fi -@end tex - -@set version 2021 -@set month-year February 2021 - -@c Define new indices for commands in auxiliary files, filenames, and options. -@defcodeindex cm -@defcodeindex fl -@defcodeindex op - -@c Put everything in one index (arbitrarily chosen to be the concept index). -@syncodeindex cm cp -@syncodeindex fl cp -@syncodeindex fn cp -@syncodeindex ky cp -@syncodeindex op cp -@syncodeindex pg cp -@syncodeindex vr cp - -@dircategory TeX -@direntry -* Web2c: (web2c). TeX, Metafont, and companion programs. -@end direntry -@dircategory Individual utilities -@direntry -* bibtex: (web2c)bibtex invocation. Maintaining bibliographies. -* dvicopy: (web2c)dvicopy invocation. Virtual font expansion -* dvitomp: (web2c)dvitomp invocation. DVI to MPX (MetaPost pictures). -* dvitype: (web2c)dvitype invocation. DVI to human-readable text. -* gftodvi: (web2c)gftodvi invocation. Generic font proofsheets. -* gftopk: (web2c)gftopk invocation. Generic to packed fonts. -* gftype: (web2c)gftype invocation. GF to human-readable text. -* mf: (web2c)mf invocation. Creating typeface families. -* mft: (web2c)mft invocation. Prettyprinting Metafont source. -* mltex: (web2c)MLTeX. Multi-lingual TeX. -* mpost: (web2c)mpost invocation. Generating PostScript. -* patgen: (web2c)patgen invocation. Creating hyphenation patterns. -* pktogf: (web2c)pktogf invocation. Packed to generic fonts. -* pktype: (web2c)pktype invocation. PK to human-readable text. -* pltotf: (web2c)pltotf invocation. Property list to TFM. -* pooltype: (web2c)pooltype invocation. Display WEB pool files. -* tangle: (web2c)tangle invocation. WEB to Pascal. -* tex: (web2c)tex invocation. Typesetting. -* tftopl: (web2c)tftopl invocation. TFM -> property list. -* vftovp: (web2c)vftovp invocation. Virtual font -> virtual pl. -* vptovf: (web2c)vptovf invocation. Virtual pl -> virtual font. -* weave: (web2c)weave invocation. WEB to TeX. -@end direntry - -@copying -This file documents the installation and use of the programs in Web2c, -an implementation of Donald Knuth's TeX system. - -Copyright @copyright{} 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, -2004, 2005, 2007, 2008, 2009, 2010-2021 Karl Berry & Olaf Weber. - -Permission is granted to make and distribute verbatim copies of this -manual provided the copyright notice and this permission notice are -preserved on all copies. - -@ignore -Permission is granted to process this file through TeX and print the -results, provided the printed document carries a copying permission -notice identical to this one except for the removal of this paragraph -(this paragraph not being relevant to the printed manual). -@end ignore - -Permission is granted to copy and distribute modified versions of this -manual under the conditions for verbatim copying, provided that the -entire resulting derived work is distributed under the terms of a -permission notice identical to this one. - -Permission is granted to copy and distribute translations of this manual -into another language, under the above conditions for modified versions, -except that this permission notice may be stated in a translation -@end copying - - -@titlepage -@title Web2c -@subtitle for version @value{version} -@subtitle @value{month-year} -@author Karl Berry -@author Olaf Weber -@author @url{https://tug.org/web2c} - -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top -@top Web2c - -This document describes how to install and use the programs in the Web2c -implementation of the @TeX{} system, especially for Unix systems. It -corresponds to Web2c version @value{version}, released in -@value{month-year}. - -@menu -* Introduction:: A brief introduction. -* Installation:: How to compile and install Web2c. -* Commonalities:: Option syntax, standard options, memory dumps. -* Three programs:: TeX, Metafont, MetaPost have much in common. -* TeX:: Typesetting. -* Metafont:: Typeface design. -* MetaPost:: Technical illustrations. -* BibTeX:: Reusable bibliographies. -* WEB:: Literate programming. -* DVI utilities:: DVI expansion. -* Font utilities:: Font format conversion. -* Legalisms:: Blah blah blah. -* References:: Books and such. -* Index:: General index. -@end menu -@end ifnottex - - -@node Introduction -@chapter Introduction - -@cindex introduction - -This manual corresponds to version @value{version} of Web2c, released in -@value{month-year}. - -@cindex Knuth, Donald E. -@cindex @TeX{}, Web2c implementation of -@cindex Hobby, John -@cindex Breitenlohner, Peter -@dfn{Web2c} is the name of a @TeX{} implementation, originally for -Unix, but now also running under various operating systems. By -@dfn{@TeX{} implementation}, we mean all of the standard programs -developed by the Stanford @TeX{} project directed by Donald E. Knuth: -Metafont, DVItype, GFtoDVI, Bib@TeX{}, Tangle, etc., as well as @TeX{} -itself. Other programs are also included: DVIcopy, written by Peter -Breitenlohner, MetaPost and its utilities (derived from Metafont), by -John Hobby, etc. - -@cindex translation from WEB to C -@cindex strategy, overall -General strategy: Web2c works, as its name implies, by translating the -WEB source in which @TeX{} is written into C source code. Its output is -not self-contained, however; it makes extensive use of many macros and -functions in a library (the @file{web2c/lib} directory in the sources). -Therefore, it will not work without change on an arbitrary WEB program. - -@cindex licensing terms -@cindex freedom of Web2c -@cindex ice cream -Availability: All of Web2c is freely available---``free'' both in the -sense of no cost (free ice cream) and of having the source code to -modify and/or redistribute (free speech). @xref{unixtex.ftp,,, -kpathsea, Kpathsea}, for the practical details of how to obtain Web2c. - -Different parts of the Web2c distribution have different licensing -terms, however, reflecting the different circumstances of their -creation; consult each source file for exact details. The main -practical implication for redistributors of Web2c is that most of the -executables are covered by the GNU General Public License or GNU -Lesser General Public License, and therefore anyone who gets a binary -distribution must also be able to get the sources, as explained by the -terms of the GPL (@url{https://gnu.org/licenses/}. The GPL covers the -Web2c executables, including @code{tex}, because the Free Software -Foundation sponsored the initial development of the Kpathsea library -that Web2c uses. The basic source files from Stanford, however, have -their own copyright terms or are in the public domain, and are not -covered by the GPL. - -@cindex history -@cindex Rokicki, Tomas -@cindex Trickey, Howard -@cindex Curtis, Pavel -@cindex Morgan, Tim -@cindex Berry, Karl -@cindex Weber, Olaf -History: Tomas Rokicki originated the @TeX{}-to-C system in 1987, -working from the first change files for @TeX{} under Unix, which were -done primarily by Howard Trickey and Pavel Curtis. Tim Morgan then -took over development and maintenance for a number of years; the name -changed to Web-to-C somewhere in there. In 1990, Karl Berry became -the maintainer. He made many changes to the original sources, and -started using the shorter name Web2c. In 1997, Olaf Weber took over, -and then in 2006, Karl started taking care of it again. No -significant development or changes have been needed for many -years. Dozens of other people have contributed; their names are listed -in the @file{ChangeLog} files. - -@cindex acknowledgements -@cindex Martin, Rick -@cindex Morris, Bob -@cindex Stallman, Richard -Other acknowledgements by Karl: The University of Massachusetts at Boston -(particularly Rick Martin and Bob Morris) provided computers and ftp -access to me for many years. Richard Stallman at the Free Software -Foundation employed me while I wrote the original path searching library -(for the GNU font utilities). (rms also gave us Emacs, GDB, and GCC, -without which I cannot imagine developing Web2c.) And, of course, -@TeX{} would not exist in the first place without Donald E. Knuth. - -@cindex reading, additional -Further reading: @xref{References}. - - -@include install.texi - - -@node Commonalities -@chapter Commonalities - -@cindex commonalities - -Many aspects of the @TeX{} system are the same among more than one -program, so we describe those pieces together, here. - -@menu -* Option conventions:: -- or -, = or ` ' for values. -* Common options:: --help --version --verbose, and TeX/MF/MP options. -* Path searching:: Features of the common path searching library. -* Output file location:: TEXMFOUTPUT allows output in places other than `.'. -@end menu - - -@node Option conventions -@section Option conventions - -@cindex option conventions -@cindex conventions for options, - -@findex getopt_long_only -To provide a clean and consistent behavior, we chose to have all these -programs use the GNU function @code{getopt_long_only} to parse command -lines. However, we do use in a restricted mode, where all the options -have to come before the rest of the arguments. - -@opindex - @r{starts option names} -@opindex -- @r{starts option names} -As a result, you can: -@itemize @bullet -@item -use @samp{-} or @samp{--} to start an option name; - -@item -use any unambiguous abbreviation for an option name; - -@item -separate option names and values with either @samp{=} or one or more -spaces; - -@item -@flindex - @r{starting a filename} -@cindex filenames starting with @samp{-} -use filenames that would otherwise look like options by putting them -after an option @samp{--}. -@end itemize - -By convention, non-option arguments, if specified, generally define the -name of an input file, as documented for each program. - -If a particular option with a value is given more than once, it is the -last value that counts. - -For example, the following command line specifies the options -@samp{foo}, @samp{bar}, and @samp{verbose}; gives the value @samp{baz} -to the @samp{abc} option, and the value @samp{xyz} to the @samp{quux} -option; and specifies the filename @file{-myfile-}. - -@example --foo --bar -verb -abc=baz -quux karl --quux xyz -- -myfile- -@end example - - -@node Common options -@section Common options - -@cindex common options -All of these programs accept the standard GNU @samp{--help} and -@samp{--version} options, and several programs accept -@samp{--verbose}. Rather than writing identical descriptions for -every program, they are described here. - -@table @samp -@item --help -@opindex --help @r{common option} -@cindex help, online -Print a usage message listing basic usage and all available options to -standard output, then exit successfully. - -@item --verbose -@opindex --verbose @r{common option} -@cindex verbosity, enabling -Print progress reports to standard output. - -@item --version -@opindex --version @r{common option} -@cindex version number, finding -Print the version number to standard output, then exit successfully. -@end table - -@TeX{}, Metafont, and MetaPost have a number of additional options in -common: - -@table @samp -@item -cnf-line=@var{str} -@opindex -cnf-line -Parse @var{str} as if it were a line in the @file{texmf.cnf} -configuration file, overriding all other settings. @xref{Path -searching options,,,kpathsea,Kpathsea}. - -@item -file-line-error -@opindex -file-line-error -@itemx -no-file-line-error -@opindex -no-file-line-error -@opindex -file-line-error-style -@cindex changing error messages style -Change (or do not change) the way error messages are printed. The -alternate style looks like error messages from many compilers and is -easier to parse for some editors that invoke @TeX{}. This option used -to be called @samp{-file-line-error-style}. - -@item -fmt=@var{dumpname} -@itemx -base=@var{dumpname} -@itemx -mem=@var{dumpname} -@opindex -fmt=@var{dumpname} -@opindex -base=@var{dumpname} -@opindex -mem=@var{dumpname} -@cindex dump file -Use @var{dumpname} instead of the program name or a @samp{%&} line to -determine the name of the memory dump file read (@samp{fmt} for @TeX{}, -@samp{base} for Metafont, @samp{mem} for MetaPost). @xref{Memory -dumps}. Also sets the program name to @var{dumpname} if no -@samp{-progname} option was given. - -@item -halt-on-error -@opindex -halt-on-error -@cindex stopping at the first error -Stop processing and exit when an error occurs, as opposed to the normal -process of trying to recover and continue. - -@item -ini -@opindex -ini -@cindex program names, special -@cindex initial form, enabling -Enable the ``initial'' form of the program (@pxref{Initial and -virgin}). This is implicitly set if the program name is @code{initex} -resp.@: @code{inimf}. - -@item -interaction=@var{string} -@opindex -interaction=@var{string} -@cindex interaction mode -Set the interaction mode from the command line. The @var{string} must -be one of @samp{batchmode}, @samp{nonstopmode}, @samp{scrollmode}, or -@samp{errorstopmode}. - -@item -jobname=@var{string} -@opindex -jobname=@var{string} -@cindex job name -Set the job name to @var{string}, instead of deriving it from the name -of the input file. - -@item -kpathsea-debug=@var{number} -@opindex -kpathsea-debug=@var{number} -@vindex KPATHSEA_DEBUG -@cindex debugging flags, specifying -@cindex path searching debugging -Set path searching debugging flags according to the bits of @var{number} -(@pxref{Debugging,,,kpathsea,Kpathsea}). You can also specify this in -@code{KPATHSEA_DEBUG} environment variable (for all Web2c programs). -(The command line value overrides.) The most useful value is @samp{-1}, -to get all available output. - -@item -output-directory=@var{dirname} -@opindex -output-directory -@cindex output directory, specifying -Specify the directory @var{dirname} to which output files are written. -Also look for input files in @var{dirname} first, before looking along -the normal search path. @xref{Output file location}. - -@item -parse-first-line -@opindex -parse-first-line -@itemx -no-parse-first-line -@opindex -no-parse-first-line -@cindex parsing the first line -Check or disable checking whether the first line of the main input -file starts with @samp{%&}, and parse it if it does. This line can be -used specify the format and/or a TCX file. - -@item -progname=@var{string} -@opindex -progname=@var{string} -@cindex binaries, linking -@cindex linking binaries -@cindex program names, special -Set program (and memory dump) name to @var{string}. This may affect the -search paths and other values used (@pxref{Config files,,, kpathsea, -Kpathsea}). Using this option is equivalent to making a link named -@var{string} to the binary and then invoking the binary under that -name. @xref{Memory dumps}. - -@item -recorder -@opindex -recorder -@cindex file recorder -Enable the filename recorder. This makes the program save a list of the -opened files into a file with (by default) extension @samp{.fls}. For -Aleph, this option is always on, and the file has extension @samp{.ofl}. - -Ordinarily, the @samp{.fls} file is written to the same location as -the @samp{.log} file, for example, respecting -@option{-output-directory} if it is given (@pxref{Output file -location}). However, if @TeX{} processing is done on the command line -(or in response to the @samp{**} prompt), the @samp{.fls} might be -written to the current directory, or include an integer (the current -pid), as in @file{texput1234.fls}. You can use @option{-jobname} to -explicitly set the basename. - -@item -translate-file=@var{tcxfile} -@opindex -translate-file=@var{tcxfile} -@cindex translation file for @TeX{}, specifying -@flindex .tcx @r{character translation files} -@cindex first line of the main input file -Use @var{tcxfile} to define which characters are printable and translations -between the internal and external character sets. Moreover, -@var{tcxfile} can be explicitly declared in the first line of the main -input file @samp{%& -translate-file=@var{tcxfile}}. -This is the recommended method for portability reasons. -@xref{TCX files}. - -@item -8bit -@opindex -8bit -@cindex 8 bit clean -@flindex 8 bit clean output, specifying -This option specifies that by default all characters should be -considered printable. If @samp{-translate-file} was given as well, -then the TCX file may mark characters as non-printable. This is a -no-op in engines natively supporting Unicode. - -@end table - - -@node Path searching -@section Path searching - -@cindex path searching - -@flindex texmf.cnf -@cindex configuration file reading -All of the Web2c programs, including @TeX{}, which do path searching use -the Kpathsea routines to do so. The precise names of the environment -and configuration file variables which get searched for particular file -formatted are therefore documented in the Kpathsea manual -(@pxref{Supported file formats,,, kpathsea, Kpathsea}). Reading -@file{texmf.cnf} (@pxref{Config files,,, kpathsea, Kpathsea}), invoking -@code{mktex@dots{}} scripts (@pxref{mktex scripts,,, kpathsea, -Kpathsea}), and so on are all handled by Kpathsea. - -@cindex font aliases -@cindex aliases for fonts -@flindex texfonts.map -The programs which read fonts make use of another Kpathsea feature: -@file{texfonts.map}, which allows arbitrary aliases for the actual names -of font files; for example, @samp{Times-Roman} for @samp{ptmr8r.tfm}. -The distributed (and installed by default) @file{texfonts.map} includes -aliases for many widely available PostScript fonts by their PostScript -names. - - -@node Output file location -@section Output file location - -@cindex output file location -@cindex current directory, used for output -@flindex .@r{, used for output} -All the programs generally follow the usual convention for output files. -Namely, they are placed in the directory current when the program is -run, regardless of any input file location; or, in a few cases, output -is to standard output. - -For example, if you run @samp{tex /tmp/foo}, for example, the output -will be in @file{./foo.dvi} and @file{./foo.log}, not -@file{/tmp/foo.dvi} and @file{/tmp/foo.log}. - -@opindex -output-directory -@cindex output directory, specifying -@cindex readonly directory, running @TeX{} in -You can use the @samp{-output-directory} option to cause all output -files that would normally be written in the current directory to be -written in the specified directory instead. @xref{Common options}. - -@vindex TEXMFOUTPUT@r{, used if @samp{.} unwritable} -@cindex readonly directory, running @TeX{} in -If the current directory is not writable, and @samp{-output-directory} -is not specified, the main programs (@TeX{}, Metafont, MetaPost, and -Bib@TeX{}) make an exception: if the config file or environment -variable value @code{TEXMFOUTPUT} is set (it is not by default), -output files are written to the directory specified. - -@vindex TEXMFOUTPUT@r{, used for reading} -@code{TEXMFOUTPUT} is also checked for input files, as @TeX{} often -generates files that need to be subsequently read; for input, no -suffixes (such as @samp{.tex}) are added by default and no exhaustive -path searching is done, the input name is -simply checked as given. - - -@node Three programs -@chapter Three programs: Metafont, MetaPost, and @TeX{} - -@cindex three programs -@cindex @TeX{}, Metafont, and MetaPost -@cindex Metafont, MetaPost, and @TeX{} -@cindex MetaPost, @TeX{}, and Metafont - -@TeX{}, Metafont, and MetaPost have a number of features in common. -Besides the ones here, command-line options and other commonalities -are described in the previous section. - -@menu -* Runtime options:: The @file{texmf.cnf} configuration file. -* Initial and virgin:: Making memory dumps vs. production runs. -* Memory dumps:: .fmt/.base files for fast startup. -* Editor invocation:: The `e' response at errors. -* \input filenames:: Filename delimiters and Kpathsea expansion. -@end menu - - -@node Runtime options -@section Runtime options - -@cindex runtime options - -@cindex configuration file values -@cindex array sizes -@flindex texmf.cnf -Besides the configure- and compile-time options described in the -installation section (@pxref{Installation}), you can control a number -of parameters in the @file{texmf.cnf} runtime file read by Kpathsea -(@pxref{Config files,,, kpathsea, Kpathsea}). - -The main purpose of @file{texmf.cnf} is to specify search paths, but -array sizes and other options are also set there. Most are rather -obscure. Here are a few of the more interesting values: - -@vtable @samp -@item main_memory -Total words of memory available, for @TeX{}, Metafont, and MetaPost. -Must remake the format file after changing. - -@item extra_mem_bot -@cindex boxes, memory for -@cindex glue, memory for -@cindex breakpoints, memory for -@cindex PiC@TeX{}, increasing memory for -Extra space for ``large'' @TeX{} data structures (default 0): boxes, -glue, breakpoints, et al. If you use PiC@TeX{}, you may well want to -set this. - -@item expand_depth -@cindex recursive expansion limit -@cindex expansion limit, recursive -@cindex runtime stack overflow -@cindex overflow, of runtime stack -@cindex segmentation fault -@vindex SIGSEGV -Limit on recursive expansion calls before @TeX{} aborts (default -10000). If a @TeX{} program does an unterminated recursive expansion, -@TeX{} will dutifully expand macros until the system's runtime stack -overflows, typically with a segmentation fault (SIGSEGV). This -parameter was introduced to minimize the chance of that unpleasant -(though not dangerous) crash, instead allowing @TeX{} to quit with a -more informative message. - -@pindex libsigsegv @r{library} -The crash can still happen, though, if the system has an exceptionally -small memory allocation for its stack. There is no quantitative way to -determine the limit, and it does not seem worth implementing -system-dependent heuristics to guess at the number, since it's highly -improbable that any real @TeX{} code will ever need more than 10000 -recursive expansions (it has never happened). For the same reason, -using the libsigsegv library (@url{https://gnu.org/s/libsigsegv}) does -not seem worth the effort. - -@item texmf_casefold_search -@xref{Casefolding search,,, kpathsea, Kpathsea}. - -@end vtable - -@cindex array limit, fixed -@cindex swap space, as array limit -@cindex reallocation of arrays -@cindex dynamic array allocation -Ideally all arrays would be dynamically expanded as necessary, so the -only limiting factor would be the amount of swap space available, or -some configurable limit much larger than can currently be supported. - -Unfortunately, implementing this is extremely difficult, as the fixed -size of arrays is assumed in many places throughout the source code. -These runtime limits are a practical compromise between the -compile-time limits in previous versions, and truly dynamic arrays. -(On the other hand, the Web2c Bib@TeX{} implementation does do true -dynamic reallocation of some arrays.) - -@cindex modifying @file{texmf.cnf} in @TeX{} Live -@cindex location of @file{texmf.cnf} in @TeX{} Live -Nowadays there is rarely a reason to modify the values. But if you do -wish to modify @file{texmf.cnf}, in @TeX{} Live the best approach is -to put your changes, and only your changes at the top of the TL -installation tree. That is, if the system @file{texmf.cnf} is -installed in -@file{/some/path/to/texlive/YYYY/texmf-dist/web2c/texmf.cnf} is put -your custom settings in @file{/some/path/to/texlive/YYY/texmf.cnf}, -where @var{YYYY} is the year of installation (if you use that -subdirectory; it's the default). That way, unrelated changes to the -system @file{texmf.cnf} can happen with normal updates, without -affecting your local values. - - -@node Initial and virgin -@section Initial and virgin - -@cindex executables, shared initial and virgin -The @TeX{} and Metafont programs each have two main variants, called -@dfn{initial} and @dfn{virgin}. MetaPost no longer makes this -distinction. - -The initial form is enabled if: -@enumerate -@item -@opindex -ini -the @samp{-ini} option was specified; or -@item -the program name is @file{initex} resp.@: @file{inimf}; or -@item -the first line of the main input file is @samp{%&ini}; -@end enumerate -@noindent -otherwise, the virgin form is used. - -@cindex virgin programs -@cindex production use -The @dfn{virgin} form is the one generally invoked for production use. -The first thing it does is read a memory dump (@pxref{Determining the -memory dump to use}), and then proceeds on with the main job. - -@cindex initial programs -@cindex initializations, lengthy -The @dfn{initial} form is generally used only to create memory dumps -(see the next section). It starts up more slowly than the virgin form, -because it must do lengthy initializations that are encapsulated in the -memory dump file. - - -@node Memory dumps -@section Memory dumps - -@cindex memory dumps - -@cindex dumping memory -@cindex macros, predefining in memory dumps -@cindex predefined macros and memory dumps -In typical use, @TeX{} and Metafont require a large number of -macros to be predefined; therefore, they support @dfn{memory dump} -files, which can be read much more efficiently than ordinary source -code. - -@menu -* Creating memory dumps:: -* Determining the memory dump to use:: -* Hardware and memory dumps:: -@end menu - - -@node Creating memory dumps -@subsection Creating memory dumps - -@cindex memory dumps, creating -@cindex creating memory dumps -@cindex writing memory dumps - -The programs all create memory dumps in slightly idiosyncratic (thought -substantially similar) way, so we describe the details in separate -sections (references below). The basic idea is to run the initial -version of the program (@pxref{Initial and virgin}), read the source -file to define the macros, and then execute the @code{\dump} primitive. - -Also, each program uses a different filename extension for its memory -dumps, since although they are completely analogous they are not -interchangeable (@TeX{} cannot read a Metafont memory dump, for -example). - -Here is a list of filename extensions with references to examples of -creating memory dumps: - -@table @asis -@item @TeX{} -(@samp{.fmt}) @xref{Initial TeX,,Initial @TeX{}}. - -@item Metafont -(@samp{.base}) @xref{Initial Metafont}. -@end table - -When making memory dumps, the programs read environment variables and -configuration files for path searching and other values as usual. If -you are making a new installation and have environment variables -pointing to an old one, for example, you will probably run into -difficulties. - - -@node Determining the memory dump to use -@subsection Determining the memory dump to use - -@cindex memory dump to use, determining -@cindex fmt file, determining -@cindex base file, determining -@cindex mem file, determining - -The virgin form (@pxref{Initial and virgin}) of each program always -reads a memory dump before processing normal source input. All three -programs determine the memory dump to use in the same way: - -@enumerate -@item -If the first non-option command-line argument begins with @samp{&}, the -program uses the remainder of that argument as the memory dump name. -For example, running @samp{tex \&super} reads @file{super.fmt}. (The -backslash protects the @samp{&} against interpretation by the shell.) - -@item -@opindex -fmt=@var{fmt} -@opindex -base=@var{base} -If the @samp{-fmt} resp.@: @samp{-base} option is -specified, its value is used. - -@item -@opindex -progname=@var{string} -If the @samp{-progname} option is specified, its value is used. - -@item -@kindex %& @r{magic number} -If the first line of the main input file (which must be specified on the -command line, not in response to @samp{**}) is @code{%&@var{dump}}, and -@var{dump} is an existing memory dump of the appropriate type, -@var{dump} is used. - -The first line of the main input file can also specify which character -translation file is to be used: @code{%&-translate-file=@var{tcxfile}} -(@pxref{TCX files}). - -These two roles can be combined: @code{%&@var{dump} --translate-file=@var{tcxfile}}. If this is done, the name of the dump -must be given first. - -@item -@cindex program name, determines memory dump -@cindex links to binaries -Otherwise, the program uses the program invocation name, most commonly -@file{tex} resp.@: @file{mf}. For example, if @file{latex} is a link -to @file{tex}, and the user runs @samp{latex foo}, @file{latex.fmt} -will be used. - -@end enumerate - - -@node Hardware and memory dumps -@subsection Hardware and memory dumps - -@cindex hardware and memory dumps -@cindex memory dumps and hardware -@cindex sharing memory dumps -@cindex fmt files, sharing -@cindex base files, sharing -@cindex mem files, sharing - -@cindex LittleEndian machines -@cindex BigEndian machines -@cindex endian dependencies -@cindex machine dependencies -@cindex architecture dependencies -@cindex dependencies, hardware -@opindex --disable-dump-share configure @r{option} -By default, memory dump files are generally sharable between -architectures of different types; specifically, on machines of different -endianness (@pxref{Byte order,,,libc,GNU C Library}). (This is a -feature of the Web2c implementation, and is not true of all @TeX{} -implementations.) If you specify @samp{--disable-dump-share} to -@code{configure}, however, memory dumps will be endian-dependent. - -@cindex byte swapping -@cindex swapping bytes -The reason to do this is speed. To achieve endian-independence, the -reading of memory dumps on LittleEndian architectures, such as PC's and -DEC architectures, is somewhat slowed (all the multibyte values have to -be swapped). Usually, this is not noticeable, and the advantage of -being able to share memory dumps across all platforms at a site far -outweighs the speed loss. But if you're installing Web2c for use on -LittleEndian machines only, perhaps on a PC being used only by you, you -may wish to get maximum speed. - -@cindex floating-point values -@cindex glue ratio representations -@TeX{}nically, even without @samp{--disable-dump-share}, sharing of -@file{.fmt} files cannot be guaranteed to work. Floating-point values -are always written in native format, and hence will generally not be -readable across platforms. Fortunately, @TeX{} uses floating point -only to represent glue ratios, and all common formats (plain, -@LaTeX{}, AMS@TeX{}, @dots{}) do not do any glue setting at -@file{.fmt}-creation time. Metafont does not use floating point in -any dumped value at all. - -@cindex date and time, in memory dumps -@cindex time and date, in memory dumps -@cindex memory dumps, contain date and time -Incidentally, different memory dump files will never compare equal -byte-for-byte, because the program always dumps the current date and -time. So don't be alarmed by just a few bytes difference. - -@cindex Harbison, Samuel P. -@cindex Steele Jr., Guy L. -If you don't know what endianness your machine is, and you're curious, -here is a little C program to tell you. (The @code{configure} script -contains a similar program.) This is from the book @cite{C: A Reference -Manual}, by Samuel P. Harbison and Guy L. Steele -Jr@:. (@pxref{References}). - -@example -main () -@{ - /* Are we little or big endian? From Harbison&Steele. */ - union - @{ - long l; - char c[sizeof (long)]; - @} u; - u.l = 1; - if (u.c[0] == 1) - printf ("LittleEndian\n"); - else if (u.c[sizeof (long) - 1] == 1) - printf ("BigEndian\n"); - else - printf ("unknownEndian"); - - exit (u.c[sizeof (long) - 1] == 1); -@} -@end example - - -@node Editor invocation -@section Editor invocation - -@cindex editor invoked at error -@cindex errors, editor invoked at -@opindex e @r{response at error prompt} - -@TeX{}, Metafont, and MetaPost all (by default) stop and ask for user -intervention at an error. If the input came from a file, and the user -responds with @kbd{e} or @kbd{E}, the program invokes an editor. - -@vindex TEXEDIT -@vindex MFEDIT -@vindex MPEDIT -@opindex --with-editor=@var{cmd} -@flindex texmf.cnf @r{for editors} -Specifying @samp{--with-editor=@var{cmd}} to @code{configure} sets the -default editor command string to @var{cmd}. The environment -variables/configuration values @code{TEXEDIT}, @code{MFEDIT}, and -@code{MPEDIT} (respectively) override this. If @samp{--with-editor} is -not specified, the default is @code{vi +%d %s} on Unix, and an -invocation of the @TeX{}works editor on Windows. (See -@file{texmf.cnf} for the precise values.) - -In this string, @samp{%d} is replaced by the line number of the error, -and @samp{%s} is replaced by the name of the current input file. - - -@node \input filenames -@section @code{\input} filenames - -@cindex input filenames -@cindex filename conventions, in input files -@findex \input @r{filenames} - -@TeX{}, Metafont, and MetaPost source programs can all read other source -files with the @code{\input} (@TeX{}) and @code{input} (MF and MP) -primitives: -@example -\input @var{name} % in TeX -@end example - -@cindex space-terminated filenames -@cindex whitespace-terminated filenames -@cindex terminator for filenames -The file @var{name} can always be terminated with whitespace; for -Metafont and MetaPost, the statement terminator @samp{;} also works. -(@LaTeX{} and other macro packages provide other interfaces to -@code{\input} that allow different notation; here we are concerned only -with the primitive operation.) - -As (allowed) extensions to standard @TeX{}, Web2c also supports -specifying the filename in double quotes (@code{"some name"}) and in -braces (@code{@{"some name"@}}), which is convenient for filenames -containing spaces or other special characters, as described in the -sections below. - -In all cases, space tokens are ignored after the filename is read. - -@cindex @code{"} character, ignored in filenames -@cindex double quote character, ignored in filenames -Also, double quote (@code{"}) characters are ignored within the -filename; there is no way to read files whose names contain a @code{"}. - -@cindex portable filenames -However, for maximal portability of your document across systems, use -only the characters @samp{a}--@samp{z}, @samp{0}--@samp{9}, and at -most one @samp{.}. Do not use anything but simple filenames, since -directory separators vary among systems; instead, add the necessary -directories to the appropriate search path. - -@menu -* Quotes: \input quoted filename. \input "some name" -* Braces: \input braced filename. \input @{some name@} -* Caveats: \input filename caveats. Tokenization, nulls, Kpathsea expansion. -@end menu - - -@node \input quoted filename -@subsection @code{\input} quoted filename: @code{\input "some name"} - -@cindex @code{\input} quoted filename -@cindex quoted filename for @code{\input} - -As of Web2c version 7.5.3 (2004), double-quote characters can be used -to include spaces or other special characters. In typical use, the -@samp{"} characters surround the entire filename: -@example -\input "filename with spaces" -@end example - -Technically, the quote characters can be used inside the name, and -can enclose any characters, as in: -@example -\input filename" "with" "spaces -@end example - -One more point. In @LaTeX{}, the quotes are needed inside the braces -of its @code{\input} macro, thus: -@example -\input@{a b@} % fails -\input@{"a b"@} % ok -@end example - -There is no way to quote the quote character. - - -@node \input braced filename -@subsection @code{\input} braced filename: @code{\input@{some name@}} - -@cindex @code{\input} braced (grouped) filename -@cindex braced filename for @code{\input} -@cindex group-delimited filename for @code{\input} - -As of Web2c 2020, @code{\input} filenames in @TeX{} engines (this does -not apply in Metafont and MetaPost) can also be specified within a -@TeX{} group, typically curly braces. For example: -@example -\input@{filename with spaces@} -@end example - -As always with @TeX{}, the brace characters are not hardwired; what -counts is the category code: the first token after the @code{\input} -must be of catcode@tie{}1 (begin group), and it is matched with the -next character of catcode@tie{}2 (end group). - -Within the group-delimited filename, braces are treated as normal -characters. - -As with all forms of filenames, following spaces are ignored (after -the end group), and double quote (@code{"}) characters are ignored -within the filename. - - -@node \input filename caveats -@subsection @code{\input} filename caveats - -@cindex @code{\input} filename caveats -@cindex caveats for @code{\input} filenames -@cindex tokenization, and @code{\input} filenames -@cindex expansion, and @code{\input} filenames -@cindex multiple spaces, and @code{\input} filenames -@cindex tabs, and @code{\input} filenames -The quoting mechanisms just described come into play @emph{after} -@TeX{} has tokenized and expanded the input. So, multiple spaces and -tabs will generally be seen as a single space, active characters such -as @samp{~} are expanded first (generally causing an error), and so -on. More examples below. - -@cindex NUL, not allowed in filenames -@cindex eight-bit characters in filenames -@cindex meta characters in filenames -On the other hand, various C library routines and Unix itself use the null -byte (character code zero, ASCII NUL) to terminate strings. So -filenames in Web2c cannot contain nulls, even though @TeX{} itself does -not treat NUL specially. - -@kindex ~ @r{expansion in filenames} -@kindex $ @r{expansion in filenames} -Finally, the present Web2c implementation does @samp{~} and @samp{$} -expansion on @var{name}, unlike Knuth's original implementation. -Thus: -@example -\input ~jsmith/$foo.bar -@end example -will dereference the environment variable or Kpathsea config file -value @samp{foo} and read that file, extended with @samp{.bar}, in -user @samp{jsmith}'s home directory. You can also use braces in the -variable expansion, as in @samp{$@{foo@}bar}, if you want to follow -the variable name with a letter, numeral, or @samp{_}. - -(So another way to get a program to read a filename containing -whitespace is to define an environment variable and dereference it.) - -@findex \string@r{, and @code{\input filenames}} -In all the common @TeX{} formats (plain @TeX{}, @LaTeX{}, Con@TeX{}t, -AMS@TeX{}, @dots{}), the characters @samp{~} and @samp{$} have special -category codes, so to actually use these in a document you have to -change their catcodes or use @code{\string}. - - -@node TeX -@chapter @TeX{}: Typesetting - -@cindex @TeX{}, description of -@cindex typesetting -@cindex mathematical typesetting - -@TeX{} is a typesetting system: it was especially designed to handle -complex mathematics, as well as most ordinary text typesetting. - -@cindex batch languages -@cindex word processor, not -@TeX{} is a batch language, like C or Pascal, and not an interactive -``word processor'': you compile a @TeX{} input file into a corresponding -device-independent (DVI) file (and then translate the DVI file to the -commands for a particular output device). This approach has both -considerable disadvantages and considerable advantages. For a complete -description of the @TeX{} language, see @cite{The @TeX{}book} -(@pxref{References}). Many other books on @TeX{}, introductory and -otherwise, are available. - -@menu -* tex invocation:: Invoking TeX. -* Initial TeX:: Making format files. -* Formats:: Major TeX macro packages. -* Languages and hyphenation:: TeX supports many human languages. -* Shell escapes:: Running subprograms from TeX. -* IPC and TeX:: DVI output to a socket. -* TeX extensions:: Additional engines with additional features. -@end menu - - -@node tex invocation -@section @code{tex} invocation - -@pindex tex -@cindex @TeX{}, invocation - -@TeX{} (usually invoked as @code{tex}) formats the given text and -commands, and outputs a corresponding device-independent representation -of the typeset document. This section merely describes the options -available in the Web2c implementation. For a complete description of -the @TeX{} typesetting language, see @cite{The @TeX{}book} -(@pxref{References}). - -@TeX{}, Metafont, and MetaPost process the command line (described -here) and determine their memory dump (fmt) file in the same way -(@pxref{Memory dumps}). Synopses: - -@example -tex [@var{option}]@dots{} [@var{texname}[.tex]] [@var{tex-commands}] -tex [@var{option}]@dots{} \@var{first-line} -tex [@var{option}]@dots{} &@var{fmt} @var{args} -@end example - -@flindex .tex -@cindex @TeX{}, input files found -@TeX{} searches the usual places for the main input file @var{texname} -(@pxref{Supported file formats,,, kpathsea, Kpathsea}), extending -@var{texname} with @file{.tex} if necessary. To see all the -relevant paths, set the environment variable @code{KPATHSEA_DEBUG} to -@samp{-1} before running the program. - -After @var{texname} is read, @TeX{} processes any remaining -@var{tex-commands} on the command line as regular @TeX{} input. Also, -if the first non-option argument begins with a @TeX{} escape character -(usually @code{\}), @TeX{} processes all non-option command-line -arguments as a line of regular @TeX{} input. - -If no arguments or options are specified, @TeX{} prompts for an -input file name with @samp{**}. - -@flindex texput -@TeX{} writes the main DVI output to the file -@file{@var{basetexname}.dvi}, where @var{basetexname} is the basename of -@var{texname}, or @samp{texput} if no input file was specified. A DVI -file is a device-independent binary representation of your @TeX{} -document. The idea is that after running @TeX{}, you translate the DVI -file using a separate program to the commands for a particular output -device, such as a PostScript printer -(@pxref{Top,,Introduction,dvips,Dvips}) or an X Window System display -(see xdvi(1)). - -@cindex EC fonts -@pindex mktextfM@r{, disabling} -@findex \font @r{and dynamic generation} -@TeX{} also reads TFM files for any fonts you load in your document with -the @code{\font} primitive. By default, it runs an external program -named @file{mktextfm} to create any nonexistent TFM files. You can -disable this at configure-time or runtime (@pxref{mktex -configuration,,, kpathsea, Kpathsea}). This is enabled mostly for the -sake of the EC fonts, which can be generated at any size. - -@findex \openout @r{and security} -@cindex security, and @code{\openout} -@cindex output files, written by @TeX{} programs -@cindex Trojan horses and @TeX{} programs -@cindex dot files, written by @TeX{} programs -@cindex security, and output files -@TeX{} can write output files, via the @code{\openout} primitive; this opens -a security hole vulnerable to Trojan horse attack: an unwitting user could -run a @TeX{} program that overwrites, say, @file{~/.rhosts}. (MetaPost has -a @code{write} primitive with similar implications). To alleviate this and -similar problems the functions @code{kpathsea_out_name_ok} and -@code{kpathsea_in_name_ok} from the Kpathse library (@pxref{Calling -sequence,,, kpathsea, Kpathsea}) are used to determine if a given filename -is acceptable to be opened for output or input, depending on the setting of -the configuration variables @code{openout_any} and @code{openin_any}: -@samp{a} (for ``any'', the default for @code{openin_any}), @samp{r} (for -``restricted''), or @samp{p} (for ``paranoid'', the default for -@code{openout_any}). - -In any case, all @code{\openout} filenames are recorded in the log file, -except those opened on the first line of input, which is processed when -the log file has not yet been opened. - -The program accepts the following options, as well as the standard -@samp{-help} and @samp{-version} (@pxref{Common options}): -@table @samp -@item -enc -@itemx -[no]-file-line-error -@itemx -fmt=@var{fmtname} -@itemx -halt-on-error -@itemx -ini -@itemx -interaction=@var{string} -@itemx -ipc -@itemx -ipc-start -@itemx -jobname=@var{string} -@itemx -kpathsea-debug=@var{number} -@itemx -[no]parse-first-line -@itemx -output-directory -@itemx -progname=@var{string} -@itemx -recorder -@itemx -translate-file=@var{tcxfile} -@itemx -8bit -These options are common to @TeX{}, Metafont, and MetaPost. -@xref{Common options}. - -@item -enc -@opindex -enc -@cindex Unicode input -@cindex UTF-8 input -Enable enc@TeX{} extensions, such as @code{\mubyte}. This can be used -to support the Unicode UTF-8 input encoding, although using an engine -with native Unicode support is more common nowadays. -@url{http://www.olsak.net/enctex.html}. - -@item -ipc -@itemx -ipc-start -@opindex -ipc -@opindex -ipc-start -@opindex --enable-ipc configure @r{option} -With either option, @TeX{} writes its DVI output to a socket as well as -to the usual @file{.dvi} file. With @samp{-ipc-start}, @TeX{} also -opens a server program at the other end to read the output. @xref{IPC -and TeX,,IPC and @TeX{}}. - -These options are available only if the @samp{--enable-ipc} option was -specified to @code{configure} during installation of Web2c. - -@item -mktex=@var{filetype} -@itemx -no-mktex=@var{filetype} -@opindex -mktex=@var{filetype} -@opindex -no-mktex=@var{filetype} -Turn on or off the @samp{mktex} script associated with @var{filetype}. -For @TeX{} proper, @var{filetype} can only be @samp{tex} and -@samp{tfm}, but for pdf@TeX{} and lua@TeX{}, it can also be @samp{pk}. - -@item -mltex -@opindex -mltex -@cindex ML@TeX{}, enabling -@cindex program names, special -If we are @code{INITEX} (@pxref{Initial and virgin}), enable ML@TeX{} -extensions such as @code{\charsubdef}. Implicitly set if the program -name is @code{mltex}. @xref{MLTeX,,ML@TeX{}}. - -@item -output-comment=@var{string} -@opindex -output-comment=@var{string} -@vindex output_comment @r{for DVI files} -@cindex DVI comment, specifying -@cindex regression testing -Use @var{string} as the DVI file comment. Ordinarily, this comment -records the date and time of the @TeX{} run, but if you are doing -regression testing, you may not want the DVI file to have this spurious -difference. This is also taken from the environment variable and -config file value @samp{output_comment}. - -@item -shell-escape -@opindex -shell-escape -@itemx -no-shell-escape -@opindex -no-shell-escape -@itemx -shell-restricted -@opindex -shell-restricted -Enable, or disable, or enable with restrictions the -@code{\write18@{@var{shell-command}@}} feature for external executing -shell commands. @xref{Shell escapes}. - -@item -enable-write18 -@opindex -enable-write18 -@itemx -disable-write18 -@opindex -disable-write18 -Synonyms for @option{-shell-escape} and @option{-no-shell-escape}, for -compatibility with MiK@TeX{}. (MiK@TeX{} also accepts both pairs of -options.) @xref{Shell escapes}. - -@item -src-specials -@itemx -src-specials=@var{string} -@cindex generating source specials -This option makes @TeX{} output specific source information using -@samp{\special} commands in the DVI file. These @samp{\special} track -the current file name and line number. - -Using the first form of this option, the @samp{\special} commands are -inserted automatically. - -In the second form of the option, @var{string} is -a comma separated list of the following values: @samp{cr}, -@samp{display}, @samp{hbox}, @samp{math}, @samp{par}, @samp{parend}, -@samp{vbox}. You can use this list to specify where you want @TeX{} to -output such commands. For example, @samp{-src-specials=cr,math} will -output source information every line and every math formula. - -These commands can be used with the appropriate DVI viewer and text -editor to switch from the current position in the editor to the same -position in the viewer and back from the viewer -to the editor. - -This option works by inserting @samp{\special} commands into the token -stream, and thus in principle these additional tokens can be recovered -or seen by the tricky-enough macros. If you run across a case, let us -know, because this counts as a bug. However, such bugs are very hard -to fix, requiring significant changes to @TeX{}, so please don't count -on it. - -Redefining @samp{\special} will not affect the functioning of this -option. The commands inserted into the token stream are -hard-coded to always use the @samp{\special} primitive. - -@TeX{} does not pass the trip test when this option is enabled. - -@end table - - -@node Initial TeX -@section Initial @TeX{} - -@cindex initial @TeX{} -@cindex @TeX{}, initial - -@flindex .fmt -@cindex fmt files -The @dfn{initial} form of @TeX{} is invoked by @samp{tex -ini}. It -does lengthy initializations avoided by the ``virgin'' (@code{vir}) -form, so as to be capable of dumping @samp{.fmt} files (@pxref{Memory -dumps}). For a detailed comparison of virgin and initial forms, -@pxref{Initial and virgin}. - -For a list of options and other information, @pxref{tex invocation}. - -@flindex plain.fmt -@flindex tex.fmt -@cindex format files -Unlike Metafont and MetaPost, many format files are commonly used with -@TeX{}. The standard one implementing the features described in the -@cite{@TeX{}book} is @samp{plain.fmt}, also known as @samp{tex.fmt} -(again, @pxref{Memory dumps}). It is created by default during -installation, but you can also do so by hand if necessary (e.g., if an -update to @file{plain.tex} is issued): -@example -tex -ini '\input plain \dump' -@end example -@noindent -(The quotes prevent interpretation of the backslashes from the shell.) -Then install the resulting @file{plain.fmt} in @samp{$(fmtdir)} -(@file{/usr/local/share/texmf/web2c} by default), and link -@file{tex.fmt} to it. - -The necessary invocation for generating a format file differs for each -format, so instructions that come with the format should explain. The -top-level @file{web2c} Makefile has targets for making most common -formats: @t{plain latex amstex texinfo eplain}. @xref{Formats}, for -more details on @TeX{} formats. - - -@node Formats -@section Formats - -@cindex formats for @TeX{} -@cindex @TeX{}, format packages for -@cindex macro packages, major @TeX{} - -@TeX{} @dfn{formats} are large collections of macros, often dumped -into a @file{.fmt} file (@pxref{Memory dumps}) by @code{tex -ini} -(@pxref{Initial TeX}). A number of formats are in reasonably -widespread use, and the Web2c Makefile has targets to make the versions -current at the time of release. You can change which formats are -automatically built by setting the @code{fmts} Make variable; by default, -only the @samp{plain} and @samp{latex} formats are made. - -Nowadays, the formats are generally installed and updated as part of a -larger @TeX{} distribution, such as @TeX{} Live -(@url{https://tug.org/texlive}). - -@table @t -@item latex -@cindex @LaTeX{} -The most widely used format. The current release is named -`@LaTeX{}2e'; new versions are released approximately every six -months, with patches issued as needed. The old release was called -`@LaTeX{} 2.09', and is no longer maintained or supported. @LaTeX{} -attempts to provide generic markup instructions, such as -``emphasize'', instead of specific typesetting instructions, such as -``use the 10@dmn{pt} Computer Modern italic font''. The @LaTeX{} home -page: @url{https://www.latex-project.org}. - -@item context -@cindex Con@TeX{}t -Con@TeX{}t is an independent macro package which has a basic document -structuring approach similar to @LaTeX{}. It also supports creating -interactive PDF files and has integrated MetaPost support, among many -other interesting features. The Con@TeX{}t home page: -@url{http://www.pragma-ade.com}. - -@item amstex -@cindex AMS@TeX{} -@cindex American Mathematical Society, typesetting system -@cindex Mathematical Reviews -The official typesetting system of the American Mathematical Society. -Like @LaTeX{}, it encourages generic markup commands. The AMS also -provides many @LaTeX{} packages for authors who prefer @LaTeX{}. Taken -together, they are used to produce nearly all AMS publications, e.g., -@cite{Mathematical Reviews}. The AMS@TeX{} home page: -@url{https://www.ams.org/tex}. - -@item texinfo -@cindex Texinfo -@cindex Info format -@cindex Free Software Foundation documentation system -The documentation system developed and maintained by the Free Software -Foundation for their software manuals. It can be automatically -converted into plain text, a machine-readable on-line format called -`info', HTML, etc. The Texinfo home page: -@url{https://www.gnu.org/software/texinfo}. - -@item eplain -@cindex Eplain -@cindex expanded plain format -The ``expanded plain'' format provides various common features (e.g., -symbolic cross-referencing, tables of contents, indexing, citations -using Bib@TeX{}), for those authors who prefer to handle their own -high-level formatting. The Eplain home page: -@url{https://tug.org/eplain}. - -@item slitex -@cindex Sli@TeX{} -@cindex slides, producing -@flindex beamer@r{, package} -An obsolete @LaTeX{} 2.09 format for making slides. It is replaced by -the @samp{slides} document class, although the @samp{beamer} package -is the most commonly method for making slides nowadays. The Beamer -page on CTAN: @url{https://ctan.org/pkg/beamer}. - -@end table - - -@node Languages and hyphenation -@section Languages and hyphenation - -@cindex language support in @TeX{} -@cindex human languages, supported in @TeX{} -@cindex hyphenation and languages - -@TeX{} supports most natural languages. See also @ref{TeX extensions,, -@TeX{} extensions}. - -@menu -* MLTeX:: Multi-lingual TeX. -* TCX files:: Support for different character sets & fonts. -* patgen invocation:: Creating hyphenation patterns. -@end menu - - -@node MLTeX -@subsection ML@TeX{}: Multi-lingual @TeX{} - -@pindex mltex -@cindex Multi-lingual @TeX{} - -@cindex Ferguson, Michael -@cindex Raichle, Bernd -@cindex accents, hyphenating words with -@cindex glyph substitutions -@cindex substitutions of font glyphs -Multi-lingual @TeX{} (@code{mltex}) is an extension of @TeX{} originally -written by Michael Ferguson and now updated and maintained by Bernd -Raichle. With the advent of Unicode, it has become obsolete, though -it is still supported in Web2c in the event of bugs or compilation -bugs. - -ML@TeX{} allows the use of non-existing glyphs in a font by declaring -glyph substitutions. These are restricted to substitutions of an -accented character glyph, which need not be defined in the current -font, by its appropriate @code{\accent} construction using a base and -accent character glyph, which do have to exist in the current font. -This substitution is automatically done behind the scenes, if -necessary, and thus ML@TeX{} additionally supports hyphenation of -words containing an accented character glyph for fonts missing this -glyph (e.g., Computer Modern). Standard @TeX{} suppresses hyphenation -in this case. - -ML@TeX{} works at @file{.fmt}-creation time: the basic idea is to -specify the @samp{-mltex} option to @TeX{} when you @code{\dump} a -format. Then, when you subsequently invoke @TeX{} and read that -@code{.fmt} file, the ML@TeX{} features described below will be enabled. - -Generally, you use special macro files to create an ML@TeX{} @code{.fmt} -file. - -The sections below describe the two new primitives that ML@TeX{} defines. -Aside from these, ML@TeX{} is completely compatible with standard @TeX{}. - -@menu -* \charsubdef:: Character substitution definitions. -* \tracingcharsubdef:: Tracing substitutions. -@end menu - - -@node \charsubdef -@subsubsection @code{\charsubdef}: Character substitutions - -@findex \charsubdef @r{and ML@TeX{}} - -The most important primitive ML@TeX{} adds is @code{\charsubdef}, used -in a way reminiscent of @code{\chardef}: -@example -\charsubdef @var{composite} [=] @var{accent} @var{base} -@end example - -Each of @var{composite}, @var{accent}, and @var{base} are font glyph -numbers, expressed in the usual @TeX{} syntax: @t{`\e} symbolically, -@t{'145} for octal, @t{"65} for hex, @t{101} for decimal. - -ML@TeX{}'s @code{\charsubdef} declares how to construct an accented -character glyph (not necessarily existing in the current font) using two -character glyphs (that do exist). Thus it defines whether a character -glyph code, either typed as a single character or using the @code{\char} -primitive, will be mapped to a font glyph or to an @code{\accent} glyph -construction. - -For example, if you assume glyph code 138 -@cindex e-circumflex -(decimal) for an e-circumflex -@tex -(\^e) -@end tex -and you are using the Computer Modern fonts, which have the circumflex -accent in position 18 and lowercase `e' in the usual ASCII position 101 -decimal, you would use @code{\charsubdef} as follows: - -@example -\charsubdef 138 = 18 101 -@end example - -For the plain @TeX{} format to make use of this substitution, you have -to redefine the circumflex accent macro @code{\^} in such a way that if -its argument is character `e' the expansion @code{\char138 } is used -instead of @code{\accent18 e}. Similar @code{\charsubdef} declaration -and macro redefinitions have to be done for all other accented -characters. - -To disable a previous @code{\charsubdef @var{c}}, redefine @var{c} -as a pair of zeros. For example: -@example -\charsubdef '321 = 0 0 % disable N tilde -@end example -@cindex N tilde -@noindent -(Octal @t{'321} is the ISO Latin-1 value for the Spanish N tilde.) - -@code{\charsubdef} commands should only be given once. Although in -principle you can use @code{\charsubdef} at any time, the result is -unspecified. If @code{\charsubdef} declarations are changed, usually -either incorrect character dimensions will be used or ML@TeX{} will -output missing character warnings. (The substitution of a -@code{\charsubdef} is used by @TeX{} when appending the character node -to the current horizontal list, to compute the width of a horizontal box -when the box gets packed, and when building the @code{\accent} -construction at @code{\shipout}-time. In summary, the substitution is -accessed often, so changing it is not desirable, nor generally useful.) - - -@node \tracingcharsubdef -@subsubsection @code{\tracingcharsubdef}: Substitution diagnostics - -@findex \tracingcharsubdef @r{and ML@TeX{}} -@cindex redefined character substitutions -To help diagnose problems with @samp{\charsubdef}, ML@TeX{} provides a -new primitive parameter, @code{\tracingcharsubdef}. If positive, every -use of @code{\charsubdef} will be reported. This can help track down -when a character is redefined. - -@findex \tracinglostchars @r{and ML@TeX{}} -In addition, if the @TeX{} parameter @code{\tracinglostchars} is 100 or -more, the character substitutions actually performed at -@code{\shipout}-time will be recorded. - - -@node TCX files -@subsection TCX files: Character translations - -@flindex TCX @r{character translation files} -@flindex .tcx @r{character translation files} -@cindex character translation files - -@cindex international characters -@cindex 8-bit characters -@cindex accented character -TCX (@TeX{} character translation) files help @TeX{} support direct -input of 8-bit international characters if fonts containing those -characters are being used. Specifically, they map an input (keyboard) -character code to the internal @TeX{} character code (a superset of -ASCII). - -Of the various proposals for handling more than one input encoding, -TCX files were chosen because they follow Knuth's original ideas for -the use of the @samp{xchr} and @samp{xord} tables. He ventured that -these would be changed in the WEB source in order to adjust the actual -version to a given environment. It turns out, however, that -recompiling the WEB sources is not as simple a task as Knuth may have -imagined; therefore, TCX files, providing the possibility of changing -of the conversion tables on on-the-fly, have been implemented instead. - -This approach limits the portability of @TeX{} documents, as some -implementations do not support it (or use a different method for -input-internal reencoding). It may also be problematic to determine -the encoding to use for a @TeX{} document of unknown provenance; in -the worst case, failure to do so correctly may result in subtle errors -in the typeset output. But we feel the benefits outweigh these -disadvantages. - -This is entirely independent of the ML@TeX{} extension (@pxref{MLTeX}): -whereas a TCX file defines how an input keyboard character is mapped to -@TeX{}'s internal code, ML@TeX{} defines substitutions for a -non-existing character glyph in a font with a @code{\accent} -construction made out of two separate character glyphs. TCX files -involve no new primitives; it is not possible to specify -that an input (keyboard) character maps to more than one character. - -@vindex WEB2C@r{, search path for TCX files} -Information on specifying TCX files: - -@itemize @bullet -@item -The best way to specify a TCX file is to list it explicitly in the -first line of the main document: -@example -%& -translate-file=@var{tcxfile} -@end example - -@item -You can also specify a TCX file to be used on a particular @TeX{} run -with the command-line option @samp{-translate-file=@var{tcxfile}}. - -@item -TCX files are searched for along the @code{WEB2C} path. - -@item -Initial @TeX{} (@pxref{Initial TeX,,Initial @TeX{}}) ignores TCX files. -@end itemize - -@flindex il1-t1.tcx -@flindex il2-t1.tcx -@flindex empty.tcx -@cindex Cork encoding and ISO input -@cindex T1 encoding and ISO input -The Web2c distribution comes with a number of TCX files. Two -important ones are @file{il1-t1.tcx} and @file{il2-t1.tcx}, which -support ISO Latin 1 and ISO Latin 2, respectively, with Cork-encoded -fonts (a.k.a.@ the @LaTeX{} T1 encoding). TCX files for Czech, -Polish, and Slovak are also provided. - -One other notable TCX file is @file{empty.tcx}, which is, well, -empty. Its purpose is to reset Web2C's behavior to the default (only -visible ASCII being printable, as described below) when a format was -dumped with another TCX being active---which is in fact the case for -everything but plain @TeX{} in the TeX Live and other distributions. -Thus: - -@example -latex somefile8.tex -@result{} terminal etc. output with 8-bit chars -latex --translate-file=empty.tcx somefile8.tex -@result{} terminal etc. output with ^^ notation -@end example - -@cindex syntax of TCX files -Syntax of TCX files: -@enumerate -@item -@cindex blank lines, in TCX files -Line-oriented. Blank lines are ignored. - -@item -@cindex whitespace, in TCX files -Whitespace is ignored except as a separator. - -@item -@cindex comments, in TCX files -Comments start with @samp{%} and continue to the end of the line. - -@item -Otherwise, a line consists of one or two character codes, optionally -followed by 0 or 1. The last number indicates whether @var{dest} is -considered printable. -@example -@var{src} [@var{dest} [@var{prnt}]] -@end example - -@item -@cindex character codes, in TCX files -@cindex octal character codes, in TCX files -@cindex hex character codes, in TCX files -@cindex decimal character codes, in TCX files -Each character code may be specified in octal with a leading @samp{0}, -hexadecimal with a leading @samp{0x}, or decimal otherwise. Values must -be between 0 and 255, inclusive (decimal). - -@item -If the @var{dest} code is not specified, it is taken to be the same as -@var{src}. - -@item -If the same @var{src} code is specified more than once, it is the last -definition that counts. -@end enumerate - -@cindex printable characters, specifying -@kindex ^^ @r{notation, avoiding} -Finally, here's what happens: when @TeX{} sees an input character with -code @var{src}, it 1) changes @var{src} to @var{dest}; and 2) makes the -@var{dest} code ``printable'', i.e., printed as-is in diagnostics and the -log file rather than in @samp{^^} notation. - -By default, no characters are translated, and character codes between 32 -and 126 inclusive (decimal) are printable. - -Specifying translations for the printable ASCII characters (codes -32--127) will yield unpredictable results. Additionally you shouldn't -make the following characters printable: @code{^^I} (TAB), @code{^^J} -(line feed), @code{^^M} (carriage return), and @code{^^?} (delete), -since @TeX{} uses them in various ways. - -@cindex font character code, translating -@cindex keyboard character code, translating -Thus, the idea is to specify the input (keyboard) character code for -@var{src}, and the output (font) character code for @var{dest}. - -@cindex interaction between TCX files and @samp{-8bit}. -By default, only the printable ASCII characters are considered printable -by @TeX{}. If you specify the @samp{-8bit} option, all characters are -considered printable by default. If you specify both the @samp{-8bit} -option and a TCX file, then the TCX can set specific characters to be -non-printable. - -Both the specified TCX encoding and whether characters are printable -are saved in the dump files (like @file{tex.fmt}). So by giving these -options in combination with @samp{-ini}, you control the defaults seen -by anyone who uses the resulting dump file. - -When loading a dump, if the @samp{-8bit} option was given, then all -characters become printable by default. - -When loading a dump, if a TCX file was specified, then the TCX data from -the dump is ignored and the data from the file used instead. - - -@node patgen invocation -@subsection Patgen: Creating hyphenation patterns - -@pindex patgen -@cindex hyphenation patterns, creating -@cindex languages, hyphenation rules for - -Patgen creates hyphenation patterns from dictionary files for use with -@TeX{}. Synopsis: - -@example -patgen @var{dictionary} @var{patterns} @var{output} @var{translate} -@end example - -Each argument is a filename. No path searching is done. The output is -written to the file @var{output}. - -@c @table @var -@c @item dictionary -@c @cindex dictionary file -@c @findex \lefthyphemmin -@c @findex \righthyphenmin -@c The first line contains the values of @code{}\lefthyphenmin} and -@c @code{\righthyphenmin} in columns 1--2 and 3--4. Columns 5, 6, and 7 may -@c optionally contain replacements for the default characters @samp{.}, -@c @samp{-}, and @samp{*} respectively used in the word lists. -@c -@c Subsequent lines are either comments (if they start with two identical -@c characters, e.g., @samp{%%}), or contain the external representation of -@c the lower case version of a letter, followed by an arbitrary number of -@c upper case versions, preceded and separated by a delimiter and followed -@c by two consecutive delimiters. The delimiter may be any character not -@c occurring in either version. - -In addition, Patgen prompts interactively for other values. - -For more information, see @cite{Word hy-phen-a-tion by com-puter} by -Frank Liang (@pxref{References}), and also the @file{patgen.web} source file. - -The only options are @samp{-help} and @samp{-version} (@pxref{Common -options}). - - -@node Shell escapes -@section Shell escapes - -@cindex shell commands in @TeX{} -@cindex security, and shell escapes -@cindex restricted shell escapes -@cindex system command -@vindex shell_escape @r{enabling in @TeX{}} -@findex \immediate\write18 -@findex \write18 @r{shell escape extension} -@findex system @r{C library function} -@flindex texmf.cnf @r{for shell escapes} - -@TeX{} can execute @dfn{shell escapes}, that is, arbitrary shell -commands. Although tremendously useful, this also has obvious -security implications. Therefore, as of @TeX{} Live 2009, a -@dfn{restricted} mode for shell escapes is the default mode of -operation, which allows executing only certain commands, as specified -in the @file{texmf.cnf} configuration file. - -@itemize @bullet -@item -Unrestricted shell escapes are allowed if the option -@option{--shell-escape} is specified, or if the environment variable -or config file value @code{shell_escape} is set to @samp{t} or -@samp{y} and @samp{1}. - -@item -Restricted shell escapes are allowed if @code{shell_escape} is set to -@samp{p}. This is the default. - -@item -Shell escapes are completely disabled if @option{--no-shell-escape} is -specified, or if @code{shell_escape} is set to anything else. -@end itemize - -When enabled, the @TeX{} construct to execute a system command is -@code{\write18@{@var{shell-command}@}}; for example: - -@example -\write18@{echo "hello, world"@} -@end example - -@findex \output @r{routine, and @code{\write}} -From @TeX{}'s point of view, this is a normal @code{\write} command, -and is therefore subject to the usual @TeX{} expansions. Also, the -system call either happens during the @samp{\output} routine or right -away, according to the absence or presence of the @code{\immediate} -prefix, as usual for @code{\write}. - -@cindex exit status, of shell escape -The @var{shell-command} string is passed to the command shell (via the -C library function @code{system}). The output of @var{shell-command} -is not diverted anywhere, so it will not appear in the log file, or -anywhere but the terminal output. The exit status of the system call -is also not available to @TeX{}. - -In unrestricted mode, the argument is simply passed straight to -@code{system} unaltered. - -In restricted mode, ASCII double quote characters (@verb{|"|}) should -always be used in the argument to @code{\write18} where quoting of -arguments is needed, as in the example above. This is to achieve some -measure of system independence. On Unix systems, these are replaced -with single quote (@verb{|'|}) characters to avoid insecure further -expansion. Care is also taken on Windows to avoid additional -expansions (from, e.g., @verb{|`...`|}). Mismatched quotation marks -in the command string result in a diagnostic message in the log file; -no execution is performed. - -@findex shell_escape_commands -After quotation processing, if the first word (delimited by a space or -tab) of the command is in the list specified by the -@code{shell_escape_commands} configuration value, the command is -executed. Otherwise it is not. In any case, a message is written to -the log file. - -The @code{shell_escape_commands} value is a comma-separated list of -words. Whitespace is significant, and typically should not be -present. The default definition in @file{texmf.cnf} looks like this, -but with more commands included: - -@example -shell_escape_commands = bibtex,kpsewhich,repstopdf,... -@end example - -@cindex pipes, reading and writing -@findex \openin@r{, and pipes} -@findex \input@r{, and pipes} -@findex \openout@r{, and pipes} -@findex \pdfshellescape -pdf@TeX{} and lua@TeX{} support reading (via @code{\input} and -@code{\openin}) and writing (via @code{\openout}) from pipes if the -first character is @samp{|}. The following command is then treated -exactly the same as the argument to @code{\write18}. In these -engines, the primitive variable @code{\pdfshellescape} is set to 0 if -shell escapes are disabled, 1 if they are enabled, and 2 if they are -enabled with restrictions. - -@cindex web environments, and security -The purpose of this feature is to make it possible for @TeX{} -documents to perform useful external actions in the common case of an -individual user running a known document on his or her own machine. -In such environments as CGI scripts or wikis where the input has to be -considered untrustworthy, shell escapes should be completely disabled. - - -@node IPC and TeX -@section IPC and @TeX{} - -@cindex IPC -@cindex sockets -(If anyone uses this feature and needs documentation, write -@email{tex-k@@tug.org}.) - -This functionality is available only if the @samp{--enable-ipc} option -was specified to @code{configure} during installation of Web2c -(@pxref{Installation}). - -@vindex IPC_DEBUG -If you define @code{IPC_DEBUG} before compilation (e.g., with @samp{make -XCFLAGS=-DIPC_DEBUG}), @TeX{} will print messages to standard error -about its socket operations. This may be helpful if you are, well, -debugging. - - -@node TeX extensions -@section Extended @TeX{} engines - -@cindex extensions to @TeX{} -@cindex @TeX{}, extensions to - -The base @TeX{} program has been extended in many ways. Here's a -partial list. - -@table @asis -@item e-@TeX{} -@cindex e-@TeX{} -@cindex primitives, new -Adds many new primitives, including right-to-left typesetting and more -registers. Now frozen. More info: @url{https://ctan.org/pkg/etex}. - -@item Aleph -@cindex Aleph -@cindex Omega -@cindex Unicode -This adds Unicode support, right-to-left typesetting, and more. Omega -was the original program. Aleph is an updated version with a variety -of bug fixes, and includes e-@TeX{}. Aleph is not actively maintained. -More info: @url{https://ctan.org/pkg/aleph}, @url{https://ctan.org/pkg/omega}. - -@item pdf@TeX{} -@cindex pdf@TeX{} -@cindex PDF -@cindex micro-typography -@cindex hypertext -@pindex etex @r{is pdf@TeX{}} -Can produce PDF as well as DVI files. It also incorporates the -e-@TeX{} extensions, new primitives for hypertext and -micro-typography, reading/writing from pipes, and much more. In -@TeX{} Live, the command @command{etex} invokes pdf@TeX{} to make all -these additions available with DVI output. Home page: -@url{http://pdftex.org}. - -@item Lua@TeX{} -@cindex Lua@TeX{} -@cindex Lua -@cindex UTF-8 input, native -@cindex OpenType support -@cindex TrueType support -@cindex system fonts, using -Embeds the Lua programming language (@url{http://lua.org}) and opens -up the @TeX{} typesetting engine to control from Lua, starting from -the pdf@TeX{} capabilities as a base. Also natively supports UTF-8 -input, the OpenType and TrueType font formats, and use of system -fonts. Home page: @url{http://luatex.org}. - -@item Xe@TeX{} -@cindex Xe@TeX{} -@cindex Unicode input, native -Combines support for Unicode input, the OpenType and TrueType font -formats, and use of system fonts with the capabilities of pdf@TeX{}, -with the exception of the font expansion part of micro-typography. -Home page: @url{https://tug.org/xetex}. - -@item p@TeX{} -@itemx up@TeX{} -@cindex p@TeX{} -@cindex up@TeX{} -With additional support for Japanese; p@TeX{} was the original engine, -and up@TeX{} has native Unicode support and thus is more useful for -Chinese and Korean. More info: @url{https://ctan.org/pkg/ptex}, -@url{https://ctan.org/pkg/uptex}. - -@item ep@TeX{} -@itemx eup@TeX{} -@cindex ep@TeX{} -@cindex eup@TeX{} -Further extends p@TeX{} and up@TeX{} with the e-@TeX{} extensions. -More info: @url{https://ctan.org/pkg/eptex}, -@url{https://ctan.org/pkg/euptex}. - -@end table - - -@node Metafont -@chapter Metafont: Creating typeface families - -@cindex Metafont -@cindex typeface families -@cindex geometric designs -@cindex shapes -@cindex font design - -Metafont is a system for producing shapes; it was designed for producing -complete typeface families, but it can also produce geometric designs, -dingbats, etc. And it has considerable mathematical and -equation-solving capabilities which can be useful entirely on their own. - -Metafont is a batch language, like C or Pascal: you compile a Metafont -program into a corresponding font, rather than interactively drawing -lines or curves. This approach has both considerable disadvantages -(people unfamiliar with conventional programming languages will be -unlikely to find it usable) and considerable advantages (you can make -your design intentions specific and parameterizable). For a complete -description of the Metafont language, see @cite{The METAFONTbook} -(@pxref{References}). - -@menu -* mf invocation:: Invoking Metafont. -* Initial Metafont:: Making bases. -* Modes:: Device definitions for Metafont. -* Online Metafont graphics:: Seeing MF output online. -* gftodvi invocation:: Making proofsheets for fonts. -* mft invocation:: Prettyprinting Metafont sources. -@end menu - - -@node mf invocation -@section @code{mf} invocation - -@pindex mf -@cindex Metafont invocation - -Metafont (usually invoked as @code{mf}) reads character definitions -specified in the Metafont programming language, and outputs the -corresponding font. This section merely describes the options available -in the Web2c implementation. For a complete description of the Metafont -language, see @cite{The Metafontbook} (@pxref{References}). - -Metafont processes its command line and determines its memory dump -(base) file in a way exactly analogous to MetaPost and @TeX{} -(@pxref{tex invocation}, and @pxref{Memory dumps}). Synopses: - -@example -mf [@var{option}]@dots{} [@var{mfname}[.mf]] [@var{mf-commands}] -mf [@var{option}]@dots{} \@var{first-line} -mf [@var{option}]@dots{} &@var{base} @var{args} -@end example - -Most commonly, a Metafont invocation looks like this: -@example -mf '\mode:=@var{mode}; mag:=@var{magnification}; input @var{mfname}' -@end example -@noindent -(The single quotes avoid unwanted interpretation by the shell.) - -@flindex .mf -@cindex Metafont input files -@cindex EC fonts -@pindex mktexmf@r{, disabling} -Metafont searches the usual places for the main input file @var{mfname} -(@pxref{Supported file formats,,, kpathsea, Kpathsea}), extending -@var{mfname} with @file{.mf} if necessary. To see all the relevant -paths, set the environment variable @code{KPATHSEA_DEBUG} to @samp{-1} -before running the program. By default, Metafont runs an external -program named @file{mktexmf} to create any nonexistent Metafont source -files you input. You can disable this at configure-time or runtime -(@pxref{mktex configuration,,, kpathsea, Kpathsea}). This is mostly -for the sake of the EC fonts, which can be generated at any size. - -@flindex .@var{nnn}gf @r{generic fonts} -@flindex mfput -@cindex GF output -@cindex GF files, output by Metafont -@cindex PK files, not output by Metafont -Metafont writes the main GF output to the file -@file{@var{basemfname}.@var{nnn}gf}, where @var{nnn} is the font -resolution in pixels per inch, and @var{basemfname} is the basename of -@var{mfname}, or @samp{mfput} if no input file was specified. A GF file -contains bitmaps of the actual character shapes. Usually GF files are -converted immediately to PK files with GFtoPK (@pxref{gftopk -invocation}), since PK files contain equivalent information, but are -more compact. (Metafont output in GF format rather than PK for only -historical reasons.) - -@flindex .tfm @r{output} -@cindex TFM files, output by Metafont -Metafont also usually writes a metric file in TFM format to -@file{@var{basemfname}.tfm}. A TFM file contains character dimensions, -kerns, and ligatures, and spacing parameters. @TeX{} reads only this -@t{.tfm} file, not the GF file. - -@cindex mode needed to run Metafont -@findex proof @r{mode} -@flindex 2602gf -@flindex .2602gf -The @var{mode} in the example command above is a name referring to a -device definition (@pxref{Modes}); for example, @code{localfont} or -@code{ljfour}. These device definitions must generally be precompiled -into the base file. If you leave this out, the default is @code{proof} -mode, as stated in @cite{The Metafontbook}, in which Metafont outputs at -a resolution of 2602@dmn{dpi}; this is usually not what you want. The -remedy is simply to assign a different mode---@code{localfont}, for -example. - -The @var{magnification} assignment in the example command above is a -magnification factor; for example, if the device is 600@dmn{dpi} and you -specify @code{mag:=2}, Metafont will produce output at 1200@dmn{dpi}. -Very often, the @var{magnification} is an expression such as -@code{magstep(.5)}, corresponding to a @TeX{} ``magstep'', which are -factors of -@tex -1.2$\sqrt{2}$. -@end tex -@ifinfo -1.2 * sqrt(2). -@end ifinfo - -After running Metafont, you can use the font in a @TeX{} document as -usual. For example: -@example -\font\myfont = newfont -\myfont Now I am typesetting in my new font (minimum hamburgers). -@end example - -The program accepts the following options, as well as the standard -@samp{-help} and @samp{-version} (@pxref{Common options}): -@table @samp -@item -[no]-file-line-error -@itemx -fmt=@var{fmtname} -@itemx -halt-on-error -@itemx -ini -@itemx -interaction=@var{string} -@itemx -jobname=@var{string} -@itemx -kpathsea-debug=@var{number} -@itemx -[no]parse-first-line -@itemx -output-directory -@itemx -progname=@var{string} -@itemx -recorder -@itemx -translate-file=@var{tcxfile} -@itemx -8bit -These options are common to @TeX{}, Metafont, and MetaPost. -@xref{Common options}. - -@item -mktex=@var{filetype} -@itemx -no-mktex=@var{filetype} -@opindex -mktex=@var{filetype} -@opindex -no-mktex=@var{filetype} -Turn on or off the @samp{mktex} script associated with @var{filetype}. -The only value that makes sense for @var{filetype} is @samp{mf}. -@end table - - -@node Initial Metafont -@section Initial Metafont - -@cindex initial Metafont -@cindex Metafont, initial - -@flindex .base -@cindex base files -@code{inimf} is the ``initial'' form of Metafont, which does lengthy -initializations avoided by the ``virgin'' (@code{vir}) form, so as to -be capable of dumping @samp{.base} files (@pxref{Memory dumps}). For -a detailed comparison of virgin and initial forms, see @ref{Initial -and virgin}. - -For a list of options and other information, see @ref{mf invocation}. - -@flindex plain.base -@flindex mf.base -The only memory dump file commonly used with Metafont is the default -@samp{plain.base}, also known as @samp{mf.base} (again, @pxref{Memory -dumps}). It is created by default during installation, but you can also -do so by hand if necessary (e.g., if a Metafont update is issued): -@example -mf -ini '\input plain; input modes; dump' -@end example -@noindent -(The quotes prevent interpretation of the backslashes from the shell.) -Then install the resulting @file{plain.base} in @samp{$(basedir)} -(@file{/usr/local/share/texmf/web2c} by default), and link -@file{mf.base} to it. - -For an explanation of the additional @file{modes.mf} file, -see @ref{Modes}. This file has no counterpart in @TeX{} or MetaPost. - -@flindex cmmf.base @r{not recommended} -@flindex cm.base -@flindex cmbase.mf -@cindex Computer Modern macros -@cindex base files, plain only -In the past, it was sometimes useful to create a base file -@file{cmmf.base} (a.k.a.@: @file{cm.base}), with the Computer Modern -macros also included in the base file. Nowadays, however, the -additional time required to read @file{cmbase.mf} is exceedingly small, -usually not enough to be worth the administrative hassle of updating the -@file{cmmf.base} file when you install a new version of @file{modes.mf}. -@cindex type design, personal -People actually working on a typeface may still find it worthwhile to -create their own base file, of course. - - -@node Modes -@section Modes: Device definitions for Metafont - -@cindex modes file needed for Metafont -@cindex base files, need mode definitions -@cindex device definitions, for Metafont -@cindex printer characteristics, for Metafont -Running Metafont and creating Metafont base files requires information -that @TeX{} and MetaPost do not: @dfn{mode} definitions which specify -device characteristics, so Metafont can properly rasterize the shapes. - -@flindex modes.mf @r{recommended modes file} -When making a base file, a file containing modes for locally-available -devices should be input after @file{plain.mf}. One commonly used file -is @url{ftp://ftp.tug.org/tex/modes.mf}; it includes all known -definitions. - -@cindex small Metafont memory and modes -@findex mode_def -@findex mode_setup -If, however, for some reason you have decreased the memory available in -your Metafont, you may need to copy @file{modes.mf} and remove the -definitions irrelevant to you (probably most of them) instead of using -it directly. (Or, if you're a Metafont hacker, maybe you can suggest a -way to redefine @code{mode_def} and/or @code{mode_setup}; right now, the -amount of memory used is approximately four times the total length of -the @code{mode_def} names, and that's a lot.) - -If you have a device not included in @file{modes.mf}, please see -comments in that file for how to create the new definition, and please -send the definition to @email{tex-fonts@@math.utah.edu} to get it included -in the next release of @file{modes.mf}. - -@findex smode @r{and dynamic Metafont mode definition} -@cindex dynamic Metafont mode definitions with @code{smode} -Usually, when you run Metafont you must supply the name of a mode that -was dumped in the base file. But you can also define the mode -characteristics dynamically, by invoking Metafont with an assignment to -@code{smode} instead of @code{mode}, like this: -@example -mf '\smode:="newmode.mf"; mag:=@var{magnification}; input @var{mfname}' -@end example -@noindent -This is most useful when you are working on the definition of a new -mode. - -The @var{magnification} and @var{mfname} arguments are explained in -@ref{mf invocation}. In the file @file{newmode.mf}, you should have the -following (with no @code{mode_def} or @code{enddef}), if you are using -@file{modes.mf} conventions: -@example -mode_param (pixels_per_inch, @var{dpi}); -mode_param (blacker, @var{b}); -mode_param (fillin, @var{f}); -mode_param (o_correction, @var{o}); -mode_common_setup_; -@end example -@noindent -(Of course, you should use real numbers for @var{dpi}, @var{b}, @var{f}, -and @var{o}.) - -For more information on the use of @code{smode}, or if you are not using -@file{modes.mf}, see page 269 of @cite{The Metafontbook}. - - -@node Online Metafont graphics -@section Online Metafont graphics - -@cindex online Metafont graphics -@cindex Metafont graphics - -The Web2c implementation of Metafont can do online graphics with a -number of devices. (See the Metafont manual for more information about -how to draw on your screen.) By default, no graphics support is -enabled. - -@vindex MFTERM -@vindex TERM -Metafont examines the @code{MFTERM} environment variable or config file -value at runtime, or the @code{TERM} environment variable if -@code{MFTERM} is not set, to determine the device support to use. -Naturally, only the devices for which support has been compiled in can -be selected. - -Here is a table of the possibilities, showing the @code{MFTERM} value -and the corresponding @code{configure} option(s) in parentheses. - -@vtable @code -@item epsf -@cindex Herberts, Mathias -@opindex --enable-epsfwin -(@samp{--enable-epsfwin}) Pseudo-window server for Encapsulated -PostScript (see @file{web2c/window/epsf.c}). This device produces an -EPS file containing the graphics which would be displayed online on -other devices. The name of the EPS file defaults to metafont.eps but -can be changed by setting the MFEPSF environment variable to the new -filename. Contributed by Mathias Herberts. - -@item hp2627 -@opindex --enable-hp2627win -(@samp{--enable-hp2627win}) HP2627a color graphics terminals. - -@item mftalk -@opindex --enable-mftalkwin -(@samp{--enable-mftalkwin}) Generic window server (see -@file{web2c/window/mftalk.c}). - -@item next -@pindex DrawingServant -@opindex --enable-next -(@samp{--enable-next}) NeXT window system. This requires a separate -program, called @code{DrawingServant}, available separately. See the -@file{web2c/window/next.c}. - -@item regis -@opindex --enable-regiswin -@cindex Regis graphics support -(@samp{--enable-regiswin}) Regis terminals. - -@item sun -@cindex SunView -@cindex Suntools -@opindex --enable-suntoolswin -@flindex sun-gfx.c -(@samp{--enable-suntoolswin}) The old Suntools (not any flavor of X) -window system. (You can get the even older SunWindows @code{gfx} system -by using @file{sun-gfx.c}.) - -@item tek -@cindex Tektronix -@opindex --enable-tektronixwin -(@samp{--enable-tektronixwin}) Tektronix terminals. - -@cindex Poole, Simon -@item uniterm -@cindex Tektronix 4014 -@opindex --enable-unitermwin -(@samp{--enable-unitermwin}) Uniterm, Simon Poole's emulator of a smart -Tektronix 4014 terminal. This may work with regular Tektronix terminals -as well; it's faster than the driver @samp{--enable-tektronixwin} selects. - -@vindex NO_X11WIN -@pindex Xt -@pindex Xlib -@item xterm -@opindex --with-x -@samp{--with-x} The X window system (version 11). - -@opindex --with-mf-x-toolkit=@var{kit} -@cindex toolkits, X -@cindex X toolkits and Metafont -@cindex Xt support -@cindex Xlib support -There are two variants of the X11 support, one that works with the Xt -toolkit, and another that works directly with Xlib. The Xt support is -more efficient and has more functionality, so it is the default. If you -must use the Xlib support, use @samp{configure --with-x ---with-kf-x-toolkit=no}. - -@opindex --disable-mf-nowin -@cindex non-windows-capable Metafont -Specify @samp{--disable-mf-nowin} in order not to build a separate -non-windows-capable Metafont executable @code{mf-nowin} (or -@code{mf-nowin.exe}). - -@cindex X resources -@cindex X class name for Metafont -@cindex class name for Metafont -@cindex geometry for Metafont -@cindex Metafont geometry -@flindex .Xdefaults -@flindex .Xresources -@opindex -geometry@r{, supported with Xt} -You cannot specify any of the usual X options (e.g., @samp{-geometry}) -on the Metafont command line, but you can specify X resources in your -@file{~/.Xdefaults} or @file{~/.Xresources} file. The class name is -@code{Metafont}. If you're using the Xt support, all the usual X toolkit -resources are supported. If you're using the Xlib support, only the -@code{geometry} resource is supported. - -@vindex DISPLAY -You specify the X display to which Metafont connects in the -@code{DISPLAY} environment variable, as usual. - -@end vtable - -@cindex Metafont online support, new devices -@cindex new graphics support for Metafont -@flindex texmfmp.c -Writing support for a new device is straightforward. Aside from defining -the basic drawing routines that Metafont uses (see @file{mf.web}), you -only have to add another entry to the tables on the last page of -@file{web2c/lib/texmfmp.c}. Or you can write an independent program and -use MFtalk (see @file{web2c/window/mftalk.c}). - - -@node gftodvi invocation -@section GFtoDVI: Character proofs of fonts - -@pindex gftodvi -@cindex character proofs of fonts -@cindex font proofs -@cindex proof sheets, of fonts - -GFtoDVI makes @dfn{proof sheets} from a GF bitmap file as output by, for -example, Metafont (@pxref{Metafont}). This is an indispensable aid for -font designers or Metafont hackers. Synopsis: - -@example -gftodvi [@var{option}]@dots{} @var{gfname}[gf] -@end example - -The font @var{gfname} is searched for in the usual places (@pxref{Glyph -lookup,,, kpathsea, Kpathsea}). To see all the relevant paths, set the -environment variable @code{KPATHSEA_DEBUG} to @samp{-1} before running -the program. - -The suffix @samp{gf} is supplied if not already present. This suffix is -not an extension, no @samp{.} precedes it; for instance, @file{cmr10.600gf}. - -The output filename is the basename of @var{gfname} extended with -@file{.dvi}, e.g., @samp{gftodvi /wherever/foo.600gf} creates -@file{./foo.dvi}. - -The characters from @var{gfname} appear one per page in the DVI output, -with labels, titles, and annotations, as specified in Appendix H -(Hardcopy Proofs) of @cite{The Metafontbook}. - -GFtoDVI uses several fonts besides @var{gfname} itself: - -@itemize @bullet -@item -@cindex gray font -@dfn{gray font} (default @file{gray}): for the pixels that actually make -up the character. Simply using black is not right, since then labels, -key points, and other information could not be shown. - -@item -@cindex title font -@dfn{title font} (default @file{cmr8}): for the header information at -the top of each output page. - -@item -@cindex label font -@dfn{label font} (default @file{cmtt10}): for the labels on key points -of the figure. - -@item -@cindex slant font -@dfn{slant font} (no default): for diagonal lines, which are otherwise -simulated using horizontal and vertical rules. -@end itemize - -To change the default fonts, you must use @code{special} commands in -your Metafont source file, typically via commands like @code{slantfont -slantlj4}. There is no default slant font since no one printer is -suitable as a default. You can make your own by copying one of the -existing files, such as -@file{.../fonts/source/public/misc/slantlj4.mf} and then running -@command{mf} on it. - -For testing purposes, you may it useful to run @code{mf-nowin rtest} -(hit RETURN when it stops) to get a @file{gf} file of a thorn glyph. -Or use @command{mf} instead of @command{mf-nowin} to have the glyph(s) -displayed on the screen. After that, @code{gftodvi rtest.2602gf} -should produce @file{rtest.dvi}, which you process as usual. - -The program accepts the following option, as well as the standard -@samp{-verbose}, @samp{-help}, and @samp{-version} (@pxref{Common -options}): - -@table @samp -@item -overflow-label-offset=@var{points} -@opindex -overflow-label-offset=@var{points} -@cindex overflow label offset -@cindex offset for overflow labels -Typeset the so-called overflow labels, if any, @var{points} @TeX{} -points from the right edge of the character bounding box. The default -is a little over two inches (ten million scaled points, to be precise). -Overflow equations are used to locate coordinates when their actual -position is too crowded with other information. -@end table - - -@node mft invocation -@section MFT: Prettyprinting Metafont source - -@pindex mft -@cindex Metafont source, prettyprinting -@cindex prettyprinting Metafont source -@cindex @TeX{}, creating from Metafont - -@flindex mftmac.tex -MFT translates a Metafont program into a @TeX{} document suitable for -typesetting, with the aid of @TeX{} macros defined in the file -@file{mftmac.tex}. Synopsis: - -@example -mft [@var{option}]@dots{} @var{mfname}[.mf] -@end example - -MFT searches the usual places for @var{mfname} (@pxref{Supported file -formats,,, kpathsea, Kpathsea}). To see all the relevant paths, set the -environment variable @code{KPATHSEA_DEBUG} to @samp{-1} before running -the program. The output goes to the basename of @var{mfname} extended -with @file{.tex}, e.g., @samp{mft /wherever/foo.mf} creates -@file{./foo.tex}. - -Line breaks in the input are carried over into the output; moreover, -blank spaces at the beginning of a line are converted to quads of -indentation in the output. Thus, you have full control over the -indentation and line breaks. Each line of input is translated -independently of the others. - -Further control is allowed via Metafont comments: -@cindex comments, MFT control -@itemize @bullet -@item -Metafont comments following a single @samp{%} should be valid @TeX{} -input. But Metafont material can be included within vertical bars in a -comment; this will be translated by MFT as if it were regular Metafont -code. For example, a comment like @samp{% |x2r| is the tip of the bowl} -will be translated into the @TeX{} @samp{% $x_@{2r@}$ is the @dots{}}, -i.e., the @samp{x2r} is treated as an identifier. - -@item -@samp{%%} indicates that the remainder of an input line should be copied -verbatim to the output. This is typically used to introduce additional -@TeX{} material at the beginning or an MFT job, e.g. code to modify the -standard layout or the formatting macros defined in @file{mftmac.tex}, -or to add a line saying @samp{%%\bye} at the end of the job. (MFT -doesn't add this automatically in order to allow processing several -files produces by MFT in the same @TeX{} job.) - -@item -@samp{%%% @var{token1} @var{other-tokens}} -introduces a change in MFT's formatting rules; all the @var{other-tokens} -will henceforth be translated according to the current conventions for -@var{token1}. The tokens must be symbolic (i.e., not -numeric or string tokens). For example, the input line -@example -%%% addto fill draw filldraw -@end example -@noindent -says to format the @samp{fill}, @samp{draw}, and @samp{filldraw} -operations of plain Metafont just like the primitive token @samp{addto}, -i.e., in boldface type. Without such reformatting commands, MFT would -treat @samp{fill} like an ordinary tag or variable name. In fact, you -need a @samp{%%%} command even to get parentheses to act like -delimiters. - -@item -@samp{%%%%} introduces an MFT comment, i.e., MFT ignores the remainder -of such a line. - -@item -Five or more @samp{%} signs should not be used. -@end itemize - -@cindex Knuth, Donald E. -(The above description was edited from @file{mft.web}, written by -@w{D.E. Knuth}.) - -The program accepts the following options, as well as the standard -@samp{-help} and @samp{-version} (@pxref{Common options}): -@table @samp -@item -change=@var{chfile}[.ch] -@opindex -change=@var{chfile} -@cindex change files, and MFT -Apply the change file @var{chfile} as with Tangle and Weave -(@pxref{WEB}). - -@item -style=@var{mftfile}[.mft] -@opindex -style=@var{mftfile} -@cindex style files -@flindex plain.mft -Read @var{mftfile} before anything else; a MFT style file typically -contains only MFT directives as described above. The default style file -is named @file{plain.mft}, which defines this properly for programs -using plain Metafont. The MFT files is searched along the -@code{MFTINPUTS} path; see @ref{Supported file formats,,, kpathsea, Kpathsea}. - -@flindex cmbase.mft -@flindex e.mft -@cindex @cite{Computer Modern Typefaces}, production of -Other examples of MFT style files are @file{cmbase.mft}, which defines -formatting rules for the macros defined in @file{cm.base}, and -@file{e.mft}, which was used in the production of Knuth's Volume@w{ }E, -@cite{Computer Modern Typefaces}. - -@cindex MetaPost source, prettyprinting -Using an appropriate MFT style file, it is also possible to configure -MFT for typesetting MetaPost sources. However, MFT does not search -the usual places for MetaPost input files. -@end table - -If you use eight-bit characters in the input file, they are -passed on verbatim to the @TeX{} output file; it is up to you to -configure @TeX{} to print these properly. - - -@node MetaPost -@chapter MetaPost: Generating PostScript - -@cindex MetaPost -@cindex PostScript meets Metafont -@cindex Metafont meets PostScript -@cindex technical illustrations, creating -MetaPost is a picture-drawing language similar to Metafont -(@pxref{Metafont}), but instead of outputting bitmaps in a ``font'', it -outputs PostScript commands. It's primarily intended for creating -technical illustrations, but can also be used to create PostScript or -OpenType fonts (@url{https://ctan.org/pkg/metatype1}). - -@pindex troff@r{, supported in MetaPost} -MetaPost also provides for arbitrary integration of text and graphics in -a natural way, using any typesetter (@TeX{} and Troff are both -supported) and a number of other subsidiary programs, described below. - -@menu -* mpost invocation:: Invoking MetaPost. -* Initial MetaPost:: Making mems. -* dvitomp invocation:: DVI-to-MPX translation. -@end menu - - -@node mpost invocation -@section @code{mpost} invocation - -@pindex mpost -@cindex MetaPost invocation - -@flindex mpman.pdf -MetaPost (installed as @code{mpost}) reads a series of pictures -specified in the MetaPost programming language, and outputs -corresponding PostScript code. This section merely describes the -options available in the Web2c implementation. For a complete -description of the MetaPost language, see AT&T technical report -CSTR-162, generally available in @file{@var{texmf}/doc/metapost/}, -where @var{texmf} is the root of @TeX{} directory structure. -The MetaPost home page: @url{https://tug.org/metapost}. - -@flindex mpgraph.pdf -Also, a standard MetaPost package for drawing graphs is documented in -AT&T technical report CSTR-164, available as the file @file{mpgraph.ps}, -generally stored alongside @file{mpman.ps}. - -MetaPost processes its command line and determines its memory dump -(mem) file in a way analogous to Metafont and @TeX{} (@pxref{tex -invocation,,@code{tex} invocation}, and @pxref{Memory dumps}). -Synopses: - -@example -mpost [@var{option}]@dots{} [@var{mpname}[.mp]] [@var{mp-commands}] -mpost [@var{option}]@dots{} \@var{first-line} -mpost [@var{option}]@dots{} &@var{mem} @var{args} -@end example - -@flindex .mp -@cindex MetaPost input files -MetaPost searches the usual places for the main input file @var{mpname} -(@pxref{Supported file formats,,, kpathsea, Kpathsea}), extending -@var{mpname} with @file{.mp} if necessary. To see all the relevant -paths, set the environment variable @code{KPATHSEA_DEBUG} to @samp{-1} -before running the program. - -@findex beginfig -@flindex .@var{nnn} @r{PostScript figures} -@flindex .tfm @r{output} -@flindex mpout -@cindex TFM files, output by MetaPost -@cindex PostScript output -MetaPost writes its PostScript output to a series of files -@file{@var{basempname}.@var{nnn}} (or perhaps -@file{@var{basempname}.ps}, very occasionally -@file{@var{basempname}.tfm}), where @var{nnn} are the figure numbers -specified in the input, typically to the @code{beginfig} macro, and -@var{basempname} is the basename of @var{mpname}, or @samp{mpout} if no -input file was specified. MetaPost uses the @samp{.ps} extension when -the figure number is out of range, e.g., if you say @code{beginfig(-1)}. - -You can use the output files as figures in a @TeX{} document just as -with any other PostScript figures. For example, with this @TeX{} command: -@example -\special@{psfile="@var{filename}"@} -@end example -@noindent -or by using @file{epsf.tex} (@pxref{EPSF macros,,, dvips, Dvips}). - -@findex btex @r{for MetaPost labels} -@findex etex @r{for MetaPost labels} -The MetaPost construct -@example -btex @dots{} @var{tex-input} @dots{} etex -@end example -@noindent -generates a MetaPost picture expression corresponding to -@var{tex-input}. - -The construct -@example -verbatimtex @dots{} @var{tex-input} @dots{} etex -@end example -@noindent -simply passes the @var{tex-input} through to -@TeX{}. For example, if you are using @LaTeX{}, your MetaPost input file -must start with a @code{verbatimtex} block that gives the necessary -@code{\documentclass} (or @code{\documentstyle}) -@code{\begin@{document@}} command. You will also need to set the -enviroment variable @code{TEX} to @samp{latex}. - -@var{tex-input} need not be specifically @TeX{} input; it could also be -Troff. In that case, you will need the @samp{-m pictures} Troff macro -package (unfortunately absent from many Troff implementations), or an -equivalent such as the @samp{-m pspic} macros from GNU groff described -in grops(1). - -@cindex PostScript fonts, and Troff -@cindex Troff, and MetaPost -@cindex Computer Modern fonts, and Troff -Naturally, you must use fonts that are supported by the typesetter; -specifically, you'll probably want to use standard PostScript fonts with -Troff. And only the @TeX{} system understands Computer Modern or other -Metafont fonts; you can also use PostScript fonts with @TeX{}, of course. - -@flindex mproof.tex -@cindex downloading of fonts for MetaPost labels -@cindex font downloading for MetaPost labels -MetaPost-generated PostScript figures which do use Computer Modern fonts -for labels cannot be directly previewed or printed. Instead, you must -include them in a @TeX{} document and run the resulting DVI file through -Dvips to arrange for the downloading of the required fonts (@pxref{Fonts -in figures,,, dvips, Dvips}). To help with this, the MetaPost -distribution provides a small @TeX{} file @file{mproof.tex} which is -typically called as: -@example -tex mproof @var{mp-output-files}... ; dvips mproof -o -@end example -@noindent -The resulting file @file{mproof.ps} can then be printed or previewed. - -@vindex prologues@r{, and EPSF output} -@flindex psfonts.map@r{, read by MetaPost} -To generate EPSF files, set the internal MetaPost variable -@code{prologues} positive. To make the output files self-contained, use -only standard PostScript fonts. MetaPost reads the same -@file{psfonts.map} file as Dvips, to determine PostScript fonts that -need to be downloaded (@pxref{psfonts.map,,, dvips, Dvips}). - -@cindex PDF, and @code{.mps} files -@cindex @code{.mps} files and PDF -It is posible for pdf@TeX{} to read MetaPost output directly; this is -in contrast to general EPSF files, which have to be converted for use -with PDF output. The easiest way is to name the MetaPost output files -with the @code{.mps} extension. Then the @LaTeX{} -@code{\includegraphics} command, for example, will be able to read -them, even when outputting PDF. - -@cindex security, and @code{write} -MetaPost can write output files, via the @code{write} primitive; this -opens a security hole. @xref{tex invocation}. - -The program accepts the following options, as well as the standard -@samp{-help} and @samp{-version} (@pxref{Common options}): -@table @samp -@item -[no]-file-line-error -@itemx -fmt=@var{fmtname} -@itemx -halt-on-error -@itemx -ini -@itemx -interaction=@var{string} -@itemx -jobname=@var{string} -@itemx -kpathsea-debug=@var{number} -@itemx -[no]parse-first-line -@itemx -output-directory -@itemx -progname=@var{string} -@itemx -recorder -@itemx -translate-file=@var{tcxfile} -@itemx -8bit -These options are common to @TeX{}, Metafont, and MetaPost. -@xref{Common options}. - -@item -T -@itemx -troff -@opindex -T -@opindex -troff -@vindex prologues -Set the @code{prologues} internal variable to @code{1}. - -@item -tex=@var{texprogram} -@opindex -tex=@var{texprogram} -When this option is given, the program @var{texprogram} is used to -typeset the labels. - -@end table - - -@node Initial MetaPost -@section Initial MetaPost - -@cindex initial MetaPost -@cindex MetaPost, initial - -As of MetaPost 1.504 (@TeX{} Live 2011), MetaPost no longer dumps -@file{.mem} files (@pxref{Memory dumps}) and does not distinguish -virgin and initial forms (@pxref{Initial and virgin}). Instead, the -``initial'' file name is read in its source form---that is, -@file{mpost.mp} when the program is invoked as @command{mpost}. - -For a list of options and other information, see @ref{mpost invocation}. - -@cindex Metafont, compatibility in MetaPost -@cindex plain Metafont, compatibility in MetaPost -@cindex MetaPost and plain Metafont compatibility -@flindex mfplain -MetaPost provides a format with all the features of plain Metafont, -called @file{mfplain}. You can use that in the same way; just run -@command{mfplain} instead of @command{mpost}. This lets you directly -process Metafont source files with MetaPost, producing character -proofs (one file for each character) similar to those produced with -Metafont in proof mode and GFtoDVI (@pxref{gftodvi invocation}). - - -@node dvitomp invocation -@section DVItoMP: DVI to MPX conversion - -@pindex dvitomp -@cindex DVI files, converting to MPX -@cindex MPX files, converting from DVI files - -DVItoMP converts DVI files into low-level MetaPost commands in a -so-called MPX file. Synopsis: - -@example -dvitomp @var{dvifile}[.dvi] [@var{mpxfile}[.mpx]] -@end example - -@noindent -If @var{mpxfile} is not specified, the output goes to the basename of -@var{dvifile} extended with @file{.mpx}, e.g., @samp{dvitomp -/wherever/foo.dvi} creates @file{./foo.mpx}. - -@cindex color, in DVItoMP -DVItoMP supports Dvips-style color specials, such as @samp{color push -@var{name}} and @samp{color pop}, outputting them as @code{withcolor} -MetaPost commands. - -The only options are @samp{-help} and @samp{-version} (@pxref{Common -options}). - - -@node BibTeX -@chapter Bib@TeX{}: Bibliographies - -@cindex bibliographies, creating -@cindex Bib@TeX{} - -Bib@TeX{} automates much of the job of typesetting bibliographies, and -makes bibliography entries reusable in many different contexts. - -@menu -* bibtex invocation:: -* Basic BibTeX style files:: The standard and semi-standard styles. -@end menu - - -@node bibtex invocation -@section Bib@TeX{} invocation - -@pindex bibtex - -@flindex .bbl @r{bibliography files} -@flindex .aux @r{cross-reference files} -@flindex .bib @r{bibliography databases} -Bib@TeX{} creates a printable bibliography (@file{.bbl}) file from -references in a @file{.aux} file, generally written by @TeX{} or -@LaTeX{}. The @file{.bbl} file is then incorporated on a subsequent -run. The basic bibliographic information comes from @file{.bib} files, -and a Bib@TeX{} style (@file{.bst}) file controls the precise contents -of the @file{.bbl} file. Synopsis: - -@example -bibtex [@var{option}]@dots{} @var{auxfile}[.aux] -@end example - -@flindex .blg @r{Bib@TeX{} log file} -@cindex log file, Bib@TeX{} -@noindent -The output goes to the basename of @var{auxfile} extended with -@file{.bbl}; for example, @samp{bibtex /wherever/foo.aux} creates -@file{./foo.bbl}. Bib@TeX{} also writes a log file to the basename of -@var{auxfile} extended with @samp{.blg}. - -@findex \bibliography -@findex \bibliographystyle -@vindex TEXBIB@r{, search path for bib files} -@vindex BIBINPUTS@r{, search path for bib files} -@vindex BSTINPUTS@r{, search path for bst files} -The names of the @file{.bib} and @file{.bst} files are specified in the -@file{.aux} file as well, via the @file{\bibliography} and -@file{\bibliographystyle} (La)@TeX{} macros. Bib@TeX{} searches for -@file{.bib} files using the @code{BIBINPUTS} and @code{TEXBIB} paths, -and for @file{.bst} files using @code{BSTINPUTS} (@pxref{Supported file -formats,,,kpathsea,Kpathsea}). It does no path searching for -@file{.aux} files. - -The program accepts the following options, as well as the standard -@samp{-help} and @samp{-version} (@pxref{Common options}): -@table @samp -@item -terse -@opindex -terse -@cindex terse output -@cindex verbose Bib@TeX{} output, suppressing -Suppress the program banner and progress reports normally output. - -@item -min-crossrefs=@var{n} -@opindex -min-crossrefs=@var{n} -@cindex cross-referenced bibliography items -@cindex bibliography items, cross-referenced -If at least @var{n} (2 by default) bibliography entries refer to another -entry @var{e} via their @code{crossref} field, include @var{e} in the -@t{.bbl} file, even if it was not explicitly referenced in the @t{.aux} -file. For example, @var{e} might be a conference proceedings as a whole, -with the cross-referencing entries being individual articles published -in the proceedings. - -If you want to avoid these automatic inclusions altogether, make -@var{n} a sufficiently large number, and be sure to remove any -previous @t{.aux} and @t{.bbl} files. Otherwise the option may -appear to have no effect, since Bib@TeX{} will have added the citation -for @var{e} to the @t{.aux}, and nothing will remove it. - -@end table - -See also: -@table @file -@item btxdoc.tex -@flindex btxdoc.tex -Basic @LaTeX{}able documentation for general Bib@TeX{} users. - -@item btxhak.tex -@flindex btxhak.tex -@cindex style design, for Bib@TeX{} -@LaTeX{}able documentation for style designers. - -@item btxdoc.bib -@flindex btxdoc.bib -Bib@TeX{} database file for the two above documents. - -@item xampl.bib -@flindex xampl.bib -Example database file with all the standard entry types. - -@item @url{ftp://ftp.math.utah.edu/pub/tex/bib/} -@flindex ftp.math.utah.edu -@cindex Bib@TeX{} collection -@cindex TUGboat bibliography -@cindex @TeX{}, bibliographies for -A very large @file{.bib} and @file{.bst} collection, including -references for all the standard @TeX{} books and a complete bibliography -for TUGboat. -@end table - - -@node Basic BibTeX style files -@section Basic Bib@TeX{} style files - -@cindex basic Bib@TeX{} style files -@cindex Bib@TeX{} style files - -Here are descriptions of the four standard and four semi-standard basic -Bib@TeX{} styles. @file{@var{CTAN:}/biblio/bibtex} contains these and -many more (for CTAN info, @pxref{unixtex.ftp,,, kpathsea, Kpathsea}). - -@table @code -@item plain -@flindex plain.bst -Sorts entries alphabetically, with numeric labels. Generally formatted -according to van Leunen's @cite{A Handbook for Scholars}. The other -style files listed here are based on @code{plain}. - -@item abbrv -@flindex abbrv.bst -First names, month names, and journal names are abbreviated. - -@item acm -@flindex acm.bst -Names are printed in small caps. - -@item alpha -@flindex alpha.bst -Alphanumeric labels, e.g., @samp{Knu66}. - -@item apalike -@flindex apalike.bst -No labels at all; instead, the year appears in parentheses after the author. -Use this in conjunction with @file{apalike.tex} (plain @TeX{}) or -@file{apalike.sty} (@LaTeX{}), which also changes the citations in the -text to be @samp{(@var{author}, @var{year})}. - -@item ieeetr -@flindex ieeetr.bst -Numeric labels, entries in citation order, @sc{ieee} abbreviations, -article titles in quotes. - -@item siam -@flindex siam.bst -Numeric labels, alphabetic order, @cite{Math.@: Reviews} -abbreviations, names in small caps. - -@item unsrt -@flindex unsrt.bst -Lists entries in citation order, i.e., unsorted. - -@item btxbst.doc -The template file and documentation for the standard styles. - -@end table - - -@node WEB -@chapter WEB: Literate programming - -@cindex WEB -@cindex literate programming - -@dfn{WEB} languages allow you to write a single source file that can -produce both a compilable program and a well-formatted document -describing the program in as much detail as you wish to prepare. -Writing in this kind of dual-purpose language is called @dfn{literate -programming}. (The Usenet newsgroup @file{comp.programming.literate} -is devoted to this subject.) - -@flindex webman.tex -@cindex Spiderweb -@cindex Cweb -@cindex CWEB -@cindex Awk, WEB for -@cindex Ada, WEB for -@cindex Troff, WEB for -WEB-like languages have been implemented with many pairs of base -languages: Cweb provides C and Troff (@pxref{References}); CWEB provides -C and @TeX{} (@file{@var{CTAN:}/web/c_cpp/cweb}); Spiderweb provides C, -C++, Awk, Ada, many others, and @TeX{} -(@file{@var{CTAN:}/web/spiderweb}); and, of course, the original WEB -provides Pascal and @TeX{}, the implementation languages for the -original @TeX{}, Metafont, MetaPost, and related programs to come from -the @TeX{} project at Stanford. - -The original WEB language is documented in the file @file{webman.tex}, -which is included in the @url{ftp://ftp.tug.org/tex/lib.tar.gz} archive -(and available in many other places, of course). - -@menu -* tangle invocation:: -* weave invocation:: -* pooltype invocation:: -@end menu - - -@node tangle invocation -@section Tangle: Translate WEB to Pascal - -@pindex tangle -@cindex Pascal, creating from WEB -@cindex WEB programs, compiling - -Tangle creates a compilable Pascal program from a WEB source file -(@pxref{WEB}). Synopsis: - -@example -tangle [@var{option}]@dots{} @var{webfile}[.web] [@var{changefile}[.ch]] -@end example - -@cindex change files, and Tangle -@noindent -The Pascal output is written to the basename of @var{webfile} extended -with @samp{.p}; for example, @samp{tangle /wherever/foo.web} creates -@file{./foo.p}. Tangle applies @var{changefile} to @var{webfile} before -writing the output; by default, there is no change file. - -@cindex pool file, writing -@cindex string pool, writing -If the program makes use of the WEB string facility, Tangle writes the -string pool to the basename of @var{webfile} extended with @samp{.pool}. - -The Pascal output is packed into lines of 72 characters or less, with -the only concession to readability being the termination of lines at -semicolons when this can be done conveniently. - -The program accepts the following options, as well as the standard -@samp{--help} and @samp{--version} (@pxref{Common options}): - -@table @samp -@item -length=@var{number} -@opindex -length=@var{number} -@cindex identifier length -The number of characters that are considered significant in an -identifier. Whether underline characters are counted depends on the -@samp{-underline} option. The default value is 32, the original tangle -used 7, but this proved too restrictive for use by Web2c. - -@item -lowercase -@itemx -mixedcase -@itemx -uppercase -@opindex -lowercase -@opindex -mixedcase -@opindex -uppercase -@cindex identifier case -These options specify the case of identifiers in the output of tangle. -If @samp{-uppercase} (@samp{-lowercase}) is specified, tangle will -convert all identfiers to uppercase (lowercase). The default is -@samp{-mixedcase}, which specifies that the case will not be changed. - -@item -underline -@opindex -underline -@cindex identifiers with underlines -When this option is given, tangle does not strip underline characters -from identifiers. - -@item -loose -@itemx -strict -@opindex -loose -@opindex -strict -@cindex identifier collisions -These options specify how strict tangle must be when checking -identifiers for equality. The default is @samp{-loose}, which means -that tangle will follow the rules set by the case-smashing and underline -options above. If @samp{-strict} is set, then identifiers will always -be stripped of underlines and converted to uppercase before checking -whether they collide. - -@end table - -@node weave invocation -@section Weave: Translate WEB to @TeX{} - -@pindex weave -@cindex @TeX{}, creating from WEB -@cindex WEB programs, typesetting -@cindex prettyprinting WEB programs - -Weave creates a @TeX{} document from a WEB source file (@pxref{WEB}), -assuming various macros defined in @file{webmac.tex}. It takes care of -typographic details such as page layout, indentation, and italicizing -identifiers. It also automatically gathers and outputs extensive -cross-reference information. Synopsis: - -@example -weave [@var{option}]@dots{} @var{webfile}[.web] [@var{changefile}[.ch]] -@end example - -@cindex change files, and Weave -@noindent -The output is to the basename of @var{webfile} extended with -@samp{.tex}; for example, @samp{weave /wherever/foo.web} creates -@file{./foo.tex}. Weave applies @var{changefile} to @var{webfile} -before writing the output; by default, there is no change file. - -The program accepts the following option, as well as the standard -@samp{-verbose}, @samp{-help} and @samp{-version} (@pxref{Common -options}): -@table @samp -@item -x -@opindex -x -@cindex cross-references, omitting -@flindex CONTENTS.tex -@flindex webmac.tex -Omit the cross-reference information: the index, the list of WEB module -names, and the table of contents (an empty @file{CONTENTS.tex} file will -still be written when the Weave output file is processed by @TeX{} using -the default @file{webmac.tex}, though). -@end table - -Conventionally, WEB programmers should define the @TeX{} @code{\title} -macro at the beginning of the source file. Also, to get output of only -changed modules, one can say @code{\let\maybe=\iffalse} (usually as the -first change in the change file). - - -@node pooltype invocation -@section Pooltype: Display WEB pool files - -@pindex pooltype -@cindex type programs, pool -@cindex string numbers, displaying -@cindex WEB pool files, displaying - -Pooltype shows the so-called @dfn{string number} of each string in a WEB -pool file (@pxref{WEB}), as output by Tangle (@pxref{tangle -invocation}), including the first 256 strings corresponding to the -possible input characters. Pooltype primarily serves as an example of -WEB conventions to implementors of the @TeX{} system. Synopsis: - -@example -pooltype [@var{option}]@dots{} @var{poolfile}[.pool] -@end example - -@noindent -No path searching is done for @var{poolfile}. Output is to standard -output. - -The only options are @samp{--help} and @samp{--version} (@pxref{Common -options}). - -As an example of the output, here is the (edited) output for @file{tex.pool}: -@example -0: "^^@@" -1: "^^A" -@dots{} -255: "^^ff" -256: "pool size" -@dots{} -1314: "Using character substitution: " -(23617 characters in all.) -@end example - -@cindex representation of strings -@cindex string representation -In Metafont and MetaPost, the first 256 characters are actually -represented as single bytes (i.e., themselves), not in the @samp{^^} -notation. Consider Pooltype as showing the results after conversion for -output. - - -@node DVI utilities -@chapter DVI utilities - -@cindex DVI utilities - -@TeX{} outputs a file in @dfn{DVI} (DeVice Independent) format as a -compact representation of the original document. DVI files can be -translated to meet the requirements of a real physical device, such as -PostScript printers (@pxref{Top,, Introduction, dvips, Dvips}), PCL -printers (see dvilj(1)), and X displays (see xdvi(1)). In fact, DVI -translators are available for virtually all common devices: see -@file{@var{CTAN:}/dviware} (for CTAN info, @pxref{unixtex.ftp,,, -kpathsea, Kpathsea}). - -@flindex dvitype.web -@cindex DVI format definition -For the precise definition of the DVI file format, see (for example) the -source file @file{web2c/dvitype.web}. - -The DVI-processing programs in the Web2c distribution are not device -drivers; they perform generic utility functions. - -@menu -* dvicopy invocation:: Expand virtual fonts. -* dvitype invocation:: DVI to human-readable text. -@end menu - -@node dvicopy invocation -@section DVIcopy: Canonicalize virtual font references - -@pindex dvicopy -@cindex virtual fonts, expanding - -DVIcopy reads a DVI file, expands any references to virtual fonts -(@pxref{Virtual fonts,,, dvips, Dvips}) to base fonts, and writes the -resulting DVI file. Thus you can use virtual fonts even if your DVI -processor does not support them, by passing the documents through -DVIcopy first. Synopsis: - -@example -dvicopy [@var{option}]@dots{} [@var{indvi}[.dvi] [@var{outdvi}[.dvi]]] -@end example - -DVIcopy reads standard input if @var{indvi} is not specified, and writes -standard output if @var{outdvi} is not specified. - -The program accepts the following options, as well as the standard -@samp{-help} and @samp{-version} (@pxref{Common options}): -@table @samp -@item -magnification=@var{integer} -@opindex -magnification=@var{integer} -@cindex magnification -@findex \mag -Override existing magnification in @var{indvi} with @var{integer}; 1000 -specifies no magnification. This is equivalent to setting @TeX{}'s -@code{\mag} parameter. - -@item -max-pages=@var{n} -@opindex -max-pages=@var{n} -Process @var{n} pages; default is one million. - -@item -page-start=@var{page-spec} -@opindex -page-start=@var{page-spec} -@cindex starting page -@cindex page, starting -@findex \count@var{n} -Start at the first page matching @var{page-spec}, which is one or more -(signed) integers separated by periods, corresponding to @TeX{}'s -@code{\count0@dots{}9} parameters at @code{\shipout} time; @samp{*} -matches anything. Examples: @samp{3}, @samp{1.*.-4}. -@end table - - -@node dvitype invocation -@section DVItype: Plain text transliteration of DVI files - -@pindex dvitype @r{DVI validation} -@cindex conversion, DVI to plain text -@cindex plain text, converting DVI to -@cindex human-readable text, converting DVI to -@cindex type programs, DVI -@cindex validation, of DVI files - -DVItype translates a DeVice Independent (DVI) file (as output by @TeX{}, -for example) to a plain text file that humans can read. It also serves -as a DVI-validating program, i.e., if DVItype can read a file, it's -correct. Synopsis: - -@example -dvitype [@var{option}]@dots{} @var{dvifile}[.dvi] -@end example - -@noindent -DVItype does not read any bitmap files, but it does read TFM files for -fonts referenced in @var{dvifile}. The usual places are searched -(@pxref{Supported file formats,,, kpathsea, Kpathsea}). To see all the -relevant paths, set the environment variable @code{KPATHSEA_DEBUG} to -@samp{-1} before running the program. - -Output goes to standard output. - -The program accepts the following options, as well as the standard -@samp{-help} and @samp{-version} (@pxref{Common options}): -@table @samp -@item -dpi=@var{real} -@opindex -dpi=@var{real} -Do pixel movement calculations at @var{real} pixels per inch; default -300.0. - -@item -magnification=@var{integer} -@opindex -magnification=@var{integer} -@cindex magnification -@findex \mag -Override existing magnification in @var{indvi} with @var{integer}; 1000 -specifies no magnification. This is equivalent to setting @TeX{}'s -@code{\mag} parameter. - -@item -max-pages=@var{n} -@opindex -max-pages=@var{n} -Process @var{n} pages; default is one million. - -@item -output-level=@var{n} -@opindex -output-level=@var{n} -Verbosity level of output, from 0 to 4 (default 4): -@itemize @bullet -@item 0: Global document information only. -@item 1: Most DVI commands included, and typeset characters summarized. -@item 2: Character and movement commands explicitly included. -@item 3: DVI stack and current position calculations included. -@item 4: Same information as level 3, but DVItype does random positioning -in the file, reading the DVI postamble first. -@end itemize - -@item -page-start=@var{page-spec} -@opindex -page-start=@var{page-spec} -@cindex starting page -@cindex page, starting -@findex \count@var{n} -Start at the first page matching @var{page-spec}, which is one or more -(signed) integers separated by periods, corresponding to @TeX{}'s -@code{\count0@dots{}9} parameters at @code{\shipout} time; @samp{*} -matches anything. Examples: @samp{1}, @samp{5.*.-9}. - -@item -show-opcodes -@opindex -show-opcodes -@cindex opcodes, showing DVI -@cindex DVI opcodes, showing -@cindex debugging DVI utilities -Show numeric opcode values (in decimal) for DVI commands, in braces -after the command name. This can help in debugging DVI utilities. We -use decimal because in the DVI format documentation (in -@file{dvitype.web}, among others) the opcodes are shown in decimal. -@end table - -@menu -* dvitype output example:: -@end menu - - -@node dvitype output example -@subsection DVItype output example - -@cindex dvitype output example -As an example of the output from DVItype (see section above), here is -its (abridged) translation of the @file{story.dvi} resulting from -running the example in @cite{The @TeX{}book}, with -@samp{-output-level=4} and @samp{-show-opcodes} on. - -@example -@dots{} -Options selected: - Starting page = * - Maximum number of pages = 1000000 - Output level = 4 (the works) - Resolution = 300.00000000 pixels per inch -numerator/denominator=25400000/473628672 -magnification=1000; 0.00006334 pixels per DVI unit -' TeX output 1992.05.17:0844' -Postamble starts at byte 564. -maxv=43725786, maxh=30785863, maxstackdepth=3, totalpages=1 -Font 33: cmsl10---loaded at size 655360 DVI units -Font 23: cmbx10---loaded at size 655360 DVI units -Font 0: cmr10---loaded at size 655360 DVI units - -42: beginning of page 1 -87: push @{141@} -level 0:(h=0,v=0,w=0,x=0,y=0,z=0,hh=0,vv=0) -88: down3 -917504 @{159@} v:=0-917504=-917504, vv:=-58 -92: pop @{142@} -@dots{} -104: putrule @{137@} height 26214, width 30785863 (2x1950 pixels) -113: down3 5185936 @{159@} v:=655360+5185936=5841296, vv:=370 -117: push @{141@} -level 1:(h=0,v=5841296,w=0,x=0,y=0,z=0,hh=0,vv=370) -118: right4 12265425 @{146@} h:=0+12265425=12265425, hh:=777 -[ ] -123: fntdef1 23 @{243@}: cmbx10 -145: fntnum23 @{194@} current font is cmbx10 -146: setchar65 h:=12265425+569796=12835221, hh:=813 -147: w3 251220 @{150@} h:=12835221+251220=13086441, hh:=829 -151: setchar83 h:=13086441+418700=13505141, hh:=856 -@dots{} -164: setchar82 h:=17448202+565245=18013447, hh:=1142 -165: x0 -62805 @{152@} h:=18013447-62805=17950642, hh:=1138 -166: setchar89 h:=17950642+569796=18520438, hh:=1174 -[A SHORT STORY] -167: pop @{142@} -level 1:(h=0,v=5841296,w=0,x=0,y=0,z=0,hh=0,vv=370) -@dots{} -550: pop @{142@} -level 0:(h=0,v=42152922,w=0,x=0,y=0,z=0,hh=0,vv=2670) -551: down3 1572864 @{159@} v:=42152922+1572864=43725786, vv:=2770 -555: push @{141@} -level 0:(h=0,v=43725786,w=0,x=0,y=0,z=0,hh=0,vv=2770) -556: right4 15229091 @{146@} h:=0+15229091=15229091, hh:=965 -561: setchar49 h:=15229091+327681=15556772, hh:=986 -[ 1] -562: pop @{142@} -level 0:(h=0,v=43725786,w=0,x=0,y=0,z=0,hh=0,vv=2770) -563: eop @{140@} -@end example - -Explanation: - -@itemize @bullet -@item -The DVItype options are recorded at the beginning, followed by -global information about the document, including fonts used. - -@item -Each DVI command is preceded by its byte position in the file -(@samp{42:}, @samp{87:}, @dots{}), and (because of the -@samp{-show-opcodes}) followed by its decimal opcode value in braces -(@samp{@{141@}}, @samp{@{142@}}, @dots{}). - -@item -The @samp{level} lines record information about the DVI stack; @samp{h} -and @samp{v} define the current position in DVI units, while @samp{hh} -and @samp{vv} are the same in pixels. - -@item -Text sequences are summarized in brackets, as in @samp{[A SHORT -STORY]} and the @samp{[ 1]}. -@end itemize - - -@node Font utilities -@chapter Font utilities - -@cindex font utilities - -The Web2c programs described here convert between various @TeX{}-related -font formats; the first section below briefly describes the -formats. GFtoPK is the only one that is routinely used, as Metafont -outputs GF format, but it's most efficient for device drivers to use PK. - -@flindex pktype.web -@flindex gftype.web -@cindex PK format definition -@cindex GF format definition -The precise definitions of the PK, GF, TFM, PL, VF, and VPL formats -mentioned below are in the source files that read them; -@file{pktype.web}, @file{gftype.web}, @file{tftopl.web}, etc. - -@menu -* Font file formats:: Explanations of GF, PK, TFM, VF, ... -* gftopk invocation:: GF -> PK (compact) -* pktogf invocation:: PK -> GF (expand). -* pktype invocation:: PK -> human-readable text. -* gftype invocation:: GF -> human-readable text. -* tftopl invocation:: TFM -> PL (for editing TFM). -* pltotf invocation:: PL -> TFM (make editing results usable). -* vftovp invocation:: VF -> VPL (tftopl for virtual fonts). -* vptovf invocation:: VPL -> VF (pltotf for virtual fonts). -* Font utilities available elsewhere:: Type 1, BDF, editors, etc. -@end menu - - -@node Font file formats -@section Font file formats - -@cindex font file formats -@cindex file formats for fonts - -(For another perspective on this, @pxref{Font concepts,,, dvips, -Dvips}). - -Font files come in several varieties, with suffixes like: -@example -.tfm .*pk .*gf .*pxl@r{ (obsolete)} .pl .mf .vf .vpl -@end example -@noindent -Each represents a file format. - -@cindex TFM files, explained -A TFM (@TeX{} font metric) file is a compact binary file that contains -information about each character in a font, about combinations of -characters within that font, and about the font as a whole. The font -metric information contained in TFM files is device-independent units is -used by @TeX{} to do typesetting. Unlike the bitmap (raster) fonts -described below, TFM font files contain no information about the shapes -of characters. They describe rectangular areas and combinations -thereof, but not what will eventually be printed in those areas. - -@cindex scaling of fonts -@cindex optical font scaling -@cindex geometric font scaling -@cindex PostScript, and font scaling -Since @TeX{} does scaling calculations, one TFM file serves for all -magnifications of a given typeface. On the other hand, the best printed -results are obtained when magnified (or reduced fonts) are not produced -geometrically (as done by PostScript, for example) but rather optically, -with each size a separate design (as done with Computer Modern and the -EC fonts, for example); then a separate TFM file is needed for each -size. - -@cindex DVI files, explained -At any rate, @TeX{} produces a DVI (DeVice Independent) file from your -source document. In order to print DVI files on real devices, you need -font files defining digitized character shapes and other data. Then -previewers and printer-driver programs can translate your DVI files into -something usable by your monitor or printer. Bitmap fonts come with -suffixes such as @samp{.600pk} or @samp{.600gf} or @samp{.3000pxl}, where -the @samp{600} is the horizontal dots-per-inch resolution at which the -font was produced, and the @samp{pk} or @samp{gf} or @samp{pxl} -indicates the font format. Outline fonts in PostScript Type 1 format -have suffixes such as @samp{.pfa} or @samp{.pfb}. - -@cindex PXL files, explained -@cindex PK files, explained -@cindex GF files, explained -Fonts in pk (packed) format are in the tightly packed raster format that -is pretty much the standard today. They take up less space than fonts -in the gf (generic font) format that Metafont generates, and far less -space than fonts in pxl format. Fonts in pxl format take up gross -amounts of disk space and permit only 128 characters. They are -obsolete. - -@cindex PL files, explained -Font files with the @samp{.pl} (property list) suffix are the plain text -(human-readable) analog of the binary @samp{.tfm} files. -The TFtoPL and PLtoTF programs convert between the two formats -(@pxref{tftopl invocation} and @ref{pltotf invocation}). - -Font files with the @samp{.mf} suffix are in Metafont source format. -These are the files used by Metafont to generate rastered fonts for -specific typefaces at specific magnifications for the specific -resolution and type of mapping used by your device. - -@flindex virtual-fonts.knuth -@flindex virtualfonts.txt -The suffix @samp{.vf} identifies ``virtual font'' files, for which -@samp{.vpl} is the human-readable analog. See @xref{vftovp invocation}, -and @ref{vptovf invocation}. For further discussion of virtual fonts, -see @file{@var{CTAN:}/doc/virtual-fonts.knuth}, -@file{@var{CTAN:}/help/virtualfonts.txt}, and @ref{Virtual fonts,,, -dvips, Dvips}. - -@cindex MacKay, Pierre -@cindex Tachikawa, Elizabeth -(This section is based on documentation in the original Unix @TeX{} -distribution by Pierre MacKay and Elizabeth Tachikawa.) - - -@node gftopk invocation -@section GFtoPK: Generic to packed font conversion - -@pindex gftopk -@cindex conversion, GF to PK -@cindex PK, converting GF to -@cindex GF, converting to PK - -GFtoPK converts a generic font (GF) file output by, for example, -Metafont (@pxref{mf invocation}) to a packed font (PK) file. PK files -are considerably smaller than the corresponding gf files, so they are -generally the bitmap font format of choice. Some DVI-processing -programs, notably Dvips, only support PK files and not GF files. -Synopsis: - -@example -gftopk [@var{option}]@dots{} @var{gfname}.@var{dpi}[gf] [@var{pkfile}] -@end example - -@noindent -The font @var{gfname} is searched for in the usual places (@pxref{Glyph -lookup,,, kpathsea, Kpathsea}). To see all the relevant paths, set the -environment variable @code{KPATHSEA_DEBUG} to @samp{-1} before running -the program. - -The suffix @samp{gf} is supplied if not already present. This suffix is -not an extension; no @samp{.} precedes it: for instance, -@file{cmr10.600gf}. - -If @var{pkfile} is not specified, the output is written to the basename -of @samp{@var{gfname}.@var{dpi}pk}, e.g., @samp{gftopk -/wherever/cmr10.600gf} creates @file{./cmr10.600pk}. - -The only options are @samp{--verbose}, @samp{--help}, and -@samp{--version} (@pxref{Common options}). - - -@node pktogf invocation -@section PKtoGF: Packed to generic font conversion - -@pindex pktogf -@cindex conversion, PK to GF -@cindex GF, converting PK to -@cindex PK, converting to GF - -PKtoGF converts a packed font (PK) file to a generic font (GF) file. -Since PK format is much more compact than GF format, the most likely -reason to do this is to run GFtype (@pxref{gftype invocation}) on the -result, so you can see the bitmap images. Also, a few old utility -programs do not support PK format. Synopsis: - -@example -pktogf [@var{option}]@dots{} @var{pkname}.@var{dpi}[pk] [@var{gffile}] -@end example - -@noindent -The font @var{pkname} is searched for in the usual places (@pxref{Glyph -lookup,,, kpathsea, Kpathsea}). To see all the relevant paths, set the -environment variable @code{KPATHSEA_DEBUG} to @samp{-1} before running -the program. - -The suffix @samp{pk} is supplied if not already present. This suffix is -not an extension; no @samp{.} precedes it: for instance, -@file{cmr10.600pk}. - -If @var{gffile} is not specified, the output is written to the basename -of @samp{@var{pkname}.@var{dpi}gf}, e.g., @samp{pktogf -/wherever/cmr10.600pk} creates @file{./cmr10.600gf}. - -The only options are @samp{--verbose}, @samp{--help}, and -@samp{--version} (@pxref{Common options}). - - -@node pktype invocation -@section PKtype: Plain text transliteration of packed fonts - -@pindex pktype @r{PK validation} -@cindex conversion, PK to plain text -@cindex plain text, converting PK to -@cindex human-readable text, converting PK to -@cindex type programs, PK -@cindex validation, of PK files - -PKtype translates a packed font (PK) bitmap file (as output by GFtoPK, -for example) to a plain text file that humans can read. It also serves -as a PK-validating program, i.e., if PKtype can read a file, it's -correct. Synopsis: - -@example -pktype @var{pkname}.@var{dpi}[pk] -@end example - -The font @var{pkname} is searched for in the usual places (@pxref{Glyph -lookup,,, kpathsea, Kpathsea}). To see all the relevant paths, set the -environment variable @code{KPATHSEA_DEBUG} to @samp{-1} before running -the program. - -The suffix @samp{pk} is supplied if not already present. This suffix is -not an extension; no @samp{.} precedes it: for instance, @file{cmr10.600pk}. - -The translation is written to standard output. - -The only options are @samp{-help} and @samp{-version} -(@pxref{Common options}). - -As an example of the output, here is the (abridged) translation of the -letter `K' in @samp{cmr10}, as rendered at 600@dmn{dpi} with the mode -@samp{ljfour} from @url{modes.mf} (available from -@file{ftp://ftp.tug.org/tex/modes.mf}). - -@smallexample -955: Flag byte = 184 Character = 75 Packet length = 174 - Dynamic packing variable = 11 - TFM width = 815562 dx = 4259840 - Height = 57 Width = 57 X-offset = -3 Y-offset = 56 - [2]23(16)17(8)9(25)11(13)7(27)7(16)7(28)4(18)7(28)2(20)7(27)@dots{} - @dots{} - (14)9(24)12(5)[2]23(13)21 -@end smallexample - -@noindent -Explanation: - -@table @samp -@item 955 -@cindex byte position -The byte position in the file where this character starts. - -@item Flag byte -@itemx Dynamic packing variable -@cindex flag byte -@cindex dynamic packing variable -Related to the packing for this character; see the source code. - -@item Character -@cindex character codes, in PKtype output -The character code, in decimal. - -@item Packet length -@cindex packet length -The total length of this character definition, in bytes. - -@item TFM width -@cindex TFM width of characters -@cindex device-independent width -@cindex width, device-independent -The device-independent (TFM) width of this character. It is 2^24 -times the ratio of the true width to the font's design size. - -@item dx -@cindex horizontal escapement -@cindex escapement, horizontal -@cindex scaled pixels -@cindex dx @r{horizontal escapement} -The device-dependent width, in @dfn{scaled pixels}, i.e., units of -horizontal pixels times 2^16. - -@item Height -@itemx Width -@cindex height, in pixels -@cindex pixel height -@cindex pixel width -@cindex width, in pixels -The bitmap height and width, in pixels. - -@item X-offset -@itemx Y-offset -@cindex x offset -@cindex y offset -@cindex origin -@cindex reference pixel -@cindex side bearings -@cindex left side bearing -@cindex right side bearing -Horizontal and vertical offset from the upper left pixel to the -reference (origin) pixel for this character, in pixels (right and down -are positive). The @dfn{reference pixel} is the pixel that occupies the -unit square in Metafont; the Metafont reference point is the lower left -hand corner of this pixel. Put another way, the x-offset is the negative -of the left side bearing; the right side bearing is the horizontal -escapement minus the bitmap width plus the x-offset. - -@item [2]23(16)@dots{} -@cindex run length encoded bitmaps -@cindex repeated rows -Finally, run lengths of black pixels alternate with parenthesized run -lengths of white pixels, and brackets indicate a repeated row. -@end table - - -@node gftype invocation -@section GFtype: Plain text transliteration of generic fonts - -@pindex gftype @r{GF validation} -@cindex conversion, GF to plain text -@cindex plain text, converting GF to -@cindex human-readable text, converting GF to -@cindex type programs, GF -@cindex validation, of GF files - -GFtype translates a generic font (GF) bitmap file (as output by -Metafont, for example) to a plain text file that humans can read. It -also serves as a GF-validating program, i.e., if GFtype can read a file, -it's correct. Synopsis: - -@example -gftype [@var{option}]@dots{} @var{gfname}.@var{dpi}[gf] -@end example - -The font @var{gfname} is searched for in the usual places (@pxref{Glyph -lookup,,, kpathsea, Kpathsea}). To see all the relevant paths, set the -environment variable @code{KPATHSEA_DEBUG} to @samp{-1} before running -the program. - -The suffix @samp{gf} is supplied if not already present. This suffix is -not an extension; no @samp{.} precedes it: for instance, @file{cmr10.600gf}. - -The translation is written to standard output. - -The program accepts the following options, as well as the standard -@samp{-help} and @samp{-version} (@pxref{Common options}): -@table @samp -@item -images -@opindex -images -Show the characters' bitmaps using asterisks and spaces. - -@item -mnemonics -@opindex -mnemonics -Translate all commands in the GF file. -@end table - -As an example of the output, here is the (abrdiged) translation of the -letter `K' in @samp{cmr10}, as rendered at 600@dmn{dpi} with the mode -@samp{ljfour} from @file{modes.mf} (available from -@url{ftp://ftp.tug.org/tex/modes.mf}), with both @samp{-mnemonics} and -@samp{-images} enabled. - -GFtype outputs the information about a character in two places: a main -definition and a one-line summary at the end. We show both. Here is the -main definition: - -@example -2033: beginning of char 75: 3<=m<=60 0<=n<=56 -(initially n=56) paint (0)24(12)20 -2043: newrow 0 (n=55) paint 24(12)20 -2047: newrow 0 (n=54) paint 24(12)20 -2051: newrow 0 (n=53) paint 24(12)20 -2055: newrow 7 (n=52) paint 10(21)13 -2059: newrow 8 (n=51) paint 8(23)9 -@dots{} -2249: newrow 8 (n=5) paint 8(23)11 -2253: newrow 7 (n=4) paint 10(22)12 -2257: newrow 0 (n=3) paint 24(11)22 -2261: newrow 0 (n=2) paint 24(11)22 -2265: newrow 0 (n=1) paint 24(11)22 -2269: newrow 0 (n=0) paint 24(11)22 -2273: eoc -@group -.<--This pixel's lower left corner is at (3,57) in METAFONT coordinates -************************ ******************** -************************ ******************** -************************ ******************** -************************ ******************** - ********** ************* - ******** ********* -@dots{} - ******** *********** - ********** ************ -************************ ********************** -************************ ********************** -************************ ********************** -************************ ********************** -.<--This pixel's upper left corner is at (3,0) in METAFONT coordinates -@end group -@end example - -@noindent -Explanation: - -@table @samp -@item 2033 -@itemx 2043 -@itemx @dots{} -@cindex byte position -The byte position in the file where each GF command starts. - -@item beginning of char 75 -@cindex character codes, in GFtype output -The character code, in decimal. - -@item 3<=m<=60 0<=n<=56 -@cindex left side bearing -@cindex right side bearing -@cindex side bearings -The character's bitmap lies between 3 and 60 (inclusive) horizontally, -and between 0 and 56 (inclusive) vertically. (@math{m} is a column -position and @math{n} is a row position.) Thus, 3 is the left side -bearing. The right side bearing is the horizontal escapement (given -below) minus the maximum @math{m}. - -@item (initially n=56) paint (0)24(12)20 -@cindex run length encoded bitmaps -The first row of pixels: 0 white pixels, 24 black pixels, 12 white -pixels, etc. - -@item newrow 0 (n=55) paint 24(12)20 -@findex newrow @r{GF command} -The second row of pixels, with zero leading white pixels on the row. - -@item eoc -@findex eoc @r{GF command} -The end of the main character definition. - -@end table - -Here is the GF postamble information that GFtype outputs at the end: - -@example -Character 75: dx 4259840 (65), width 815562 (64.57289), loc 2033 -@end example - -Explanation: - -@table @samp -@item dx -@cindex horizontal escapement -@cindex escapement, horizontal -@cindex vertical escapement -@cindex escapement, vertical -@cindex scaled pixels -@cindex dx @r{horizontal escapement} -@cindex dy @r{vertical escapement} -The device-dependent width, in @dfn{scaled pixels}, i.e., units of -horizontal pixels times 2^16. The @samp{(65)} is simply the same number -rounded. If the vertical escapement is nonzero, it would appear here as -a @samp{dy} value. - -@item width -@cindex TFM width of characters -@cindex device-independent width -@cindex width, device-independent -The device-independent (TFM) width of this character. It is 2^24 -times the ratio of the true width to the font's design size. The -@samp{64.57289} is the same number converted to pixels. - -@item loc -The byte position in the file where this character starts. - -@end table - - -@node tftopl invocation -@section TFtoPL: @TeX{} font metric to property list conversion - -@pindex tftopl -@cindex conversion, TFM to property list -@cindex validation, of TFM files -@cindex property list, converting TFM to -@cindex human-readable text, converting TFM to -@cindex plain text, converting TFM to - -TFtoPL translates a @TeX{} font metric (TFM, @pxref{Metric -files,,,dvips,Dvips}) file (as output by Metafont, for example) to -@dfn{property list format} (a list of parenthesized items describing the -font) that humans can edit or read. This program is mostly used by -people debugging @TeX{} implementations, writing font utilities, etc. -Synopsis: - -@example -tftopl [@var{option}]@dots{} @var{tfmname}[.tfm] [@var{plfile}[.pl]] -@end example - -The font @var{tfmname} (extended with @samp{.tfm} if necessary) is -searched for in the usual places (@pxref{Supported file formats,,, -kpathsea, Kpathsea}). To see all the relevant paths, set the -environment variable @code{KPATHSEA_DEBUG} to @samp{-1} before running -the program. - -If @var{plfile} (which is extended with @samp{.pl} if necessary) is not -specified, the property list file is written to standard output. The -property list file can be converted back to TFM format by the companion -program TFtoPL (see the next section). - -The program accepts the following option, as well as the standard -@samp{-verbose}, @samp{-help} and @samp{-version} (@pxref{Common -options}): -@table @samp -@item -charcode-format=@var{type} -@opindex -charcode-format=@var{type} -Output character codes in the PL file according to @var{type}: either -@samp{octal} or @samp{ascii}. Default is @samp{ascii} for letters and -digits, octal for all other characters. Exception: if the font's coding -scheme starts with @samp{TeX math sy} or @samp{TeX math ex}, all -character codes are output in octal. - -In @samp{ascii} format, character codes that correspond to graphic -characters, except for left and right parentheses, are output as a -@samp{C} followed by the single character: @samp{C K}, for example. In -octal format, character codes are output as the letter @samp{O} followed -by octal digits, as in @samp{O 113} for @samp{K}. - -@samp{octal} format is useful for symbol and other non-alphabetic fonts, -where using ASCII characters for the character codes is merely -confusing. -@end table - -@cindex property list format -As an example of the output, here is the (abridged) property list -translation of @file{cmr10.tfm}: - -@example -(FAMILY CMR) -(FACE O 352) -(CODINGSCHEME TEX TEXT) -(DESIGNSIZE R 10.0) -(COMMENT DESIGNSIZE IS IN POINTS) -(COMMENT OTHER SIZES ARE MULTIPLES OF DESIGNSIZE) -(CHECKSUM O 11374260171) -(FONTDIMEN - (SLANT R 0.0) - (SPACE R 0.333334) - (STRETCH R 0.166667) - (SHRINK R 0.111112) - (XHEIGHT R 0.430555) - (QUAD R 1.000003) - (EXTRASPACE R 0.111112) - ) -(LIGTABLE - @dots{} - (LABEL C f) - (LIG C i O 14) - (LIG C f O 13) - (LIG C l O 15) - (KRN O 47 R 0.077779) - (KRN O 77 R 0.077779) - (KRN O 41 R 0.077779) - (KRN O 51 R 0.077779) - (KRN O 135 R 0.077779) - (STOP) - @dots{} - ) -@dots{} -(CHARACTER C f - (CHARWD R 0.305557) - (CHARHT R 0.694445) - (CHARIC R 0.077779) - (COMMENT - (LIG C i O 14) - (LIG C f O 13) - (LIG C l O 15) - (KRN O 47 R 0.077779) - (KRN O 77 R 0.077779) - @dots{} - ) - ) -@dots{} -@end example - -As you can see, the general format is a list of parenthesized -@dfn{properties}, nested where necessary. - -@itemize @bullet -@item -@findex FAMILY @r{property} -@findex FACE @r{property} -@findex headerbyte @r{information} -The first few items (@code{FAMILY}, @code{FACE}, and so on) are -the so-called @dfn{headerbyte} information from Metafont, giving general -information about the font. - -@item -@findex FAMILY @r{property} -@findex \fontdimen -The @code{FONTDIMEN} property defines the @TeX{} @code{\fontdimen} -values. - -@item -@findex LIGTABLE @r{property} -@findex LABEL @r{property} -@findex LIG @r{property} -@findex KRN @r{property} -@cindex ligature table, in TFM files -@cindex kerning table, in TFM files -@cindex design-size units -The @code{LIGTABLE} property defines the ligature and kerning table. -@code{LIG} properties define ligatures: in the example above, an -@samp{f} (in the @samp{LABEL}) followed by an @samp{i} is a ligature, -i.e., a typesetting program like @TeX{} replaces those two consecutive -characters by the character at position octal '014 in the current -font---presumably the `fi' ligature. @code{KRN} properties define -kerns: if an @samp{f} is followed by character octal '047 (an -apostrophe), @TeX{} inserts a small amount of space between them: -0.077779 times the design size the font was loaded at (about -three-quarters of a printer's point by default in this case, or .001 -inches). - -@item -@findex CHARACTER @r{property} -@findex CHARWD @r{property} -@findex CHARHT @r{property} -@findex CHARDP @r{property} -@findex CHARIC @r{property} -The @code{CHARACTER} property defines the dimensions of a character: its -width, height, depth, and italic correction, also in design-size units, -as explained in the previous item. For our example `f', the depth is -zero, so that property is omitted. TFtoPL also inserts any kerns and -ligatures for this character as a comment. - -@end itemize - - -@node pltotf invocation -@section PLtoTF: Property list to @TeX{} font metric conversion - -@pindex pltotf -@cindex conversion, property list to TFM -@cindex TFM files, converting property lists to -@cindex machine-readable, converting property lists to - -PLtoTF translates a property list file (as output by TFtoPL, for -example) to @TeX{} font metric (TFM, @pxref{Metric files,,,dvips,Dvips}) -format. It's much easier for both programs and humans to create the -(plain text) property list files and let PLtoTF take care of creating -the binary TFM equivalent than to output TFM files directly. Synopsis: - -@example -pltotf [@var{option}]@dots{} @var{plfile}[.pl] [@var{tfmfile}[.tfm]] -@end example - -If @var{tfmfile} (extended with @samp{.tfm} if necessary) is -not specified, the TFM file is written to the basename of -@samp{@var{plfile}.tfm}, e.g., @samp{pltotf /wherever/cmr10.pl} creates -@file{./cmr10.tfm}. (Since TFM files are binary, writing to standard -output by default is undesirable.) - -The only options are @samp{-verbose}, @samp{-help}, and -@samp{-version} (@pxref{Common options}). - -For an example of property list format, see the previous section. - - -@node vftovp invocation -@section VFtoVP: Virtual font to virtual property lists - -@pindex vftovp -@cindex conversion, VF to VPL -@cindex validation, of VF files -@cindex property list, converting VF to virtual -@cindex human-readable text, converting VF to -@cindex plain text, converting VF to - -VFtoVP translates a virtual font metric (VF, @pxref{Virtual -fonts,,,dvips,Dvips}) file and its accompanying @TeX{} font metric (TFM, -@pxref{Metric files,,,dvips,Dvips}) file (as output by VPtoVF, for -example) to @dfn{virtual property list format} (a list of parenthesized -items describing the virtual font) that humans can edit or read. This -program is mostly used by people debugging virtual font utilities. -Synopsis: - -@example -vftovp [@var{option}]@dots{} @var{vfname}[.vf] [@var{tfmname}[.tfm] @c -[@var{vplfile}[.vpl]]] -@end example - -The fonts @var{vfname} and @var{tfmname} (extended with @samp{.vf} and -@samp{.tfm} if necessary) are searched for in the usual places -(@pxref{Supported file formats,,, kpathsea, Kpathsea}). To see all the -relevant paths, set the environment variable @code{KPATHSEA_DEBUG} to -@samp{-1} before running the program. If @var{tfmname} is not -specified, @var{vfname} (without a trailing @samp{.vf}) is used. - -If @var{vplfile} (extended with @samp{.vpl} if necessary) is -not specified, the property list file is written to standard output. -The property list file can be converted back to VF and TFM format by the -companion program VFtoVP (see the next section). - -The program accepts the following option, as well as the standard -@samp{-verbose}, @samp{-help} and @samp{-version} (@pxref{Common -options}): -@table @samp -@item -charcode-format=@var{type} -@opindex -charcode-format=@var{type} -Output character codes in the PL file according to @var{type}: either -@samp{octal} or @samp{ascii}. Default is @samp{ascii} for letters and -digits, octal for all other characters. Exception: if the font's coding -scheme starts with @samp{TeX math sy} or @samp{TeX math ex}, all -character codes are output in octal. - -In @samp{ascii} format, character codes that correspond to graphic -characters, except for left and right parentheses, are output as a -@samp{C} followed by the single character: @samp{C K}, for example. In -octal format, character codes are output as the letter @samp{O} followed -by octal digits, as in @samp{O 113} for @samp{K}. - -@samp{octal} format is useful for symbol and other non-alphabetic fonts, -where using ASCII characters for the character codes is merely -confusing. -@end table - - -@node vptovf invocation -@section VPtoVF: Virtual property lists to virtual font - -@pindex vptovf -@cindex conversion, property list to VF -@cindex VF files, converting property lists to -@cindex machine-readable, converting property lists to - -VPtoVF translates a virtual property list file (as output by VFtoVP, for -example) to virtual font (VF, @pxref{Virtual fonts,,,dvips,Dvips}) and -@TeX{} font metric (TFM, @pxref{Metric files,,,dvips,Dvips}) files. -It's much easier for both programs and humans to create the (plain text) -property list files and let VPtoVF take care of creating the binary VF -and TFM equivalents than to output them directly. Synopsis: - -@example -vptovf [@var{option}]@dots{} @var{vplfile}[.vpl] [@var{vffile}[.vf] @c -[@var{tfmfile}[.tfm]]] -@end example - -If @var{vffile} (extended with @samp{.vf} if necessary) is not -specified, the VF output is written to the basename of -@samp{@var{vplfile}.vf}; similarly for @var{tfmfile}. For example, -@samp{vptovf /wherever/ptmr.vpl} creates @file{./ptmr.vf} and -@file{./ptmr.tfm}. - -The only options are @samp{-verbose}, @samp{-help}, and @samp{-version} -(@pxref{Common options}). - - -@node Font utilities available elsewhere -@section Font utilities available elsewhere - -@cindex font utilities, non-Web2c - -The Web2c complement of font utilities merely implements a few basic -conversions. Many other more sophisticated font utilities exist; most -are in @file{@var{CTAN:}/fonts/utilities} (for CTAN info, -@pxref{unixtex.ftp,,, kpathsea, Kpathsea}). Here are some of the most -commonly-requested items: - -@itemize @bullet -@item -@cindex AFM to TFM conversion -@pindex afm2tfm -@pindex afmtopl -AFM (Adobe font metric) to TFM conversion: @pxref{Invoking afm2tfm,,, -dvips, Dvips}, and @file{@var{CTAN:}/fonts/utilities/afmtopl}. - -@item -@cindex X bitmap fonts -@cindex BDF and GF conversion -BDF (the X bitmap format) conversion: -@url{ftp://ftp.tug.org/tex/bdf.tar.gz}. - -@item -@pindex metatype1 -@cindex Latin Modern -Creating fonts using MetaPost: MetaType1. -@url{ftp://bop.eps.gda.pl/pub/metatype1}. This is used to create -the excellent Latin Modern font family (@file{@var{CTAN:}/fonts/lm}), -which extends Computer Modern to a vast repertoire of scripts. - -@item -@cindex editing of bitmap fonts -@pindex xbfe@r{, bitmap font editor} -@pindex xfed@r{, bitmap font editor} -@pindex xfedor@r{, bitmap font editor} -@pindex gftopxl -@pindex chtopx -@pindex pxtoch -Editing of bitmap fonts: Xbfe from the GNU font utilities mentioned -below; the X BDF-editing programs available from -@url{ftp://ftp.x.org/R5contrib/xfed.tar.Z} and -@url{ftp://ftp.x.org/R5contrib/xfedor.tar.Z}; and finally, if your -fonts have only 128 characters, you can use the old @code{gftopxl}, -@code{pxtoch}, and @code{chtopx} programs from -@url{ftp://ftp.tug.org/tex/web}. - -@item -@pindex fontforge -@pindex pfaedit -Editing of outline fonts: FontForge, @url{fontforge.sourceforge.net}. -This is a very elaborate program with support for many outline formats -(Type@tie{}1, OpenType, TrueType, @dots{}), and many advanced font -editing features. - -@item -@cindex PK bitmaps from PostScript -@cindex PostScript to PK bitmaps -@pindex gsftopk -@pindex ps2pk -PK bitmaps from PostScript outline fonts: gsftopk from the @samp{xdvi} -distribution. Alternatively, @code{ps2pk}, from -@file{@var{CTAN:}/fonts/utilities/ps2pk}. - -@item -@cindex Type 1 conversion -@cindex PFA and PFB conversion -@cindex PostScript Type 1 font conversion -PostScript Type 1 font format conversion (i.e., between PFA and PFB -formats): @url{https://www.lcdf.org/type}. - -@item -@pindex autotrace -@pindex potrace -Tracing bitmaps to fitted outlines: Autotrace -(@url{http://autotrace.sourceforge.net}), Potrace -(@url{http://potrace.sourceforge.net}). For Metafont fonts, either of -the two programs @code{mftrace} -(@url{http://www.xs4all.nl/~hanwen/mftrace}) or @code{textrace} -(@url{http://textrace.sourceforge.net}) make the job easier. - -@item -@cindex virtual font creation -@pindex fontinst@r{, for creating virtual fonts} -Virtual font creation: @url{https://ctan.org/pkg/fontinst}. -@end itemize - - -@node Legalisms -@appendix Legalisms - -@cindex legalisms -@cindex copyright notices -@cindex permissions, legal - -In general, each file has its own copyright notice stating the copying -permissions for that file. Following is a summary. - -The Stanford @TeX{} programs and Web2c system itself are in the public -domain (@url{https://tug.org/texlive/copying.html}). The sources may -be copied verbatim, or used as the starting point of new software -under different names; however, per the wishes of the authors, they -should be modified only through a @file{.ch} file, but this is in the -nature of a development request rather than a legal requirement. - -ML@TeX{}, pdf@TeX{}, Lua@TeX{}, Xe@TeX{}, and all the other derived -engines have used various license terms for their additions to the -base code, often the GPL (see @url{https://www.gnu.org/licenses/#GPL} -or (for example) the file @file{web2c/pdftexdir/COPYINGv2}. They also -mostly make use of additional libraries with their own (compatible) -terms. Please see each program's sources. - -The Kpathsea library is covered by the GNU Lesser General Public -License (@pxref{Introduction,,, kpathsea, Kpathsea}). Therefore, the -@emph{binaries} resulting from a standard Web2c compilation are also -covered by the LGPL; so if you (re)distribute the binaries, you must -also (offer to) distribute the complete source that went into those -binaries. See @url{https://gnu.org/licenses/#LGPL} or the file -@file{kpathsea/COPYING.LESSERv2}. - -@node References -@appendix References - -@cindex references -@cindex bibliography - -@enumerate -@item -Kpathsea: @xref{Top, Introduction,, kpathsea, Kpathsea}. - -@item -Dvips and Afm2tfm: @xref{Top, Introduction,, dvips, Dvips}. - -@item -The @TeX{} Users Group: @url{https://tug.org}. For an introduction -to the @TeX{} system, see @url{https://tug.org/begin.html}. - -@item -TUGboat, the principal journal for the @TeX{} world: -@url{https://tug.org/TUGboat}. - -@item -@TeX{} and computer typesetting in general:@* -@url{ftp://ftp.math.utah.edu/pub/tex/bib/texbook1.bib}. - -@item -For a bibliography of formal articles and technical reports on the -@TeX{} project, see the books @cite{@TeX{}: The Program} or -@cite{Metafont: The Program} cited below. - -@include ref.txi - -@end enumerate - - -@node Index -@unnumbered Index - -@printindex cp - -@bye |