| 1 |
This is web2c.info, produced by makeinfo version 7.2 from web2c.texi. |
| 2 |
|
| 3 |
This file documents the installation and use of the programs in Web2c, |
| 4 |
an implementation of Donald Knuth's TeX system. |
| 5 |
|
| 6 |
Copyright © 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, |
| 7 |
2005, 2007, 2008, 2009, 2010-2026 Karl Berry & Olaf Weber. |
| 8 |
|
| 9 |
Permission is granted to make and distribute verbatim copies of this |
| 10 |
manual provided the copyright notice and this permission notice are |
| 11 |
preserved on all copies. |
| 12 |
|
| 13 |
Permission is granted to copy and distribute modified versions of |
| 14 |
this manual under the conditions for verbatim copying, provided that the |
| 15 |
entire resulting derived work is distributed under the terms of a |
| 16 |
permission notice identical to this one. |
| 17 |
|
| 18 |
Permission is granted to copy and distribute translations of this |
| 19 |
manual into another language, under the above conditions for modified |
| 20 |
versions, except that this permission notice may be stated in a |
| 21 |
translation |
| 22 |
INFO-DIR-SECTION TeX |
| 23 |
START-INFO-DIR-ENTRY |
| 24 |
* Web2c: (web2c). TeX, Metafont, and companion programs. |
| 25 |
END-INFO-DIR-ENTRY |
| 26 |
|
| 27 |
INFO-DIR-SECTION Individual utilities |
| 28 |
START-INFO-DIR-ENTRY |
| 29 |
* bibtex: (web2c)bibtex invocation. Maintaining bibliographies. |
| 30 |
* dvicopy: (web2c)dvicopy invocation. Virtual font expansion |
| 31 |
* dvitomp: (web2c)dvitomp invocation. DVI to MPX (MetaPost pictures). |
| 32 |
* dvitype: (web2c)dvitype invocation. DVI to human-readable text. |
| 33 |
* gftodvi: (web2c)gftodvi invocation. Generic font proofsheets. |
| 34 |
* gftopk: (web2c)gftopk invocation. Generic to packed fonts. |
| 35 |
* gftype: (web2c)gftype invocation. GF to human-readable text. |
| 36 |
* mf: (web2c)mf invocation. Creating typeface families. |
| 37 |
* mft: (web2c)mft invocation. Prettyprinting Metafont source. |
| 38 |
* mltex: (web2c)MLTeX. Multi-lingual TeX. |
| 39 |
* mpost: (web2c)mpost invocation. Generating PostScript. |
| 40 |
* patgen: (web2c)patgen invocation. Creating hyphenation patterns. |
| 41 |
* pktogf: (web2c)pktogf invocation. Packed to generic fonts. |
| 42 |
* pktype: (web2c)pktype invocation. PK to human-readable text. |
| 43 |
* pltotf: (web2c)pltotf invocation. Property list to TFM. |
| 44 |
* pooltype: (web2c)pooltype invocation. Display WEB pool files. |
| 45 |
* tangle: (web2c)tangle invocation. WEB to Pascal. |
| 46 |
* tex: (web2c)tex invocation. Typesetting. |
| 47 |
* tftopl: (web2c)tftopl invocation. TFM -> property list. |
| 48 |
* vftovp: (web2c)vftovp invocation. Virtual font -> virtual pl. |
| 49 |
* vptovf: (web2c)vptovf invocation. Virtual pl -> virtual font. |
| 50 |
* weave: (web2c)weave invocation. WEB to TeX. |
| 51 |
END-INFO-DIR-ENTRY |
| 52 |
|
| 53 |
|
| 54 |
File: web2c.info, Node: Top, Next: Introduction, Up: (dir) |
| 55 |
|
| 56 |
Web2c |
| 57 |
***** |
| 58 |
|
| 59 |
This document describes how to install and use the programs in the Web2c |
| 60 |
implementation of the TeX system, especially for Unix systems. It |
| 61 |
corresponds to Web2c version 2026, released in January 2026. |
| 62 |
|
| 63 |
* Menu: |
| 64 |
|
| 65 |
* Introduction:: A brief introduction. |
| 66 |
* Installation:: How to compile and install Web2c. |
| 67 |
* Commonalities:: Option syntax, standard options, memory dumps. |
| 68 |
* Three programs:: TeX, Metafont, MetaPost have much in common. |
| 69 |
* TeX:: Typesetting. |
| 70 |
* Metafont:: Typeface design. |
| 71 |
* MetaPost:: Technical illustrations. |
| 72 |
* BibTeX:: Reusable bibliographies. |
| 73 |
* WEB:: Literate programming. |
| 74 |
* DVI utilities:: DVI expansion. |
| 75 |
* Font utilities:: Font format conversion. |
| 76 |
* Legalisms:: Blah blah blah. |
| 77 |
* References:: Books and such. |
| 78 |
* Index:: General index. |
| 79 |
|
| 80 |
|
| 81 |
File: web2c.info, Node: Introduction, Next: Installation, Prev: Top, Up: Top |
| 82 |
|
| 83 |
1 Introduction |
| 84 |
************** |
| 85 |
|
| 86 |
This manual corresponds to version 2026 of Web2c, released in January |
| 87 |
2026. |
| 88 |
|
| 89 |
“Web2c” (also spelled Web2C) is the name of a TeX implementation, |
| 90 |
originally for Unix, but now also running under Windows and other |
| 91 |
operating systems. By “TeX implementation”, we mean all of the standard |
| 92 |
programs developed by the Stanford TeX project led by Donald E. Knuth: |
| 93 |
Metafont, DVItype, GFtoDVI, BibTeX, Tangle, etc., as well as TeX itself. |
| 94 |
Other programs are also included: DVIcopy, written by Peter |
| 95 |
Breitenlohner, MetaPost and its utilities (derived from Metafont), by |
| 96 |
John Hobby, and many more. |
| 97 |
|
| 98 |
General strategy: Web2c works, as its name implies, by translating |
| 99 |
the WEB source in which TeX is written into C source code. Its output |
| 100 |
is not self-contained, however; it makes extensive use of many macros |
| 101 |
and functions in a library (the ‘web2c/lib’ directory in the sources). |
| 102 |
Therefore, it will not work without change on an arbitrary WEB program. |
| 103 |
|
| 104 |
Availability: All of Web2c is freely available--"free" both in the |
| 105 |
sense of no cost (free ice cream) and of having the source code to |
| 106 |
modify and/or redistribute (free speech). *Note |
| 107 |
(kpathsea)unixtex.ftp::, for the practical details of how to obtain |
| 108 |
Web2c. |
| 109 |
|
| 110 |
Different parts of the Web2c distribution have different licensing |
| 111 |
terms, however, reflecting the different circumstances of their |
| 112 |
creation; consult each source file for exact details. The main |
| 113 |
practical implication for redistributors of Web2c is that most of the |
| 114 |
executables are covered by the GNU General Public License or GNU Lesser |
| 115 |
General Public License, and therefore anyone who gets a binary |
| 116 |
distribution must also be able to get the sources, as explained by the |
| 117 |
terms of the GPL (<https://gnu.org/licenses/>). The GPL covers the |
| 118 |
Web2c executables, including ‘tex’, because the Free Software Foundation |
| 119 |
sponsored the initial development of the Kpathsea library that Web2c |
| 120 |
uses. The basic source files from Stanford, however, have their own |
| 121 |
copyright terms or are in the public domain, and are not covered by the |
| 122 |
GPL. |
| 123 |
|
| 124 |
History: Tomas Rokicki originated the TeX-to-C system in 1987, |
| 125 |
working from the first change files for TeX under Unix, which were done |
| 126 |
primarily by Howard Trickey and Pavel Curtis. Tim Morgan then took over |
| 127 |
development and maintenance for a number of years; the name changed to |
| 128 |
Web-to-C somewhere in there. In 1990, Karl Berry became the maintainer. |
| 129 |
He made many changes to the original sources, and started using the |
| 130 |
shorter name Web2c. In 1997, Olaf Weber took over, and then in 2006, |
| 131 |
Karl started taking care of it again. No significant development or |
| 132 |
changes have been needed for many years, though dozens of other people |
| 133 |
have contributed in many ways; their names are listed in the ‘ChangeLog’ |
| 134 |
files. |
| 135 |
|
| 136 |
Originally, Web2c was distributed as its own package, alongside the |
| 137 |
original web programs from Stanford and other components. It was also |
| 138 |
the basis for the teTeX distribution (now discontinued). Around 2004, |
| 139 |
the packaging focus shifted entirely to the TeX Live distribution |
| 140 |
(<https://tug.org/texlive/>), though the same Web2c is at the heart of |
| 141 |
the release. |
| 142 |
|
| 143 |
Other acknowledgements by Karl: The University of Massachusetts at |
| 144 |
Boston (particularly Rick Martin and Bob Morris) provided computers and |
| 145 |
ftp access to me for many years. Richard Stallman at the Free Software |
| 146 |
Foundation employed me while I wrote the original path searching library |
| 147 |
(for the GNU font utilities). (rms also gave us Emacs, GDB, and GCC, |
| 148 |
without which I cannot imagine developing Web2c.) And, of course, TeX |
| 149 |
would not exist in the first place without Donald E. Knuth. |
| 150 |
|
| 151 |
Further reading: *Note References::. |
| 152 |
|
| 153 |
|
| 154 |
File: web2c.info, Node: Installation, Next: Commonalities, Prev: Introduction, Up: Top |
| 155 |
|
| 156 |
2 Installation |
| 157 |
************** |
| 158 |
|
| 159 |
(A copy of this chapter is in the distribution file ‘web2c/INSTALL’.) |
| 160 |
|
| 161 |
Installing Web2c is mostly the same as installing any other |
| 162 |
Kpathsea-using program. Therefore, for the basic steps involved, see |
| 163 |
*note (kpathsea)Installation::. (A copy is in the file |
| 164 |
‘kpathsea/INSTALL’.) |
| 165 |
|
| 166 |
One peculiarity to Web2c is that the source distribution comes in two |
| 167 |
files: ‘web.tar.gz’ and ‘web2c.tar.gz’. You must retrieve and unpack |
| 168 |
them both. (We have two because the former archive contains the very |
| 169 |
large and seldom-changing original WEB source files.) *Note |
| 170 |
(kpathsea)unixtex.ftp::. |
| 171 |
|
| 172 |
Another peculiarity is the MetaPost program. Although it has been |
| 173 |
installed previously as ‘mp’, as of Web2c 7.0 the installed name is now |
| 174 |
‘mpost’, to avoid conflict with the ‘mp’ program that does |
| 175 |
prettyprinting. This approach was recommended by the MetaPost author, |
| 176 |
John Hobby. If you as the TeX administrator wish to make it available |
| 177 |
under its shorter name as well, you will have to set up a link or some |
| 178 |
such yourself. And of course individual users can do the same. |
| 179 |
|
| 180 |
For solutions to common installation problems and information on how |
| 181 |
to report a bug, see the file ‘kpathsea/BUGS’ (*note (kpathsea)Bugs::). |
| 182 |
See also the Web2c home page, <http://www.tug.org/web2c>. |
| 183 |
|
| 184 |
Points worth repeating: |
| 185 |
|
| 186 |
• Before starting the standard compilation and installation you must |
| 187 |
install the basic fonts, macros, and other library files. *Note |
| 188 |
(kpathsea)Installation::. |
| 189 |
|
| 190 |
• If you do not wish to use the standard file locations, see *note |
| 191 |
(kpathsea)Changing search paths::. |
| 192 |
|
| 193 |
• Some Web2c features are enabled or disabled at ‘configure’ time, as |
| 194 |
described in the first section below. |
| 195 |
|
| 196 |
* Menu: |
| 197 |
|
| 198 |
* configure options:: Especially -with and -enable. |
| 199 |
* Compile-time options:: Unusual -D's. |
| 200 |
* Additional targets:: Breaking down the task. |
| 201 |
* Triptrap:: Running the torture tests. |
| 202 |
|
| 203 |
|
| 204 |
File: web2c.info, Node: configure options, Next: Compile-time options, Up: Installation |
| 205 |
|
| 206 |
2.1 ‘configure’ options |
| 207 |
======================= |
| 208 |
|
| 209 |
This section gives pointers to descriptions of the ‘--with’ and |
| 210 |
‘--enable’ ‘configure’ arguments that Web2c accepts. Some are specific |
| 211 |
to Web2c, others are generic to all Kpathsea-using programs. |
| 212 |
|
| 213 |
For a list of all the options ‘configure’ accepts, run ‘configure |
| 214 |
--help’. The generic options are listed first, and the package-specific |
| 215 |
options come last. |
| 216 |
|
| 217 |
For a description of the generic options (which mainly allow you to |
| 218 |
specify installation directories) and basic ‘configure’ usage, see *note |
| 219 |
Running ‘configure’ scripts: (autoconf)Invoking configure, a copy is in |
| 220 |
the file ‘kpathsea/CONFIGURE’. |
| 221 |
|
| 222 |
‘--disable-dump-share’ |
| 223 |
Do not make fmt/base/mem files sharable across different endian |
| 224 |
architectures. *Note Hardware and memory dumps::. |
| 225 |
|
| 226 |
‘--without-maketexmf-default’ |
| 227 |
‘--without-maketexpk-default’ |
| 228 |
‘--without-maketextfm-default’ |
| 229 |
‘--with-maketextex-default’ |
| 230 |
Enable or disable the dynamic generation programs. *Note |
| 231 |
(kpathsea)mktex configuration::. The defaults are the inverse of |
| 232 |
the options, i.e., everything is enabled except ‘mktextex’. |
| 233 |
|
| 234 |
‘--enable-shared’ |
| 235 |
Build Kpathsea as a shared library. *Note (kpathsea)Shared |
| 236 |
library::. |
| 237 |
|
| 238 |
‘--with-editor=CMD’ |
| 239 |
Change the default editor invoked by the ‘e’ interactive command. |
| 240 |
*Note Editor invocation::. |
| 241 |
|
| 242 |
‘--with-epsfwin’ |
| 243 |
‘--with-hp2627win’ |
| 244 |
‘--with-mftalkwin’ |
| 245 |
‘--with-nextwin’ |
| 246 |
‘--with-regiswin’ |
| 247 |
‘--with-suntoolswin’ |
| 248 |
‘--with-tektronixwin’ |
| 249 |
‘--with-unitermwin’ |
| 250 |
‘--with-x’ |
| 251 |
‘--with-x-toolkit=KIT’ |
| 252 |
‘--with-x11win’ |
| 253 |
‘--with-x11’ |
| 254 |
Define Metafont graphics support; by default, no graphics support |
| 255 |
is enabled. *Note Online Metafont graphics::. |
| 256 |
|
| 257 |
‘--x-includes=DIR’ |
| 258 |
‘--x-libraries=DIR’ |
| 259 |
Define the locations of the X11 include files and libraries; by |
| 260 |
default, ‘configure’ does its best to guess). *Note |
| 261 |
(autoconf)Optional Features::. A copy is in ‘kpathsea/CONFIGURE’. |
| 262 |
|
| 263 |
|
| 264 |
File: web2c.info, Node: Compile-time options, Next: Additional targets, Prev: configure options, Up: Installation |
| 265 |
|
| 266 |
2.2 Compile-time options |
| 267 |
======================== |
| 268 |
|
| 269 |
In addition to the ‘configure’ options listed in the previous section, |
| 270 |
there are a few things that can be affected at compile-time with C |
| 271 |
definitions, rather than with ‘configure’. Using any of these is |
| 272 |
unusual. |
| 273 |
|
| 274 |
To specify extra compiler flags (‘-DNAME’ in this case), the simplest |
| 275 |
thing to do is: |
| 276 |
make XCFLAGS="CCOPTIONS" |
| 277 |
You can also set the ‘CFLAGS’ environment variable before running |
| 278 |
‘configure’. *Note (kpathsea)configure environment::. |
| 279 |
|
| 280 |
Anyway, here are the possibilities: |
| 281 |
|
| 282 |
‘-DFIXPT’ |
| 283 |
‘-DNO_MF_ASM’ |
| 284 |
Use the original WEB fixed-point routines for Metafont and MetaPost |
| 285 |
arithmetic calculations regarding fractions. By default, |
| 286 |
assembly-language routines are used on x86 hardware with GNU C |
| 287 |
(unless ‘NO_MF_ASM’ is defined), and floating-point routines are |
| 288 |
used otherwise. |
| 289 |
|
| 290 |
‘-DIPC_DEBUG’ |
| 291 |
Report on various interprocess communication activities. *Note IPC |
| 292 |
and TeX: IPC and TeX. |
| 293 |
|
| 294 |
|
| 295 |
File: web2c.info, Node: Additional targets, Next: Triptrap, Prev: Compile-time options, Up: Installation |
| 296 |
|
| 297 |
2.3 Additional targets |
| 298 |
====================== |
| 299 |
|
| 300 |
Web2c has several Make targets besides the standard ones. You can |
| 301 |
invoke these either in the top level directory of the source |
| 302 |
distribution (the one containing ‘kpathsea/’ and ‘web2c/’), or in the |
| 303 |
‘web2c/’ directory. |
| 304 |
|
| 305 |
‘c-sources’ |
| 306 |
Make only the C files, translated from the Web sources, presumably |
| 307 |
because you want to take them to a non-Unix machine. |
| 308 |
|
| 309 |
‘formats’ |
| 310 |
‘install-formats’ |
| 311 |
Make or install all the memory dumps (*note Memory dumps::). By |
| 312 |
default, the standard plain formats plus ‘latex.fmt’ are made. You |
| 313 |
can add other formats by redefining the ‘fmts’, ‘bases’, and ‘mems’ |
| 314 |
variables. See the top of ‘web2c/Makefile’ for the possibilities. |
| 315 |
|
| 316 |
‘fmts’ |
| 317 |
‘install-fmts’ |
| 318 |
Make or install the TeX ‘.fmt’ files. *Note Initial TeX::. |
| 319 |
|
| 320 |
‘bases’ |
| 321 |
‘install-bases’ |
| 322 |
|
| 323 |
Make or install the Metafont ‘.base’ files. *Note Initial |
| 324 |
Metafont::. |
| 325 |
|
| 326 |
‘mems’ |
| 327 |
‘install-mems’ |
| 328 |
Make or install the MetaPost ‘.mem’ files. *Note Initial |
| 329 |
MetaPost::. |
| 330 |
|
| 331 |
‘triptrap’ |
| 332 |
‘trip’ |
| 333 |
‘trap’ |
| 334 |
‘mptrap’ |
| 335 |
To run the torture tests for TeX, Metafont, and MetaPost |
| 336 |
(respectively). See the next section. |
| 337 |
|
| 338 |
|
| 339 |
File: web2c.info, Node: Triptrap, Prev: Additional targets, Up: Installation |
| 340 |
|
| 341 |
2.4 Trip, trap, and mptrap: Torture tests |
| 342 |
========================================= |
| 343 |
|
| 344 |
To validate your TeX, Metafont, and MetaPost executables, run ‘make |
| 345 |
triptrap’. This runs the trip, trap, and mptrap "torture tests". See |
| 346 |
the files ‘triptrap/tripman.tex’, ‘triptrap/trapman.tex’, and |
| 347 |
‘triptrap/mptrap.readme’ for detailed information and background on the |
| 348 |
tests. |
| 349 |
|
| 350 |
The differences between your executables' behavior and the standard |
| 351 |
values will show up on your terminal. The usual differences (these are |
| 352 |
all acceptable) are: |
| 353 |
|
| 354 |
• string usage and table sizes; |
| 355 |
• glue set ratios; |
| 356 |
• ‘down4’, ‘right4’, and ‘y4’ commands in DVItype output; |
| 357 |
• dates and times. |
| 358 |
|
| 359 |
Any other differences are trouble. The most common culprit in the past |
| 360 |
has been compiler bugs, especially when optimizing. *Note TeX or |
| 361 |
Metafont failing: (kpathsea)TeX or Metafont failing. |
| 362 |
|
| 363 |
The files ‘trip.diffs’, ‘mftrap.diffs’, and ‘mptrap.diffs’ in the |
| 364 |
‘triptrap’ directory show the standard diffs against the original |
| 365 |
output. If you diff your diffs against these files, you should come up |
| 366 |
clean. For example |
| 367 |
make trip >&mytrip.diffs |
| 368 |
diff triptrap/trip.diffs mytrip.diffs |
| 369 |
|
| 370 |
To run the tests separately, use the targets ‘trip’, ‘trap’, and |
| 371 |
‘mptrap’. |
| 372 |
|
| 373 |
To run simple tests for all the programs as well as the torture |
| 374 |
tests, run ‘make check’. You can compare the output to the distributed |
| 375 |
file ‘tests/check.log’ if you like. |
| 376 |
|
| 377 |
|
| 378 |
File: web2c.info, Node: Commonalities, Next: Three programs, Prev: Installation, Up: Top |
| 379 |
|
| 380 |
3 Commonalities |
| 381 |
*************** |
| 382 |
|
| 383 |
Many aspects of the TeX system are the same among more than one program, |
| 384 |
so we describe those pieces together, here. |
| 385 |
|
| 386 |
Another kind of commonality is the extensions to TeX that are |
| 387 |
available across all the engines; *note TeX extensions::. |
| 388 |
|
| 389 |
* Menu: |
| 390 |
|
| 391 |
* Option conventions:: - or -, = or ' ' for values. |
| 392 |
* Common options:: -help -version -verbose, and TeX/MF/MP options. |
| 393 |
* Path searching:: Features of the common path searching library. |
| 394 |
* Output file location:: TEXMFOUTPUT allows output in places other than '.'. |
| 395 |
|
| 396 |
|
| 397 |
File: web2c.info, Node: Option conventions, Next: Common options, Up: Commonalities |
| 398 |
|
| 399 |
3.1 Option conventions |
| 400 |
====================== |
| 401 |
|
| 402 |
To provide a clean and consistent behavior, we chose to have all these |
| 403 |
programs use the GNU function ‘getopt_long_only’ to parse command lines. |
| 404 |
It is used in a restricted mode where all the options have to come |
| 405 |
before the rest of the arguments. |
| 406 |
|
| 407 |
As a result, you can: |
| 408 |
• use ‘-’ or ‘--’ to start an option name; |
| 409 |
|
| 410 |
• use any unambiguous abbreviation for an option name; |
| 411 |
|
| 412 |
• separate option names and values with either ‘=’ or one or more |
| 413 |
spaces; |
| 414 |
|
| 415 |
• use filenames that would otherwise look like options by putting |
| 416 |
them after an option ‘--’. |
| 417 |
|
| 418 |
By convention, non-option arguments, if specified, generally define |
| 419 |
the name of an input file, as documented for each program. |
| 420 |
|
| 421 |
If a particular option with a value is given more than once, it is |
| 422 |
the last value that counts. |
| 423 |
|
| 424 |
For example, the following command line specifies the options ‘foo’, |
| 425 |
‘bar’, and ‘verbose’; gives the value ‘baz’ to the ‘abc’ option, and the |
| 426 |
value ‘xyz’ to the ‘quux’ option; and specifies the filename ‘-myfile-’. |
| 427 |
|
| 428 |
-foo --bar -verb -abc=baz -quux karl --quux xyz -- -myfile- |
| 429 |
|
| 430 |
|
| 431 |
File: web2c.info, Node: Common options, Next: Path searching, Prev: Option conventions, Up: Commonalities |
| 432 |
|
| 433 |
3.2 Common options |
| 434 |
================== |
| 435 |
|
| 436 |
All of these programs accept the standard GNU ‘--help’ and ‘--version’ |
| 437 |
options, and several programs accept ‘--verbose’. Rather than writing |
| 438 |
identical descriptions for every program, they are described here. |
| 439 |
|
| 440 |
‘--help’ |
| 441 |
Print a usage message listing basic usage and all available options |
| 442 |
to standard output, then exit successfully. |
| 443 |
|
| 444 |
‘--verbose’ |
| 445 |
Print progress reports to standard output. |
| 446 |
|
| 447 |
‘--version’ |
| 448 |
Print the version number to standard output, then exit |
| 449 |
successfully. |
| 450 |
|
| 451 |
TeX, Metafont, and MetaPost have a number of additional options in |
| 452 |
common: |
| 453 |
|
| 454 |
‘-cnf-line=STR’ |
| 455 |
Parse STR as if it were a line in the ‘texmf.cnf’ configuration |
| 456 |
file, overriding all other settings. *Note (kpathsea)Path |
| 457 |
searching options::. |
| 458 |
|
| 459 |
‘-file-line-error’ |
| 460 |
‘-no-file-line-error’ |
| 461 |
Change (or do not change) the way error messages are printed. The |
| 462 |
alternate style looks like error messages from many compilers and |
| 463 |
is easier to parse for some editors that invoke TeX. This option |
| 464 |
used to be called ‘-file-line-error-style’. |
| 465 |
|
| 466 |
‘-fmt=DUMPNAME’ |
| 467 |
‘-base=DUMPNAME’ |
| 468 |
‘-mem=DUMPNAME’ |
| 469 |
Use DUMPNAME instead of the program name or a ‘%&’ line to |
| 470 |
determine the name of the memory dump file read (‘fmt’ for TeX, |
| 471 |
‘base’ for Metafont, ‘mem’ for MetaPost). *Note Memory dumps::. |
| 472 |
Also sets the program name to DUMPNAME if no ‘-progname’ option was |
| 473 |
given. |
| 474 |
|
| 475 |
‘-halt-on-error’ |
| 476 |
Stop processing and exit when an error occurs, as opposed to the |
| 477 |
normal process of trying to recover and continue. |
| 478 |
|
| 479 |
‘-ini’ |
| 480 |
Enable the "initial" form of the program (*note Initial and |
| 481 |
virgin::). This is implicitly set if the program name is ‘initex’ |
| 482 |
resp. ‘inimf’. |
| 483 |
|
| 484 |
‘-interaction=STRING’ |
| 485 |
Set the interaction mode from the command line. The STRING must be |
| 486 |
one of ‘batchmode’, ‘nonstopmode’, ‘scrollmode’, or |
| 487 |
‘errorstopmode’. |
| 488 |
|
| 489 |
‘-jobname=STRING’ |
| 490 |
Set the job name to STRING, instead of deriving it from the name of |
| 491 |
the input file. |
| 492 |
|
| 493 |
‘-kpathsea-debug=NUMBER’ |
| 494 |
Set path searching debugging flags according to the bits of NUMBER |
| 495 |
(*note (kpathsea)Debugging::). You can also specify this in |
| 496 |
‘KPATHSEA_DEBUG’ environment variable (for all Web2c programs). |
| 497 |
(The command line value overrides.) The most useful value is ‘-1’, |
| 498 |
to get all available output. |
| 499 |
|
| 500 |
‘-output-directory=DIRNAME’ |
| 501 |
Specify the directory DIRNAME to which output files are written. |
| 502 |
Also look for input files in DIRNAME first, before looking along |
| 503 |
the normal search path. Input files are only looked for as |
| 504 |
specified; no default extension is added. *Note Output file |
| 505 |
location::. |
| 506 |
|
| 507 |
‘-parse-first-line’ |
| 508 |
‘-no-parse-first-line’ |
| 509 |
Check or disable checking whether the first line of the main input |
| 510 |
file starts with ‘%&’, and parse it if it does. This line can be |
| 511 |
used specify the format and/or a TCX file. |
| 512 |
|
| 513 |
‘-progname=STRING’ |
| 514 |
Set program (and memory dump) name to STRING. This may affect the |
| 515 |
search paths and other values used (*note (kpathsea)Config |
| 516 |
files::). Using this option is equivalent to making a link named |
| 517 |
STRING to the binary and then invoking the binary under that name. |
| 518 |
*Note Memory dumps::. |
| 519 |
|
| 520 |
‘-recorder’ |
| 521 |
Enable the filename recorder. This makes the program save a list |
| 522 |
of the opened files into a file with (by default) extension ‘.fls’. |
| 523 |
For Aleph, this option is always on, and the file has extension |
| 524 |
‘.ofl’. |
| 525 |
|
| 526 |
Ordinarily, the ‘.fls’ file is written to the same location as the |
| 527 |
‘.log’ file, for example, respecting ‘-output-directory’ if it is |
| 528 |
given (*note Output file location::). However, if TeX processing |
| 529 |
is done on the command line (or in response to the ‘**’ prompt), |
| 530 |
the ‘.fls’ might be written to the current directory, or include an |
| 531 |
integer (the current pid), as in ‘texput1234.fls’. You can use |
| 532 |
‘-jobname’ to explicitly set the basename. |
| 533 |
|
| 534 |
‘-translate-file=TCXFILE’ |
| 535 |
Use TCXFILE to define which characters are printable and |
| 536 |
translations between the internal and external character sets. |
| 537 |
Moreover, TCXFILE can be explicitly declared in the first line of |
| 538 |
the main input file ‘%& -translate-file=TCXFILE’. This is the |
| 539 |
recommended method for portability reasons. *Note TCX files::. |
| 540 |
|
| 541 |
‘-8bit’ |
| 542 |
This option specifies that by default all characters should be |
| 543 |
considered printable. If ‘-translate-file’ was given as well, then |
| 544 |
the TCX file may mark characters as non-printable. This is a no-op |
| 545 |
in engines natively supporting Unicode. |
| 546 |
|
| 547 |
|
| 548 |
File: web2c.info, Node: Path searching, Next: Output file location, Prev: Common options, Up: Commonalities |
| 549 |
|
| 550 |
3.3 Path searching |
| 551 |
================== |
| 552 |
|
| 553 |
All of the Web2c programs, including TeX, which do path searching use |
| 554 |
the Kpathsea routines to do so. The precise names of the environment |
| 555 |
and configuration file variables which get searched for particular file |
| 556 |
formatted are therefore documented in the Kpathsea manual (*note |
| 557 |
(kpathsea)Supported file formats::). Reading ‘texmf.cnf’ (*note |
| 558 |
(kpathsea)Config files::), invoking ‘mktex...’ scripts (*note |
| 559 |
(kpathsea)mktex scripts::), and so on are all handled by Kpathsea. |
| 560 |
|
| 561 |
The programs which read fonts make use of another Kpathsea feature: |
| 562 |
‘texfonts.map’, which allows arbitrary aliases for the actual names of |
| 563 |
font files; for example, ‘Times-Roman’ for ‘ptmr8r.tfm’. The |
| 564 |
distributed (and installed by default) ‘texfonts.map’ includes aliases |
| 565 |
for many widely available PostScript fonts by their PostScript names. |
| 566 |
|
| 567 |
|
| 568 |
File: web2c.info, Node: Output file location, Prev: Path searching, Up: Commonalities |
| 569 |
|
| 570 |
3.4 Output file location |
| 571 |
======================== |
| 572 |
|
| 573 |
All the programs generally follow the usual convention for output files; |
| 574 |
namely, they are placed in the directory current when the program is |
| 575 |
run, regardless of any input file location; or, in a few cases, output |
| 576 |
is to standard output. The main programs (TeX, Metafont, MetaPost) |
| 577 |
provide several ways to override this, as explained below. |
| 578 |
|
| 579 |
For example, if you run ‘tex /tmp/foo’, by default the output will be |
| 580 |
in ‘./foo.dvi’ and ‘./foo.log’, not ‘/tmp/foo.dvi’ and ‘/tmp/foo.log’. |
| 581 |
|
| 582 |
An explicitly-given output location is also checked for input files, |
| 583 |
as TeX often generates files that need to be subsequently read. For |
| 584 |
input, the input filename is simply checked as given. No suffixes, such |
| 585 |
as ‘.tex’, are added by default, and no exhaustive path searching is |
| 586 |
done. |
| 587 |
|
| 588 |
Override 1: ‘-output-directory’ option |
| 589 |
-------------------------------------- |
| 590 |
|
| 591 |
If the ‘-output-directory’ option is specified, all output files that |
| 592 |
would normally be written in the current directory are written in the |
| 593 |
specified directory instead. *Note Common options::. |
| 594 |
|
| 595 |
Override 2: ‘TEXMF_OUTPUT_DIRECTORY’ environment variable |
| 596 |
--------------------------------------------------------- |
| 597 |
|
| 598 |
Furthermore, if the ‘-output-directory’ option is specified, its |
| 599 |
argument is saved in the environment variable ‘TEXMF_OUTPUT_DIRECTORY’. |
| 600 |
This is for the benefit of any subprograms that might be called via |
| 601 |
‘\write18’ (*note Shell escapes::), such as ‘kpsewhich’ (*note |
| 602 |
(kpathsea)Invoking kpsewhich::). (This feature was added in TeX Live |
| 603 |
2024.) |
| 604 |
|
| 605 |
If the ‘-output-directory’ option is not specified, but the |
| 606 |
environment variable ‘TEXMF_OUTPUT_DIRECTORY’ is set, then the |
| 607 |
environment variable value is used just as if it had been given to the |
| 608 |
option. |
| 609 |
|
| 610 |
Warning: we most strongly recommend always setting |
| 611 |
‘TEXMF_OUTPUT_DIRECTORY’ temporarily, for a given run. It has great |
| 612 |
potential for confusion, since with it set, output files will not be in |
| 613 |
the expected place. To reduce this chance somewhat, |
| 614 |
‘TEXMF_OUTPUT_DIRECTORY’ must be set in the environment, not a |
| 615 |
configuration file. |
| 616 |
|
| 617 |
Override 3: ‘TEXMFOUTPUT’ environment variable |
| 618 |
---------------------------------------------- |
| 619 |
|
| 620 |
Finally, if neither ‘-output-directory’ nor ‘TEXMF_OUTPUT_DIRECTORY’ is |
| 621 |
set, _and_ an output file is not writable, then the main programs (TeX, |
| 622 |
Metafont, MetaPost), plus BibTeX for this one case, make an exception: |
| 623 |
if the config file or environment variable value ‘TEXMFOUTPUT’ is set |
| 624 |
(it is not by default), the output file is written to the directory |
| 625 |
specified. Usually this is because the current directory is not |
| 626 |
writable, and thus all output files are written to ‘TEXMFOUTPUT’, but |
| 627 |
technically it works on a file-by-file basis. |
| 628 |
|
| 629 |
None of these explicitly-given output locations are checked until |
| 630 |
(and unless) the program needs to write a file. For example, the |
| 631 |
invocation |
| 632 |
‘tex --output-directory=/nonesuch \\end’ |
| 633 |
won't generate an error until TeX tries to write the log file: |
| 634 |
‘! I can't write on file `texput.log'.’. |
| 635 |
|
| 636 |
|
| 637 |
File: web2c.info, Node: Three programs, Next: TeX, Prev: Commonalities, Up: Top |
| 638 |
|
| 639 |
4 Three programs: Metafont, MetaPost, and TeX |
| 640 |
********************************************* |
| 641 |
|
| 642 |
TeX, Metafont, and MetaPost have a number of features in common. |
| 643 |
Besides the ones here, command-line options and other commonalities are |
| 644 |
described in the previous section. |
| 645 |
|
| 646 |
* Menu: |
| 647 |
|
| 648 |
* Runtime options:: The ‘texmf.cnf’ configuration file. |
| 649 |
* Initial and virgin:: Making memory dumps vs. production runs. |
| 650 |
* Memory dumps:: .fmt/.base files for fast startup. |
| 651 |
* Editor invocation:: The 'e' response at errors. |
| 652 |
* \input filenames:: Filename delimiters and Kpathsea expansion. |
| 653 |
|
| 654 |
|
| 655 |
File: web2c.info, Node: Runtime options, Next: Initial and virgin, Up: Three programs |
| 656 |
|
| 657 |
4.1 Runtime options |
| 658 |
=================== |
| 659 |
|
| 660 |
Besides the configure- and compile-time options described in the |
| 661 |
installation section (*note Installation::), you can control a number of |
| 662 |
parameters in the ‘texmf.cnf’ runtime file read by Kpathsea (*note |
| 663 |
(kpathsea)Config files::). |
| 664 |
|
| 665 |
The main purpose of ‘texmf.cnf’ is to specify search paths, but array |
| 666 |
sizes and other options are also set there. Most are rather obscure. |
| 667 |
Here are a few of the more interesting values: |
| 668 |
|
| 669 |
‘main_memory’ |
| 670 |
Total words of memory available, for TeX, Metafont, and MetaPost. |
| 671 |
Must remake the format file after changing. |
| 672 |
|
| 673 |
‘extra_mem_bot’ |
| 674 |
Extra space for "large" TeX data structures (default 0): boxes, |
| 675 |
glue, breakpoints, et al. If you use PiCTeX, you may well want to |
| 676 |
set this. |
| 677 |
|
| 678 |
‘expand_depth’ |
| 679 |
Limit on recursive expansion calls before TeX aborts (default |
| 680 |
10000). If a TeX program does an unterminated recursive expansion, |
| 681 |
TeX will dutifully expand macros until the system's runtime stack |
| 682 |
overflows, typically with a segmentation fault (SIGSEGV). This |
| 683 |
parameter was introduced to minimize the chance of that unpleasant |
| 684 |
(though not dangerous) crash, instead allowing TeX to quit with a |
| 685 |
more informative message. |
| 686 |
|
| 687 |
The crash can still happen, though, if the system has an |
| 688 |
exceptionally small memory allocation for its stack. There is no |
| 689 |
quantitative way to determine the limit, and it does not seem worth |
| 690 |
implementing system-dependent heuristics to guess at the number, |
| 691 |
since it's highly improbable that any real TeX code will ever need |
| 692 |
more than 10000 recursive expansions (it has never happened). For |
| 693 |
the same reason, using the libsigsegv library |
| 694 |
(<https://gnu.org/s/libsigsegv>) does not seem worth the effort. |
| 695 |
|
| 696 |
‘texmf_casefold_search’ |
| 697 |
*Note (kpathsea)Casefolding search::. |
| 698 |
|
| 699 |
Ideally all arrays would be dynamically expanded as necessary, so the |
| 700 |
only limiting factor would be the amount of swap space available, or |
| 701 |
some configurable limit much larger than can currently be supported. |
| 702 |
|
| 703 |
Unfortunately, implementing this is extremely difficult, as the fixed |
| 704 |
size of arrays is assumed in many places throughout the source code. |
| 705 |
These runtime limits are a practical compromise between the compile-time |
| 706 |
limits in previous versions, and truly dynamic arrays. (On the other |
| 707 |
hand, the Web2c BibTeX implementation does do true dynamic reallocation |
| 708 |
of some arrays.) |
| 709 |
|
| 710 |
Nowadays there is rarely a reason to modify the values. But if you |
| 711 |
do wish to modify ‘texmf.cnf’, in TeX Live the best approach is to put |
| 712 |
your changes, and only your changes at the top of the TL installation |
| 713 |
tree. That is, if the system ‘texmf.cnf’ is installed in |
| 714 |
‘/some/path/to/texlive/YYYY/texmf-dist/web2c/texmf.cnf’ is put your |
| 715 |
custom settings in ‘/some/path/to/texlive/YYY/texmf.cnf’, where YYYY is |
| 716 |
the year of installation (if you use that subdirectory; it's the |
| 717 |
default). That way, unrelated changes to the system ‘texmf.cnf’ can |
| 718 |
happen with normal updates, without affecting your local values. |
| 719 |
|
| 720 |
|
| 721 |
File: web2c.info, Node: Initial and virgin, Next: Memory dumps, Prev: Runtime options, Up: Three programs |
| 722 |
|
| 723 |
4.2 Initial and virgin |
| 724 |
====================== |
| 725 |
|
| 726 |
The TeX and Metafont programs each have two main variants, called |
| 727 |
“initial” and “virgin”. MetaPost no longer makes this distinction. |
| 728 |
|
| 729 |
The initial form is enabled if: |
| 730 |
1. the ‘-ini’ option was specified; or |
| 731 |
2. the program name is ‘initex’ resp. ‘inimf’; or |
| 732 |
3. the first line of the main input file is ‘%&ini’; |
| 733 |
otherwise, the virgin form is used. |
| 734 |
|
| 735 |
The “virgin” form is the one generally invoked for production use. |
| 736 |
The first thing it does is read a memory dump (*note Determining the |
| 737 |
memory dump to use::), and then proceeds on with the main job. |
| 738 |
|
| 739 |
The “initial” form is generally used only to create memory dumps (see |
| 740 |
the next section). It starts up more slowly than the virgin form, |
| 741 |
because it must do lengthy initializations that are encapsulated in the |
| 742 |
memory dump file. |
| 743 |
|
| 744 |
|
| 745 |
File: web2c.info, Node: Memory dumps, Next: Editor invocation, Prev: Initial and virgin, Up: Three programs |
| 746 |
|
| 747 |
4.3 Memory dumps |
| 748 |
================ |
| 749 |
|
| 750 |
In typical use, TeX and Metafont require a large number of macros to be |
| 751 |
predefined; therefore, they support “memory dump” files, which can be |
| 752 |
read much more efficiently than ordinary source code. |
| 753 |
|
| 754 |
* Menu: |
| 755 |
|
| 756 |
* Creating memory dumps:: |
| 757 |
* Determining the memory dump to use:: |
| 758 |
* Hardware and memory dumps:: |
| 759 |
|
| 760 |
|
| 761 |
File: web2c.info, Node: Creating memory dumps, Next: Determining the memory dump to use, Up: Memory dumps |
| 762 |
|
| 763 |
4.3.1 Creating memory dumps |
| 764 |
--------------------------- |
| 765 |
|
| 766 |
The programs both create memory dumps in slightly idiosyncratic (thought |
| 767 |
substantially similar) way, so we describe the details in separate |
| 768 |
sections (references below). The basic idea is to run the initial |
| 769 |
version of the program (*note Initial and virgin::), read the source |
| 770 |
file to define the macros, and then execute the ‘\dump’ primitive. |
| 771 |
|
| 772 |
Also, each program uses a different filename extension for its memory |
| 773 |
dumps, since although they are completely analogous they are not |
| 774 |
interchangeable (TeX cannot read a Metafont memory dump, or vice versa). |
| 775 |
|
| 776 |
Here are the filename extensions with references to examples of |
| 777 |
creating memory dumps: |
| 778 |
|
| 779 |
TeX |
| 780 |
(‘.fmt’) *Note Initial TeX: Initial TeX. |
| 781 |
|
| 782 |
Metafont |
| 783 |
(‘.base’) *Note Initial Metafont::. |
| 784 |
|
| 785 |
MetaPost used to have an equivalent memory dump, called ‘.mem’, but |
| 786 |
no longer uses this; it now reads only source files. |
| 787 |
|
| 788 |
When making memory dumps, the programs read environment variables and |
| 789 |
configuration files for path searching and other values as usual. If |
| 790 |
you are making a new installation and have environment variables |
| 791 |
pointing to an old one, for example, you will probably run into |
| 792 |
difficulties. |
| 793 |
|
| 794 |
|
| 795 |
File: web2c.info, Node: Determining the memory dump to use, Next: Hardware and memory dumps, Prev: Creating memory dumps, Up: Memory dumps |
| 796 |
|
| 797 |
4.3.2 Determining the memory dump to use |
| 798 |
---------------------------------------- |
| 799 |
|
| 800 |
The virgin form (*note Initial and virgin::) of each program always |
| 801 |
reads a memory dump before processing normal source input. All three |
| 802 |
programs determine the memory dump to use in the same way: |
| 803 |
|
| 804 |
1. If the first non-option command-line argument begins with ‘&’, the |
| 805 |
program uses the remainder of that argument as the memory dump |
| 806 |
name. For example, running ‘tex \&super’ reads ‘super.fmt’. The |
| 807 |
backslash merely protects the ‘&’ against interpretation by the |
| 808 |
shell; quotes could also be used. TeX must see only the ‘&’. |
| 809 |
|
| 810 |
2. If the ‘-fmt’ resp. ‘-base’ option is specified, its value is used. |
| 811 |
|
| 812 |
3. If the ‘-progname’ option is specified, its value is used. |
| 813 |
|
| 814 |
4. If the first line of the main input file (which must be specified |
| 815 |
on the command line, not in response to the ‘**’ prompt) is |
| 816 |
‘%&DUMP’, and DUMP is an existing memory dump of the appropriate |
| 817 |
type, DUMP is used. |
| 818 |
|
| 819 |
The first line of the main input file can also specify which |
| 820 |
character translation file is to be used: |
| 821 |
‘%&-translate-file=TCXFILE’ (*note TCX files::). |
| 822 |
|
| 823 |
These two roles can be combined: ‘%&DUMP -translate-file=TCXFILE’. |
| 824 |
If this is done, the name of the dump must be given first. |
| 825 |
|
| 826 |
5. Otherwise, the program uses the program invocation name, most |
| 827 |
simply ‘tex’ resp. ‘mf’. For example, if ‘latex’ is a link to |
| 828 |
‘tex’, and the user runs ‘latex foo’, ‘latex.fmt’ will be used. |
| 829 |
|
| 830 |
|
| 831 |
File: web2c.info, Node: Hardware and memory dumps, Prev: Determining the memory dump to use, Up: Memory dumps |
| 832 |
|
| 833 |
4.3.3 Hardware and memory dumps |
| 834 |
------------------------------- |
| 835 |
|
| 836 |
By default, most memory dump files are sharable among architectures of |
| 837 |
different types; specifically, among machines of different endianness |
| 838 |
(*note (libc)Byte order::) and with different word sizes (4-byte ‘long’ |
| 839 |
vs. 8-byte ‘long’). This is a feature of the Web2c implementation, and |
| 840 |
is not true of all TeX implementations. |
| 841 |
|
| 842 |
However, with the advent of Lua as an embedded scripting language, |
| 843 |
some dumps have become unportable, namely ‘lualatex’, ‘optex’, and |
| 844 |
‘context’. These formats precompile Lua code into bytecode, which is |
| 845 |
architecture-specific for the sake of speed. With TeX Live, if you need |
| 846 |
to support multiple architectures with the same tree, you can explicitly |
| 847 |
set ‘TEXMFSYSVAR’ to different directories on the different systems. |
| 848 |
More discussion: <https://github.com/latex3/latex2e/issues/775>. |
| 849 |
|
| 850 |
The script ‘tl-check-fmtshare’ in the TeX Live source tree |
| 851 |
(‘Master/tlpkg/bin’) provides a relatively easy way to test that a |
| 852 |
‘.fmt’ built on the local host can be loaded by a TeX engine built on |
| 853 |
some remote host. |
| 854 |
|
| 855 |
If you specify ‘--disable-dump-share’ to ‘configure’, however, memory |
| 856 |
dumps will be endian-dependent. The reason to do this is speed. To |
| 857 |
achieve endian-independence, the reading of memory dumps on LittleEndian |
| 858 |
architectures, such as PC's and DEC architectures, is somewhat slowed |
| 859 |
(all the multibyte values have to be swapped). Usually, this is not |
| 860 |
noticeable, and the advantage of being able to share memory dumps across |
| 861 |
all platforms at a site outweighs the speed loss. But if you're trying |
| 862 |
to squeeze out every possible bit of performance, you may wish to do |
| 863 |
this. |
| 864 |
|
| 865 |
TeXnically, even without ‘--disable-dump-share’, sharing of ‘.fmt’ |
| 866 |
files cannot be guaranteed to work. Floating-point values are always |
| 867 |
written in native format, and hence will generally not be readable |
| 868 |
across platforms. Fortunately, TeX uses floating point only to |
| 869 |
represent glue ratios, and none of the common formats (plain, LaTeX, |
| 870 |
AMSTeX, ...) do any glue setting at ‘.fmt’-creation time. Metafont does |
| 871 |
not use floating point in any dumped value at all. |
| 872 |
|
| 873 |
Different memory dump files will never compare equal byte-for-byte, |
| 874 |
because the programs dump the current date and time. So don't be |
| 875 |
alarmed by this difference. |
| 876 |
|
| 877 |
If you don't know what endianness your machine is, and you're |
| 878 |
curious, here is a little C program to tell you. (The ‘configure’ |
| 879 |
script contains a similar program.) This is from the book ‘C: A |
| 880 |
Reference Manual’, by Samuel P. Harbison and Guy L. Steele Jr. (*note |
| 881 |
References::). |
| 882 |
|
| 883 |
main () |
| 884 |
{ |
| 885 |
/* Are we little or big endian? From Harbison&Steele. */ |
| 886 |
union |
| 887 |
{ |
| 888 |
long l; |
| 889 |
char c[sizeof (long)]; |
| 890 |
} u; |
| 891 |
u.l = 1; |
| 892 |
if (u.c[0] == 1) |
| 893 |
printf ("LittleEndian\n"); |
| 894 |
else if (u.c[sizeof (long) - 1] == 1) |
| 895 |
printf ("BigEndian\n"); |
| 896 |
else |
| 897 |
printf ("unknownEndian"); |
| 898 |
|
| 899 |
exit (u.c[sizeof (long) - 1] == 1); |
| 900 |
} |
| 901 |
|
| 902 |
You can add ‘printf("long %d\n", sizeof(long));’ to see the size of |
| 903 |
the ‘long’ data type. |
| 904 |
|
| 905 |
|
| 906 |
File: web2c.info, Node: Editor invocation, Next: \input filenames, Prev: Memory dumps, Up: Three programs |
| 907 |
|
| 908 |
4.4 Editor invocation |
| 909 |
===================== |
| 910 |
|
| 911 |
TeX, Metafont, and MetaPost all (by default) stop and ask for user |
| 912 |
intervention at an error. If the input came from a file, and the user |
| 913 |
responds with ‘e’ or ‘E’, the program invokes an editor. |
| 914 |
|
| 915 |
Specifying ‘--with-editor=CMD’ to ‘configure’ sets the default editor |
| 916 |
command string to CMD. The environment variables/configuration values |
| 917 |
‘TEXEDIT’, ‘MFEDIT’, and ‘MPEDIT’ (respectively) override this. If |
| 918 |
‘--with-editor’ is not specified, the default is ‘vi +%d %s’ on Unix, |
| 919 |
and an invocation of the TeXworks editor on Windows. (See ‘texmf.cnf’ |
| 920 |
for the precise values.) |
| 921 |
|
| 922 |
In this string, ‘%d’ is replaced by the line number of the error, and |
| 923 |
‘%s’ is replaced by the name of the current input file. |
| 924 |
|
| 925 |
|
| 926 |
File: web2c.info, Node: \input filenames, Prev: Editor invocation, Up: Three programs |
| 927 |
|
| 928 |
4.5 ‘\input’ filenames |
| 929 |
====================== |
| 930 |
|
| 931 |
TeX, Metafont, and MetaPost source programs can all read other source |
| 932 |
files with the ‘\input’ (TeX) and ‘input’ (MF and MP) primitives: |
| 933 |
\input NAME % in TeX |
| 934 |
|
| 935 |
The file NAME can always be terminated with whitespace; for Metafont |
| 936 |
and MetaPost, the statement terminator ‘;’ also works. (LaTeX and other |
| 937 |
macro packages provide other interfaces to ‘\input’ that allow different |
| 938 |
notation; here we are concerned only with the primitive operation.) |
| 939 |
|
| 940 |
As an extension to standard TeX (allowed by Knuth's conditions), |
| 941 |
Web2c also supports specifying the filename in double quotes (‘"some |
| 942 |
name"’) and in a group, i.e., braces (‘{some name}’), which is |
| 943 |
convenient for filenames containing spaces or other special characters, |
| 944 |
as described in the sections below. |
| 945 |
|
| 946 |
In all cases, space tokens are ignored after the filename is read. |
| 947 |
|
| 948 |
Also, double quote (‘"’) characters are ignored within the filename; |
| 949 |
there is no way to read files whose names contain a ‘"’. |
| 950 |
|
| 951 |
For maximal portability of your document across systems, use only the |
| 952 |
characters ‘a’-‘z’, ‘0’-‘9’, and at most one ‘.’. Do not use anything |
| 953 |
but simple filenames, since directory separators vary among systems; |
| 954 |
instead, add the necessary directories to the appropriate search path. |
| 955 |
|
| 956 |
* Menu: |
| 957 |
|
| 958 |
* Quotes: \input quoted filename. \input "some name" |
| 959 |
* Braces: \input braced filename. \input {some name} |
| 960 |
* Caveats: \input filename caveats. Tokenization, nulls, Kpathsea expansion. |
| 961 |
|
| 962 |
|
| 963 |
File: web2c.info, Node: \input quoted filename, Next: \input braced filename, Up: \input filenames |
| 964 |
|
| 965 |
4.5.1 ‘\input’ quoted filename: ‘\input "some name"’ |
| 966 |
---------------------------------------------------- |
| 967 |
|
| 968 |
As of Web2c version 7.5.3 (2004), double-quote characters can be used to |
| 969 |
include spaces or other special characters. In typical use, the ‘"’ |
| 970 |
characters surround the entire filename: |
| 971 |
\input "filename with spaces" |
| 972 |
|
| 973 |
Technically, the quote characters can be used inside the name, and |
| 974 |
can enclose any characters, as in: |
| 975 |
\input filename" "with" "spaces |
| 976 |
|
| 977 |
One more point. In LaTeX, the quotes are needed inside the braces of |
| 978 |
its ‘\input’ macro, thus: |
| 979 |
\input{a b} % fails |
| 980 |
\input{"a b"} % ok |
| 981 |
|
| 982 |
There is no way to quote the quote character. |
| 983 |
|
| 984 |
|
| 985 |
File: web2c.info, Node: \input braced filename, Next: \input filename caveats, Prev: \input quoted filename, Up: \input filenames |
| 986 |
|
| 987 |
4.5.2 ‘\input’ braced filename: ‘\input{some name}’ |
| 988 |
--------------------------------------------------- |
| 989 |
|
| 990 |
As of Web2c 2020, ‘\input’ filenames in TeX engines (this does not apply |
| 991 |
in Metafont and MetaPost) can also be specified within a TeX group, |
| 992 |
typically curly braces. For example: |
| 993 |
\input{filename with spaces} |
| 994 |
|
| 995 |
As always with TeX, the brace characters are not hardwired; what |
| 996 |
counts is the category code: the first token after the ‘\input’ must be |
| 997 |
of catcode 1 (begin group), and it is matched with the next character of |
| 998 |
catcode 2 (end group). |
| 999 |
|
| 1000 |
Within the group-delimited filename, braces are treated as normal |
| 1001 |
characters. |
| 1002 |
|
| 1003 |
As with all forms of filenames, following spaces are ignored (after |
| 1004 |
the end group), and double quote (‘"’) characters are ignored within the |
| 1005 |
filename. |
| 1006 |
|
| 1007 |
|
| 1008 |
File: web2c.info, Node: \input filename caveats, Prev: \input braced filename, Up: \input filenames |
| 1009 |
|
| 1010 |
4.5.3 ‘\input’ filename caveats |
| 1011 |
------------------------------- |
| 1012 |
|
| 1013 |
The quoting mechanisms just described come into play _after_ TeX has |
| 1014 |
tokenized and expanded the input. So, multiple spaces and tabs will |
| 1015 |
generally be seen as a single space, active characters such as ‘~’ are |
| 1016 |
expanded first (generally causing an error), and so on. More examples |
| 1017 |
below. |
| 1018 |
|
| 1019 |
Various C library routines and Unix itself use the null byte |
| 1020 |
(character code zero, ASCII NUL) to terminate strings. So filenames in |
| 1021 |
Web2c cannot contain nulls, even though TeX itself does not treat NUL |
| 1022 |
specially. |
| 1023 |
|
| 1024 |
Windows reserves a long list of alphanumeric filenames, |
| 1025 |
case-insensitive and with any extension, such as ‘CON’, ‘NUL’, ‘COM1’, |
| 1026 |
‘con.tex’, etc.; see Windows systems documentation for the whole list. |
| 1027 |
Trying to use such names will cause a system error on Windows. |
| 1028 |
|
| 1029 |
Finally, the present Web2c implementation does ‘~’ and ‘$’ expansion |
| 1030 |
on NAME, on all platforms, unlike Knuth's original program. Thus: |
| 1031 |
|
| 1032 |
\input ~jsmith/$foo.bar |
| 1033 |
|
| 1034 |
will dereference the environment variable or Kpathsea config file value |
| 1035 |
‘foo’ and read that file, extended with ‘.bar’, in user ‘jsmith’'s home |
| 1036 |
directory. You can also use braces in the variable expansion, as in |
| 1037 |
‘${foo}bar’, if you want to follow the variable name with a letter, |
| 1038 |
numeral, or ‘_’. |
| 1039 |
|
| 1040 |
(So, another way to get a program to read a filename containing |
| 1041 |
whitespace is to define an environment variable and dereference it.) |
| 1042 |
|
| 1043 |
In all the common TeX formats (plain TeX, LaTeX, ConTeXt, ...), the |
| 1044 |
characters ‘~’ and ‘$’ have special category codes, so to use them |
| 1045 |
within a document you have to change their catcodes or use ‘\string’. |
| 1046 |
|
| 1047 |
|
| 1048 |
File: web2c.info, Node: TeX, Next: Metafont, Prev: Three programs, Up: Top |
| 1049 |
|
| 1050 |
5 TeX: Typesetting |
| 1051 |
****************** |
| 1052 |
|
| 1053 |
TeX is a typesetting system: it was especially designed to handle |
| 1054 |
complex mathematics, as well as most ordinary text typesetting. |
| 1055 |
|
| 1056 |
TeX is a batch language, like C or Pascal, and not an interactive |
| 1057 |
"word processor": you compile a TeX input file into a corresponding |
| 1058 |
device-independent (DVI) file (and then translate the DVI file to the |
| 1059 |
commands for a particular output device). This approach has both |
| 1060 |
considerable disadvantages and considerable advantages. For a complete |
| 1061 |
description of the TeX language, see ‘The TeXbook’ (*note References::). |
| 1062 |
Many other books on TeX, introductory and otherwise, are available. |
| 1063 |
|
| 1064 |
* Menu: |
| 1065 |
|
| 1066 |
* tex invocation:: Invoking TeX. |
| 1067 |
* Initial TeX:: Making format files. |
| 1068 |
* Formats:: Major TeX macro packages. |
| 1069 |
* Languages and hyphenation:: TeX supports many human languages. |
| 1070 |
* Shell escapes:: Running subprograms from TeX. |
| 1071 |
* IPC and TeX:: DVI output to a socket. |
| 1072 |
* TeX extensions:: Additional engines with additional features. |
| 1073 |
|
| 1074 |
|
| 1075 |
File: web2c.info, Node: tex invocation, Next: Initial TeX, Up: TeX |
| 1076 |
|
| 1077 |
5.1 ‘tex’ invocation |
| 1078 |
==================== |
| 1079 |
|
| 1080 |
TeX (usually invoked as ‘tex’) formats the given text and commands, and |
| 1081 |
outputs a corresponding device-independent representation of the typeset |
| 1082 |
document. This section merely describes the options available in the |
| 1083 |
Web2c implementation. For a complete description of the TeX typesetting |
| 1084 |
language, see ‘The TeXbook’ (*note References::). |
| 1085 |
|
| 1086 |
TeX, Metafont, and MetaPost process the command line (described here) |
| 1087 |
and determine their memory dump (fmt) file in the same way (*note Memory |
| 1088 |
dumps::). Synopses: |
| 1089 |
|
| 1090 |
tex [OPTION]... [TEXNAME[.tex]] [MORE-INPUT] |
| 1091 |
tex [OPTION]... \MORE-INPUT |
| 1092 |
tex [OPTION]... &FMT FIRST-LINE |
| 1093 |
|
| 1094 |
In short, TeX prepends ‘\input ’ to non-option command line arguments |
| 1095 |
or the input to the ‘**’ prompt, and then processes the result as normal |
| 1096 |
TeX input, including expansion. |
| 1097 |
|
| 1098 |
The most common invocation is ‘tex somefile’, which reads |
| 1099 |
‘somefile.tex’, normally from the current directory. It is equivalent |
| 1100 |
to ‘\input somefile’. |
| 1101 |
|
| 1102 |
In more detail: |
| 1103 |
|
| 1104 |
TeX searches the usual places for the main input file TEXNAME (*note |
| 1105 |
(kpathsea)Supported file formats::), extending TEXNAME with ‘.tex’ if |
| 1106 |
necessary. To see all the relevant paths, set the environment variable |
| 1107 |
‘KPATHSEA_DEBUG’ to ‘-1’ before running the program. |
| 1108 |
|
| 1109 |
After TEXNAME is read, TeX processes any remaining MORE-INPUT on the |
| 1110 |
command line as regular TeX input. Also, if the first non-option |
| 1111 |
argument begins with a TeX escape character (usually ‘\’), TeX processes |
| 1112 |
all non-option command-line arguments as a line of regular TeX input. |
| 1113 |
The backslash or other escape character usually has to be escaped to |
| 1114 |
avoid being processed by your shell. |
| 1115 |
|
| 1116 |
If no arguments or options are specified, TeX prompts for an input |
| 1117 |
filename with ‘**’. Whatever input is given in response to ‘**’ is |
| 1118 |
processed exactly like a command line not starting with an escape |
| 1119 |
character, i.e., ‘\input’ is prepended and then the entire line is |
| 1120 |
processed as normal TeX intput. |
| 1121 |
|
| 1122 |
Thus, the text of an input filename, as well as any text following a |
| 1123 |
filename, is subject to TeX's normal macro expansion. As a result, a |
| 1124 |
‘~’ character is normally not usable within a filename, since by default |
| 1125 |
‘~’ is defined (in plain TeX, LaTeX, etc.) to be an active character |
| 1126 |
that expands into several primitive tokens that can't be part of a |
| 1127 |
filename. As a special case in Web2c, a ‘~’ _beginning_ a filename |
| 1128 |
refers to a user's home directory (*note \input filename caveats::), but |
| 1129 |
you still have to arrange for TeX to see a ‘~’ character rather than the |
| 1130 |
expansion of ‘~’. |
| 1131 |
|
| 1132 |
To summarize the usual cases (in all these cases, ‘tex’ also reads |
| 1133 |
‘tex.fmt’ before starting any processing): |
| 1134 |
|
| 1135 |
• ‘tex foo’ executes ‘\input foo’. |
| 1136 |
|
| 1137 |
• ‘tex foo bar’ executes ‘\input foo bar’, which inputs ‘foo.tex’ and |
| 1138 |
then typesets ‘bar’. |
| 1139 |
|
| 1140 |
• ‘tex \\end’ executes ‘\end’; here the double backslash is one |
| 1141 |
common way of escaping the backslash for the shell. TeX only sees |
| 1142 |
one backslash. |
| 1143 |
|
| 1144 |
• ‘tex’ with no arguments prints a ‘**’ prompt. Entering ‘foo bar’ |
| 1145 |
at the ‘**’ prompt again executes ‘\input foo’ and typesets ‘bar’. |
| 1146 |
|
| 1147 |
TeX writes its main output, a DVI file, to ‘BASETEXNAME.dvi’, where |
| 1148 |
BASETEXNAME is the basename of TEXNAME, or ‘texput’ if no input file was |
| 1149 |
specified. |
| 1150 |
|
| 1151 |
A DVI file is a device-independent binary representation of your |
| 1152 |
document. You can translate the DVI file, using independent programs, |
| 1153 |
to whatever may be needed, such as a PDF file (see dvipdfmx(1)), a |
| 1154 |
PostScript file (*note Introduction: (dvips)Top.), an SVG file (see |
| 1155 |
dvisvgm(1)), etc. There are also variants of TeX that can produce PDF |
| 1156 |
files directly, namely pdfTeX and LuaTeX (*note TeX extensions::). |
| 1157 |
|
| 1158 |
The program accepts the following options, as well as the standard |
| 1159 |
‘-help’ and ‘-version’ (*note Common options::): |
| 1160 |
|
| 1161 |
‘-enc’ |
| 1162 |
‘-[no]-file-line-error’ |
| 1163 |
‘-fmt=FMTNAME’ |
| 1164 |
‘-halt-on-error’ |
| 1165 |
‘-ini’ |
| 1166 |
‘-interaction=STRING’ |
| 1167 |
‘-ipc’ |
| 1168 |
‘-ipc-start’ |
| 1169 |
‘-jobname=STRING’ |
| 1170 |
‘-kpathsea-debug=NUMBER’ |
| 1171 |
‘-[no]parse-first-line’ |
| 1172 |
‘-output-directory’ |
| 1173 |
‘-progname=STRING’ |
| 1174 |
‘-recorder’ |
| 1175 |
‘-translate-file=TCXFILE’ |
| 1176 |
‘-8bit’ |
| 1177 |
These options are common to TeX, Metafont, and MetaPost. *Note |
| 1178 |
Common options::. |
| 1179 |
|
| 1180 |
‘-enc’ |
| 1181 |
Enable encTeX extensions, such as ‘\mubyte’. This can be used to |
| 1182 |
support the Unicode UTF-8 input encoding, although using an engine |
| 1183 |
with native Unicode support is more common nowadays. |
| 1184 |
<http://www.olsak.net/enctex.html>. |
| 1185 |
|
| 1186 |
‘-ipc’ |
| 1187 |
‘-ipc-start’ |
| 1188 |
With either option, TeX writes its DVI output to a socket as well |
| 1189 |
as to the usual ‘.dvi’ file. With ‘-ipc-start’, TeX also opens a |
| 1190 |
server program at the other end to read the output. *Note IPC and |
| 1191 |
TeX: IPC and TeX. |
| 1192 |
|
| 1193 |
These options are available only if the ‘--enable-ipc’ option was |
| 1194 |
specified to ‘configure’ during installation of Web2c. |
| 1195 |
|
| 1196 |
‘-mktex=FILETYPE’ |
| 1197 |
‘-no-mktex=FILETYPE’ |
| 1198 |
Turn on or off the ‘mktex’ script associated with FILETYPE. For |
| 1199 |
TeX proper, FILETYPE can only be ‘tex’ and ‘tfm’, but for pdfTeX |
| 1200 |
and LuaTeX, it can also be ‘pk’. |
| 1201 |
|
| 1202 |
‘-mltex’ |
| 1203 |
If we are ‘INITEX’ (*note Initial and virgin::), enable MLTeX |
| 1204 |
extensions such as ‘\charsubdef’. Implicitly set if the program |
| 1205 |
name is ‘mltex’. *Note MLTeX: MLTeX. |
| 1206 |
|
| 1207 |
‘-output-comment=STRING’ |
| 1208 |
Use STRING as the DVI file comment. Ordinarily, this comment |
| 1209 |
records the date and time of the TeX run, but if you are doing |
| 1210 |
regression testing, you may not want the DVI file to have this |
| 1211 |
spurious difference. This is also taken from the environment |
| 1212 |
variable and config file value ‘output_comment’. |
| 1213 |
|
| 1214 |
‘-shell-escape’ |
| 1215 |
‘-no-shell-escape’ |
| 1216 |
‘-shell-restricted’ |
| 1217 |
Enable, or disable, or enable with restrictions the |
| 1218 |
‘\write18{SHELL-COMMAND}’ feature for external execution of shell |
| 1219 |
commands. *Note Shell escapes::. |
| 1220 |
|
| 1221 |
‘-enable-write18’ |
| 1222 |
‘-disable-write18’ |
| 1223 |
Synonyms for ‘-shell-escape’ and ‘-no-shell-escape’, for |
| 1224 |
compatibility with MiKTeX. (MiKTeX also accepts both pairs of |
| 1225 |
options.) *Note Shell escapes::. |
| 1226 |
|
| 1227 |
‘-src-specials’ |
| 1228 |
‘-src-specials=STRING’ |
| 1229 |
This option makes TeX output specific source information using |
| 1230 |
‘\special’ commands in the DVI file. These ‘\special’ track the |
| 1231 |
current filename and line number. |
| 1232 |
|
| 1233 |
Using the first form of this option, the ‘\special’ commands are |
| 1234 |
inserted automatically. |
| 1235 |
|
| 1236 |
In the second form of the option, STRING is a comma separated list |
| 1237 |
of the following values: ‘cr’, ‘display’, ‘hbox’, ‘math’, ‘par’, |
| 1238 |
‘parend’, ‘vbox’. You can use this list to specify where you want |
| 1239 |
TeX to output such commands. For example, ‘-src-specials=cr,math’ |
| 1240 |
will output source information every line and every math formula. |
| 1241 |
|
| 1242 |
These commands can be used with the appropriate DVI viewer and text |
| 1243 |
editor to switch from the current position in the editor to the |
| 1244 |
same position in the viewer and back from the viewer to the editor. |
| 1245 |
|
| 1246 |
This option works by inserting ‘\special’ commands into the token |
| 1247 |
stream, and thus in principle these additional tokens can be |
| 1248 |
recovered or seen by the tricky-enough macros. If you run across a |
| 1249 |
case, let us know, because this counts as a bug. However, such |
| 1250 |
bugs are very hard to fix, requiring significant changes to TeX, so |
| 1251 |
please don't count on it. |
| 1252 |
|
| 1253 |
Redefining ‘\special’ will not affect the functioning of this |
| 1254 |
option. The commands inserted into the token stream are hard-coded |
| 1255 |
to always use the ‘\special’ primitive. |
| 1256 |
|
| 1257 |
TeX does not pass the ‘TRIP’ test when this option is enabled. |
| 1258 |
|
| 1259 |
Other input and output that can happen: |
| 1260 |
|
| 1261 |
• TeX also reads TFM files for any fonts you load in your document |
| 1262 |
with the ‘\font’ primitive. By default, it runs an external |
| 1263 |
program named ‘mktextfm’ to create any nonexistent TFM files. You |
| 1264 |
can disable this at configure-time or runtime (*note |
| 1265 |
(kpathsea)mktex configuration::). |
| 1266 |
|
| 1267 |
• TeX can write output files, via the ‘\openout’ primitive. This |
| 1268 |
raises the possibility of a Trojan horse attack: an unwitting user |
| 1269 |
could run a TeX program that overwrites, say, |
| 1270 |
‘$HOME/.ssh/authorized_keys’. (MetaPost has a ‘write’ primitive |
| 1271 |
with similar implications.) |
| 1272 |
|
| 1273 |
To alleviate this and similar problems, the functions |
| 1274 |
‘kpathsea_out_name_ok’ and ‘kpathsea_in_name_ok’ from the Kpathsea |
| 1275 |
library (*note (kpathsea)Calling sequence::) are used to determine |
| 1276 |
if a given filename is acceptable to be opened for output or input, |
| 1277 |
depending on the setting of the configuration variables |
| 1278 |
‘openout_any’ and ‘openin_any’: ‘a’ (for "any", the default for |
| 1279 |
‘openin_any’), ‘r’ (for "restricted"), or ‘p’ (for "paranoid", the |
| 1280 |
default for ‘openout_any’). |
| 1281 |
|
| 1282 |
In any case, all ‘\openout’ filenames are recorded in the log file, |
| 1283 |
except those opened on the first line of input, which is processed |
| 1284 |
before the log file has been opened. |
| 1285 |
|
| 1286 |
|
| 1287 |
File: web2c.info, Node: Initial TeX, Next: Formats, Prev: tex invocation, Up: TeX |
| 1288 |
|
| 1289 |
5.2 Initial TeX |
| 1290 |
=============== |
| 1291 |
|
| 1292 |
The “initial” form of TeX is invoked by ‘tex -ini’. It does lengthy |
| 1293 |
initializations avoided by the "virgin" (‘vir’) form, so as to be |
| 1294 |
capable of dumping ‘.fmt’ files (*note Memory dumps::). For a detailed |
| 1295 |
comparison of virgin and initial forms, *note Initial and virgin::. |
| 1296 |
|
| 1297 |
For a list of options and other information, *note tex invocation::. |
| 1298 |
|
| 1299 |
Unlike Metafont and MetaPost, many format files are commonly used |
| 1300 |
with TeX. The standard one implementing the features described in ‘The |
| 1301 |
TeXbook’ is ‘plain.fmt’, also known as ‘tex.fmt’ (again, *note Memory |
| 1302 |
dumps::). It is created by default during installation, but you can |
| 1303 |
also do so by hand if necessary: |
| 1304 |
|
| 1305 |
tex -ini '\input plain \dump' |
| 1306 |
|
| 1307 |
(The quotes prevent interpretation of the backslashes from the shell.) |
| 1308 |
Then put the resulting ‘plain.fmt’ where TeX will find it, and link |
| 1309 |
‘tex.fmt’ to it. Any existing ‘tex.fmt’ can be found with the |
| 1310 |
invocation: |
| 1311 |
|
| 1312 |
kpsewhich --all --engine=/ tex.fmt |
| 1313 |
|
| 1314 |
*Note Formats::, for more details on TeX formats. |
| 1315 |
|
| 1316 |
|
| 1317 |
File: web2c.info, Node: Formats, Next: Languages and hyphenation, Prev: Initial TeX, Up: TeX |
| 1318 |
|
| 1319 |
5.3 Formats |
| 1320 |
=========== |
| 1321 |
|
| 1322 |
TeX “formats” are large collections of macros, often dumped into a |
| 1323 |
‘.fmt’ file (*note Memory dumps::) by ‘tex -ini’ (*note Initial TeX::). |
| 1324 |
A number of formats are in reasonably widespread use. The formats are |
| 1325 |
generally selected, installed, and updated as part of a larger TeX |
| 1326 |
distribution, such as TeX Live (<https://tug.org/texlive>). |
| 1327 |
|
| 1328 |
latex |
| 1329 |
The most widely used format, called LaTeX, based on LaTeX2e and |
| 1330 |
also incorporating LaTeX3; new versions are released approximately |
| 1331 |
every six months, with patches issued as needed. The old release |
| 1332 |
was called 'LaTeX 2.09', and is no longer maintained or supported, |
| 1333 |
though compatibility for 2.09 documents is retained. LaTeX |
| 1334 |
attempts to provide generic markup instructions, such as |
| 1335 |
"emphasize", instead of specific typesetting instructions, such as |
| 1336 |
"use the 10pt Computer Modern italic font". The LaTeX home page: |
| 1337 |
<https://www.latex-project.org>. |
| 1338 |
|
| 1339 |
latex-dev |
| 1340 |
A set of formats and executables made so that anyone interested can |
| 1341 |
easily help test upcoming LaTeX releases. They correspond to new |
| 1342 |
formats which have been tested by the LaTeX team for stability and |
| 1343 |
usability. Testing by as many users as possible is desired and |
| 1344 |
requested. Simply changing the regular engine name (e.g., |
| 1345 |
‘pdflatex’), to have a -dev suffix (‘pdflatex-dev’) in your |
| 1346 |
invocations is all that should be needed. No changes to source |
| 1347 |
documents should be required. |
| 1348 |
|
| 1349 |
context |
| 1350 |
ConTeXt is an independent macro package which also supports a |
| 1351 |
document structuring approach. It can also create interactive PDF |
| 1352 |
files and has an integrated MetaPost library for graphics, among |
| 1353 |
many other advanced features. It uses its own engine, LuaMetaTeX, |
| 1354 |
developed in tandem. The ConTeXt home page: |
| 1355 |
<http://www.pragma-ade.com>. |
| 1356 |
|
| 1357 |
eplain |
| 1358 |
An "expanded plain" format that provides various common features |
| 1359 |
(e.g., symbolic cross-referencing, tables of contents, indexing, |
| 1360 |
citations using BibTeX), for those authors who prefer to handle |
| 1361 |
their own high-level formatting. The Eplain home page: |
| 1362 |
<https://tug.org/eplain>. |
| 1363 |
|
| 1364 |
texinfo |
| 1365 |
The documentation system developed and maintained by the Free |
| 1366 |
Software Foundation for their software manuals. It can be |
| 1367 |
automatically converted into HTML, plain text, a machine-readable |
| 1368 |
online format called Info, etc. The Texinfo home page: |
| 1369 |
<https://www.gnu.org/software/texinfo>. |
| 1370 |
|
| 1371 |
amstex |
| 1372 |
This was the official typesetting system of the American |
| 1373 |
Mathematical Society; nowadays, the AMS recommends authors use |
| 1374 |
LaTeX; the AMS provides a number of LaTeX packages important for |
| 1375 |
math typesetting. The AMS's TeX page: <https://www.ams.org/tex>. |
| 1376 |
|
| 1377 |
slitex |
| 1378 |
An obsolete LaTeX 2.09 format for making slides. In core LaTeX2e, |
| 1379 |
it is replaced by the ‘slides’ document class. As of 2025, the |
| 1380 |
‘ltx-talk’ class is also provided for typesetting presentations, |
| 1381 |
including accessibility support: <https://ctan.org/pkg/ltx-talk>. |
| 1382 |
The ‘beamer’ package is perhaps the most commonly used method for |
| 1383 |
making slides nowadays: <https://ctan.org/pkg/beamer>. |
| 1384 |
|
| 1385 |
|
| 1386 |
File: web2c.info, Node: Languages and hyphenation, Next: Shell escapes, Prev: Formats, Up: TeX |
| 1387 |
|
| 1388 |
5.4 Languages and hyphenation |
| 1389 |
============================= |
| 1390 |
|
| 1391 |
TeX supports most natural languages. See also *note TeX extensions: TeX |
| 1392 |
extensions. |
| 1393 |
|
| 1394 |
* Menu: |
| 1395 |
|
| 1396 |
* MLTeX:: Multi-lingual TeX. |
| 1397 |
* TCX files:: Support for different character sets & fonts. |
| 1398 |
* patgen invocation:: Creating hyphenation patterns. |
| 1399 |
|
| 1400 |
|
| 1401 |
File: web2c.info, Node: MLTeX, Next: TCX files, Up: Languages and hyphenation |
| 1402 |
|
| 1403 |
5.4.1 MLTeX: Multi-lingual TeX |
| 1404 |
------------------------------ |
| 1405 |
|
| 1406 |
Multi-lingual TeX (‘mltex’) is an extension of TeX originally written by |
| 1407 |
Michael Ferguson and now updated and maintained by Bernd Raichle. With |
| 1408 |
the advent of Unicode, it has become obsolete, though it is still |
| 1409 |
supported in Web2c in the event of bugs or compilation bugs. |
| 1410 |
|
| 1411 |
MLTeX allows the use of non-existing glyphs in a font by declaring |
| 1412 |
glyph substitutions. These are restricted to substitutions of an |
| 1413 |
accented character glyph, which need not be defined in the current font, |
| 1414 |
by its appropriate ‘\accent’ construction using a base and accent |
| 1415 |
character glyph, which do have to exist in the current font. This |
| 1416 |
substitution is automatically done behind the scenes, if necessary, and |
| 1417 |
thus MLTeX additionally supports hyphenation of words containing an |
| 1418 |
accented character glyph for fonts missing this glyph (e.g., Computer |
| 1419 |
Modern). Standard TeX suppresses hyphenation in this case. |
| 1420 |
|
| 1421 |
MLTeX works at ‘.fmt’-creation time: the basic idea is to specify the |
| 1422 |
‘-mltex’ option to TeX when you ‘\dump’ a format. Then, when you |
| 1423 |
subsequently invoke TeX and read that ‘.fmt’ file, the MLTeX features |
| 1424 |
described below will be enabled. |
| 1425 |
|
| 1426 |
Generally, you use special macro files to create an MLTeX ‘.fmt’ |
| 1427 |
file. |
| 1428 |
|
| 1429 |
The sections below describe the two new primitives that MLTeX |
| 1430 |
defines. Aside from these, MLTeX is completely compatible with standard |
| 1431 |
TeX. |
| 1432 |
|
| 1433 |
* Menu: |
| 1434 |
|
| 1435 |
* \charsubdef:: Character substitution definitions. |
| 1436 |
* \tracingcharsubdef:: Tracing substitutions. |
| 1437 |
|
| 1438 |
|
| 1439 |
File: web2c.info, Node: \charsubdef, Next: \tracingcharsubdef, Up: MLTeX |
| 1440 |
|
| 1441 |
5.4.1.1 ‘\charsubdef’: Character substitutions |
| 1442 |
.............................................. |
| 1443 |
|
| 1444 |
The most important primitive MLTeX adds is ‘\charsubdef’, used in a way |
| 1445 |
reminiscent of ‘\chardef’: |
| 1446 |
\charsubdef COMPOSITE [=] ACCENT BASE |
| 1447 |
|
| 1448 |
Each of COMPOSITE, ACCENT, and BASE are font glyph numbers, expressed |
| 1449 |
in the usual TeX syntax: `\e symbolically, '145 for octal, "65 for hex, |
| 1450 |
101 for decimal. |
| 1451 |
|
| 1452 |
MLTeX's ‘\charsubdef’ declares how to construct an accented character |
| 1453 |
glyph (not necessarily existing in the current font) using two character |
| 1454 |
glyphs (that do exist). Thus it defines whether a character glyph code, |
| 1455 |
either typed as a single character or using the ‘\char’ primitive, will |
| 1456 |
be mapped to a font glyph or to an ‘\accent’ glyph construction. |
| 1457 |
|
| 1458 |
For example, if you assume glyph code 138 (decimal) for an |
| 1459 |
e-circumflex and you are using the Computer Modern fonts, which have the |
| 1460 |
circumflex accent in position 18 and lowercase 'e' in the usual ASCII |
| 1461 |
position 101 decimal, you would use ‘\charsubdef’ as follows: |
| 1462 |
|
| 1463 |
\charsubdef 138 = 18 101 |
| 1464 |
|
| 1465 |
For the plain TeX format to make use of this substitution, you have |
| 1466 |
to redefine the circumflex accent macro ‘\^’ in such a way that if its |
| 1467 |
argument is character 'e' the expansion ‘\char138 ’ is used instead of |
| 1468 |
‘\accent18 e’. Similar ‘\charsubdef’ declaration and macro |
| 1469 |
redefinitions have to be done for all other accented characters. |
| 1470 |
|
| 1471 |
To disable a previous ‘\charsubdef C’, redefine C as a pair of zeros. |
| 1472 |
For example: |
| 1473 |
\charsubdef '321 = 0 0 % disable N tilde |
| 1474 |
(Octal '321 is the ISO Latin-1 value for the Spanish N tilde.) |
| 1475 |
|
| 1476 |
‘\charsubdef’ commands should only be given once. Although in |
| 1477 |
principle you can use ‘\charsubdef’ at any time, the result is |
| 1478 |
unspecified. If ‘\charsubdef’ declarations are changed, usually either |
| 1479 |
incorrect character dimensions will be used or MLTeX will output missing |
| 1480 |
character warnings. (The substitution of a ‘\charsubdef’ is used by TeX |
| 1481 |
when appending the character node to the current horizontal list, to |
| 1482 |
compute the width of a horizontal box when the box gets packed, and when |
| 1483 |
building the ‘\accent’ construction at ‘\shipout’-time. In summary, the |
| 1484 |
substitution is accessed often, so changing it is not desirable, nor |
| 1485 |
generally useful.) |
| 1486 |
|
| 1487 |
|
| 1488 |
File: web2c.info, Node: \tracingcharsubdef, Prev: \charsubdef, Up: MLTeX |
| 1489 |
|
| 1490 |
5.4.1.2 ‘\tracingcharsubdef’: Substitution diagnostics |
| 1491 |
...................................................... |
| 1492 |
|
| 1493 |
To help diagnose problems with ‘\charsubdef’, MLTeX provides a new |
| 1494 |
primitive parameter, ‘\tracingcharsubdef’. If positive, every use of |
| 1495 |
‘\charsubdef’ will be reported. This can help track down when a |
| 1496 |
character is redefined. |
| 1497 |
|
| 1498 |
In addition, if the TeX parameter ‘\tracinglostchars’ is 100 or more, |
| 1499 |
the character substitutions performed at ‘\shipout’-time will be |
| 1500 |
recorded. |
| 1501 |
|
| 1502 |
|
| 1503 |
File: web2c.info, Node: TCX files, Next: patgen invocation, Prev: MLTeX, Up: Languages and hyphenation |
| 1504 |
|
| 1505 |
5.4.2 TCX files: Character translations |
| 1506 |
--------------------------------------- |
| 1507 |
|
| 1508 |
TCX (TeX character translation) files help TeX support direct input of |
| 1509 |
8-bit international characters if fonts containing those characters are |
| 1510 |
being used. Specifically, they map an input (keyboard) character code |
| 1511 |
to the internal TeX character code (a superset of ASCII). |
| 1512 |
|
| 1513 |
Of the various proposals for handling more than one input encoding, |
| 1514 |
TCX files were chosen because they follow Knuth's original ideas for the |
| 1515 |
use of the ‘xchr’ and ‘xord’ tables. He ventured that these would be |
| 1516 |
changed in the WEB source in order to adjust the actual version to a |
| 1517 |
given environment. It turns out, however, that recompiling the WEB |
| 1518 |
sources is not as simple a task as Knuth may have imagined; therefore, |
| 1519 |
TCX files, providing the possibility of changing of the conversion |
| 1520 |
tables on on-the-fly, have been implemented instead. |
| 1521 |
|
| 1522 |
This approach limits the portability of TeX documents, as some |
| 1523 |
implementations do not support it (or use a different method for |
| 1524 |
input-internal reencoding). It may also be problematic to determine the |
| 1525 |
encoding to use for a TeX document of unknown provenance; in the worst |
| 1526 |
case, failure to do so correctly may result in subtle errors in the |
| 1527 |
typeset output. But we feel the benefits outweigh these disadvantages. |
| 1528 |
|
| 1529 |
This is entirely independent of the MLTeX extension (*note MLTeX::): |
| 1530 |
whereas a TCX file defines how an input keyboard character is mapped to |
| 1531 |
TeX's internal code, MLTeX defines substitutions for a non-existing |
| 1532 |
character glyph in a font with a ‘\accent’ construction made out of two |
| 1533 |
separate character glyphs. TCX files involve no new primitives; it is |
| 1534 |
not possible to specify that an input (keyboard) character maps to more |
| 1535 |
than one character. |
| 1536 |
|
| 1537 |
Information on specifying TCX files: |
| 1538 |
|
| 1539 |
• The best way to specify a TCX file is to list it explicitly in the |
| 1540 |
first line of the main document: |
| 1541 |
%& -translate-file=TCXFILE |
| 1542 |
|
| 1543 |
• You can also specify a TCX file to be used on a particular TeX run |
| 1544 |
with the command-line option ‘-translate-file=TCXFILE’. |
| 1545 |
|
| 1546 |
• TCX files are searched for along the ‘WEB2C’ path. |
| 1547 |
|
| 1548 |
• Initial TeX (*note Initial TeX: Initial TeX.) ignores TCX files. |
| 1549 |
|
| 1550 |
The Web2c distribution comes with a number of TCX files. Two |
| 1551 |
important ones are ‘il1-t1.tcx’ and ‘il2-t1.tcx’, which support ISO |
| 1552 |
Latin 1 and ISO Latin 2, respectively, with Cork-encoded fonts |
| 1553 |
(a.k.a. the LaTeX T1 encoding). TCX files for Czech, Polish, and Slovak |
| 1554 |
are also provided. |
| 1555 |
|
| 1556 |
One other notable TCX file is ‘empty.tcx’, which is, well, empty. |
| 1557 |
Its purpose is to reset Web2C's behavior to the default (only visible |
| 1558 |
ASCII being printable, as described below) when a format was dumped with |
| 1559 |
another TCX being active--which is in fact the case for everything but |
| 1560 |
plain TeX in the TeX Live and other distributions. Thus: |
| 1561 |
|
| 1562 |
latex somefile8.tex |
| 1563 |
⇒ terminal etc. output with 8-bit chars |
| 1564 |
latex --translate-file=empty.tcx somefile8.tex |
| 1565 |
⇒ terminal etc. output with ^^ notation |
| 1566 |
|
| 1567 |
Syntax of TCX files: |
| 1568 |
1. Line-oriented. Blank lines are ignored. |
| 1569 |
|
| 1570 |
2. Whitespace is ignored except as a separator. |
| 1571 |
|
| 1572 |
3. Comments start with ‘%’ and continue to the end of the line. |
| 1573 |
|
| 1574 |
4. Otherwise, a line consists of one or two character codes, |
| 1575 |
optionally followed by 0 or 1. The last number indicates whether |
| 1576 |
DEST is considered printable. |
| 1577 |
SRC [DEST [PRNT]] |
| 1578 |
|
| 1579 |
5. Each character code may be specified in octal with a leading ‘0’, |
| 1580 |
hexadecimal with a leading ‘0x’, or decimal otherwise. Values must |
| 1581 |
be between 0 and 255, inclusive (decimal). |
| 1582 |
|
| 1583 |
6. If the DEST code is not specified, it is taken to be the same as |
| 1584 |
SRC. |
| 1585 |
|
| 1586 |
7. If the same SRC code is specified more than once, it is the last |
| 1587 |
definition that counts. |
| 1588 |
|
| 1589 |
Finally, here's what happens: when TeX sees an input character with |
| 1590 |
code SRC, it 1) changes SRC to DEST; and 2) makes the DEST code |
| 1591 |
"printable", i.e., printed as-is in diagnostics and the log file rather |
| 1592 |
than in ‘^^’ notation. |
| 1593 |
|
| 1594 |
By default, no characters are translated, and character codes between |
| 1595 |
32 and 126 inclusive (decimal) are printable. |
| 1596 |
|
| 1597 |
Specifying translations for the printable ASCII characters (codes |
| 1598 |
32-127) will yield unpredictable results. Additionally you shouldn't |
| 1599 |
make the following characters printable: ‘^^I’ (TAB), ‘^^J’ (line feed), |
| 1600 |
‘^^M’ (carriage return), and ‘^^?’ (delete), since TeX uses them in |
| 1601 |
various ways. |
| 1602 |
|
| 1603 |
Thus, the idea is to specify the input (keyboard) character code for |
| 1604 |
SRC, and the output (font) character code for DEST. |
| 1605 |
|
| 1606 |
By default, only the printable ASCII characters are considered |
| 1607 |
printable by TeX. If you specify the ‘-8bit’ option, all characters are |
| 1608 |
considered printable by default. If you specify both the ‘-8bit’ option |
| 1609 |
and a TCX file, then the TCX can set specific characters to be |
| 1610 |
non-printable. |
| 1611 |
|
| 1612 |
Both the specified TCX encoding and whether characters are printable |
| 1613 |
are saved in the dump files (like ‘tex.fmt’). So by giving these |
| 1614 |
options in combination with ‘-ini’, you control the defaults seen by |
| 1615 |
anyone who uses the resulting dump file. |
| 1616 |
|
| 1617 |
When loading a dump, if the ‘-8bit’ option was given, then all |
| 1618 |
characters become printable by default. |
| 1619 |
|
| 1620 |
When loading a dump, if a TCX file was specified, then the TCX data |
| 1621 |
from the dump is ignored and the data from the file used instead. |
| 1622 |
|
| 1623 |
|
| 1624 |
File: web2c.info, Node: patgen invocation, Prev: TCX files, Up: Languages and hyphenation |
| 1625 |
|
| 1626 |
5.4.3 Patgen: Creating hyphenation patterns |
| 1627 |
------------------------------------------- |
| 1628 |
|
| 1629 |
Patgen creates hyphenation patterns from dictionary files for use with |
| 1630 |
TeX. Synopsis: |
| 1631 |
|
| 1632 |
patgen DICTIONARY PATTERNS OUTPUT TRANSLATE |
| 1633 |
|
| 1634 |
Each argument is a filename. No path searching is done. The output |
| 1635 |
is written to the file OUTPUT. |
| 1636 |
|
| 1637 |
In addition, Patgen prompts interactively for other values. |
| 1638 |
|
| 1639 |
For more information, see ‘Word hy-phen-a-tion by com-put-er’ by |
| 1640 |
Frank Liang (*note References::), and also the ‘patgen.web’ source file. |
| 1641 |
|
| 1642 |
The only options are ‘-help’ and ‘-version’ (*note Common options::). |
| 1643 |
|
| 1644 |
|
| 1645 |
File: web2c.info, Node: Shell escapes, Next: IPC and TeX, Prev: Languages and hyphenation, Up: TeX |
| 1646 |
|
| 1647 |
5.5 Shell escapes |
| 1648 |
================= |
| 1649 |
|
| 1650 |
TeX can execute “shell escapes”, that is, arbitrary shell commands. |
| 1651 |
Although tremendously useful, this also has obvious security |
| 1652 |
implications. Therefore, as of TeX Live 2009, a “restricted” mode for |
| 1653 |
shell escapes is the default mode of operation, which allows executing |
| 1654 |
only certain commands, as specified in the ‘texmf.cnf’ configuration |
| 1655 |
file. |
| 1656 |
|
| 1657 |
• Unrestricted shell escapes are allowed if the option |
| 1658 |
‘--shell-escape’ is specified, or if the environment variable or |
| 1659 |
config file value ‘shell_escape’ is set to ‘t’ or ‘y’ and ‘1’. |
| 1660 |
|
| 1661 |
• Restricted shell escapes are allowed if ‘shell_escape’ is set to |
| 1662 |
‘p’. This is the default. |
| 1663 |
|
| 1664 |
• Shell escapes are completely disabled if ‘--no-shell-escape’ is |
| 1665 |
specified, or if ‘shell_escape’ is set to anything else. |
| 1666 |
|
| 1667 |
When enabled, the TeX construct to execute a system command is |
| 1668 |
‘\write18{SHELL-COMMAND}’; for example: |
| 1669 |
|
| 1670 |
\write18{echo "hello, world"} |
| 1671 |
|
| 1672 |
From TeX's point of view, this is a normal ‘\write’ command, and is |
| 1673 |
therefore subject to the usual TeX expansions. Also, the system call |
| 1674 |
either happens during the ‘\output’ routine or right away, according to |
| 1675 |
the absence or presence of the ‘\immediate’ prefix, as usual for |
| 1676 |
‘\write’. |
| 1677 |
|
| 1678 |
The SHELL-COMMAND string is passed to the command shell (via the C |
| 1679 |
library function ‘system’). The output of SHELL-COMMAND is not diverted |
| 1680 |
anywhere, so it will not appear in the log file, or anywhere but the |
| 1681 |
terminal output. The exit status of the system call is also not |
| 1682 |
available to TeX. |
| 1683 |
|
| 1684 |
In unrestricted mode, the argument is simply passed straight to |
| 1685 |
‘system’ unaltered. |
| 1686 |
|
| 1687 |
In restricted mode, ASCII double quote characters (") should always |
| 1688 |
be used in the argument to ‘\write18’ where quoting of arguments is |
| 1689 |
needed, as in the example above. This is to achieve some measure of |
| 1690 |
system independence. On Unix systems, these are replaced with single |
| 1691 |
quote (') characters to avoid insecure further expansion (from, e.g., |
| 1692 |
`...`). Care is also taken on Windows to avoid additional expansions. |
| 1693 |
Mismatched quotation marks in the command string result in a diagnostic |
| 1694 |
message in the log file, and no execution is performed. |
| 1695 |
|
| 1696 |
After quotation processing, if the first word (delimited by a space |
| 1697 |
or tab) of the command is in the list specified by the |
| 1698 |
‘shell_escape_commands’ configuration value, the command is executed. |
| 1699 |
Otherwise it is not. In any case, a message is written to the log file. |
| 1700 |
|
| 1701 |
The ‘shell_escape_commands’ value is a comma-separated list of words. |
| 1702 |
Whitespace is significant, and typically should not be present. The |
| 1703 |
default definition in ‘texmf.cnf’ looks like this, with more commands |
| 1704 |
included: |
| 1705 |
|
| 1706 |
shell_escape_commands = bibtex,kpsewhich,repstopdf,... |
| 1707 |
|
| 1708 |
pdfTeX and LuaTeX support reading (via ‘\input’ and ‘\openin’) and |
| 1709 |
writing (via ‘\openout’) from pipes if the first character is ‘|’. The |
| 1710 |
following command is then treated exactly the same as the argument to |
| 1711 |
‘\write18’. In these engines, the primitive variable ‘\pdfshellescape’ |
| 1712 |
is set to 0 if shell escapes are disabled, 1 if they are enabled, and 2 |
| 1713 |
if they are enabled with restrictions. |
| 1714 |
|
| 1715 |
The purpose of this feature is to make it possible for TeX documents |
| 1716 |
to perform useful external actions in the common case of an individual |
| 1717 |
user running a known document on his or her own machine. In |
| 1718 |
environments such as CGI scripts or wikis where the input has to be |
| 1719 |
considered untrustworthy, shell escapes should be completely disabled. |
| 1720 |
|
| 1721 |
Programs intended to be called from TeX in restricted should |
| 1722 |
implement the "paranoid" safety measures regarding output files that TeX |
| 1723 |
itself does. *Note (kpathsea)Calling sequence::. |
| 1724 |
|
| 1725 |
|
| 1726 |
File: web2c.info, Node: IPC and TeX, Next: TeX extensions, Prev: Shell escapes, Up: TeX |
| 1727 |
|
| 1728 |
5.6 IPC and TeX |
| 1729 |
=============== |
| 1730 |
|
| 1731 |
(If anyone uses this feature and needs documentation, write |
| 1732 |
<[email protected]>.) |
| 1733 |
|
| 1734 |
This functionality is available only if the ‘--enable-ipc’ option was |
| 1735 |
specified to ‘configure’ during installation of Web2c (*note |
| 1736 |
Installation::). |
| 1737 |
|
| 1738 |
If you define ‘IPC_DEBUG’ before compilation (e.g., with ‘make |
| 1739 |
XCFLAGS=-DIPC_DEBUG’), TeX will print messages to standard error about |
| 1740 |
its socket operations. This may be helpful if you are, well, debugging. |
| 1741 |
|
| 1742 |
|
| 1743 |
File: web2c.info, Node: TeX extensions, Prev: IPC and TeX, Up: TeX |
| 1744 |
|
| 1745 |
5.7 Extended TeX engines |
| 1746 |
======================== |
| 1747 |
|
| 1748 |
The base TeX program has been extended in many ways. |
| 1749 |
|
| 1750 |
There has been a substantial effort to make a set of extended |
| 1751 |
functionality available across all actively-updated engines, so that |
| 1752 |
formats, notably LaTeX, can rely on it. A list of this common extended |
| 1753 |
functionality is in a ‘LaTeX News’ article, |
| 1754 |
<https://www.latex-project.org/news/latex2e-news/ltnews31.pdf>. For |
| 1755 |
engines in TeX Live, the detailed documentation for these primitives is |
| 1756 |
mostly in the pdfTeX manual (<https://pdftex.org>). |
| 1757 |
|
| 1758 |
In addition, each engine (naturally) has its own particular features, |
| 1759 |
described in its own manual. Here's a partial list of the engines. |
| 1760 |
|
| 1761 |
e-TeX |
| 1762 |
Adds many new primitives, including right-to-left typesetting and |
| 1763 |
more registers. Now frozen. More info: |
| 1764 |
<https://ctan.org/pkg/etex>. |
| 1765 |
|
| 1766 |
Aleph |
| 1767 |
This adds Unicode support, right-to-left typesetting, and more, |
| 1768 |
based on the Omega engine, with the e-TeX and other extensions. |
| 1769 |
Aleph is maintained only for serious bug fixes and does not include |
| 1770 |
the common functionality mentioned above. More info: |
| 1771 |
<https://ctan.org/pkg/aleph>, <https://ctan.org/pkg/omega>. |
| 1772 |
|
| 1773 |
pdfTeX |
| 1774 |
Can produce PDF as well as DVI files. It also incorporates the |
| 1775 |
e-TeX extensions, new primitives for hypertext and |
| 1776 |
micro-typography, reading/writing from pipes, and much more. In |
| 1777 |
TeX Live, the command ‘etex’ invokes pdfTeX to make all these |
| 1778 |
additions available with DVI output. Home page: |
| 1779 |
<https://pdftex.org>. |
| 1780 |
|
| 1781 |
LuaTeX |
| 1782 |
Embeds the Lua programming language (<http://lua.org>) and opens up |
| 1783 |
the TeX typesetting engine to control from Lua, starting from the |
| 1784 |
pdfTeX capabilities as a base. Also natively supports UTF-8 input, |
| 1785 |
the OpenType and TrueType font formats, and use of system fonts. |
| 1786 |
Home page: <https://luatex.org>. |
| 1787 |
|
| 1788 |
XeTeX |
| 1789 |
Combines support for Unicode input, the OpenType and TrueType font |
| 1790 |
formats, and use of system fonts with the capabilities of pdfTeX, |
| 1791 |
with the exception of the font expansion part of micro-typography. |
| 1792 |
Home page: <https://tug.org/xetex>. |
| 1793 |
|
| 1794 |
hiTeX |
| 1795 |
Outputs its own HINT format, which is designed for reading |
| 1796 |
technical documents on mobile devices. More info: |
| 1797 |
<https://ctan.org/pkg/hitex>. |
| 1798 |
|
| 1799 |
pTeX |
| 1800 |
upTeX |
| 1801 |
With additional support for Japanese; pTeX was the original engine, |
| 1802 |
and upTeX has native Unicode support and thus is more useful for |
| 1803 |
Chinese and Korean. More info: <https://ctan.org/pkg/ptex>, |
| 1804 |
<https://ctan.org/pkg/uptex>. |
| 1805 |
|
| 1806 |
epTeX |
| 1807 |
eupTeX |
| 1808 |
Further extends pTeX and upTeX with the e-TeX extensions. More |
| 1809 |
info: <https://ctan.org/pkg/eptex>, <https://ctan.org/pkg/euptex>. |
| 1810 |
|
| 1811 |
|
| 1812 |
File: web2c.info, Node: Metafont, Next: MetaPost, Prev: TeX, Up: Top |
| 1813 |
|
| 1814 |
6 Metafont: Creating typeface families |
| 1815 |
************************************** |
| 1816 |
|
| 1817 |
Metafont is a system for producing shapes; it was designed for producing |
| 1818 |
complete typeface families, but it can also produce geometric designs, |
| 1819 |
dingbats, etc. And it has considerable mathematical and |
| 1820 |
equation-solving capabilities which can be useful entirely on their own. |
| 1821 |
|
| 1822 |
Metafont is a batch language, like C or Pascal: you compile a |
| 1823 |
Metafont program into a corresponding font, rather than interactively |
| 1824 |
drawing lines or curves. This approach has both considerable |
| 1825 |
disadvantages (people unfamiliar with conventional programming languages |
| 1826 |
will be unlikely to find it usable) and considerable advantages (you can |
| 1827 |
make your design intentions specific and parameterizable). For a |
| 1828 |
complete description of the Metafont language, see ‘The METAFONTbook’ |
| 1829 |
(*note References::). |
| 1830 |
|
| 1831 |
* Menu: |
| 1832 |
|
| 1833 |
* mf invocation:: Invoking Metafont. |
| 1834 |
* Initial Metafont:: Making bases. |
| 1835 |
* Modes:: Device definitions for Metafont. |
| 1836 |
* Online Metafont graphics:: Seeing MF output online. |
| 1837 |
* gftodvi invocation:: Making proofsheets for fonts. |
| 1838 |
* mft invocation:: Prettyprinting Metafont sources. |
| 1839 |
|
| 1840 |
|
| 1841 |
File: web2c.info, Node: mf invocation, Next: Initial Metafont, Up: Metafont |
| 1842 |
|
| 1843 |
6.1 ‘mf’ invocation |
| 1844 |
=================== |
| 1845 |
|
| 1846 |
Metafont (usually invoked as ‘mf’) reads character definitions specified |
| 1847 |
in the Metafont programming language, and outputs the corresponding |
| 1848 |
font. This section merely describes the options available in the Web2c |
| 1849 |
implementation. For a complete description of the Metafont language, |
| 1850 |
see ‘The Metafontbook’ (*note References::). |
| 1851 |
|
| 1852 |
Metafont processes its command line and determines its memory dump |
| 1853 |
(base) file in a way exactly analogous to MetaPost and TeX (*note tex |
| 1854 |
invocation::, and *note Memory dumps::). Synopses: |
| 1855 |
|
| 1856 |
mf [OPTION]... [MFNAME[.mf]] [MF-COMMANDS] |
| 1857 |
mf [OPTION]... \FIRST-LINE |
| 1858 |
mf [OPTION]... &BASE ARGS |
| 1859 |
|
| 1860 |
Most commonly, a Metafont invocation looks like this: |
| 1861 |
mf '\mode:=MODE; mag:=MAGNIFICATION; input MFNAME' |
| 1862 |
(The single quotes avoid unwanted interpretation by the shell.) |
| 1863 |
|
| 1864 |
Metafont searches the usual places for the main input file MFNAME |
| 1865 |
(*note (kpathsea)Supported file formats::), extending MFNAME with ‘.mf’ |
| 1866 |
if necessary. To see all the relevant paths, set the environment |
| 1867 |
variable ‘KPATHSEA_DEBUG’ to ‘-1’ before running the program. By |
| 1868 |
default, Metafont runs an external program named ‘mktexmf’ to create any |
| 1869 |
nonexistent Metafont source files you input. You can disable this at |
| 1870 |
configure-time or runtime (*note (kpathsea)mktex configuration::). This |
| 1871 |
is mostly for the sake of the EC fonts, which can be generated at any |
| 1872 |
size. |
| 1873 |
|
| 1874 |
Metafont writes the main GF output to the file ‘BASEMFNAME.NNNgf’, |
| 1875 |
where NNN is the font resolution in pixels per inch, and BASEMFNAME is |
| 1876 |
the basename of MFNAME, or ‘mfput’ if no input file was specified. A GF |
| 1877 |
file contains bitmaps of the actual character shapes. Usually GF files |
| 1878 |
are converted immediately to PK files with GFtoPK (*note gftopk |
| 1879 |
invocation::), since PK files contain equivalent information, but are |
| 1880 |
more compact. (Metafont output in GF format rather than PK for only |
| 1881 |
historical reasons.) |
| 1882 |
|
| 1883 |
Metafont also usually writes a metric file in TFM format to |
| 1884 |
‘BASEMFNAME.tfm’. A TFM file contains character dimensions, kerns, and |
| 1885 |
ligatures, and spacing parameters. TeX reads only this .tfm file, not |
| 1886 |
the GF file. |
| 1887 |
|
| 1888 |
The MODE in the example command above is a name referring to a device |
| 1889 |
definition (*note Modes::); for example, ‘localfont’ or ‘ljfour’. These |
| 1890 |
device definitions must generally be precompiled into the base file. If |
| 1891 |
you leave this out, the default is ‘proof’ mode, as stated in ‘The |
| 1892 |
Metafontbook’, in which Metafont outputs at a resolution of 2602dpi; |
| 1893 |
this is usually not what you want. The remedy is simply to assign a |
| 1894 |
different mode--‘localfont’, for example. |
| 1895 |
|
| 1896 |
The MAGNIFICATION assignment in the example command above is a |
| 1897 |
magnification factor; for example, if the device is 600dpi and you |
| 1898 |
specify ‘mag:=2’, Metafont will produce output at 1200dpi. Very often, |
| 1899 |
the MAGNIFICATION is an expression such as ‘magstep(.5)’, corresponding |
| 1900 |
to a TeX "magstep", which are factors of 1.2 * sqrt(2). |
| 1901 |
|
| 1902 |
After running Metafont, you can use the font in a TeX document as |
| 1903 |
usual. For example: |
| 1904 |
\font\myfont = newfont |
| 1905 |
\myfont Now I am typesetting in my new font (minimum hamburgers). |
| 1906 |
|
| 1907 |
The program accepts the following options, as well as the standard |
| 1908 |
‘-help’ and ‘-version’ (*note Common options::): |
| 1909 |
‘-[no]-file-line-error’ |
| 1910 |
‘-fmt=FMTNAME’ |
| 1911 |
‘-halt-on-error’ |
| 1912 |
‘-ini’ |
| 1913 |
‘-interaction=STRING’ |
| 1914 |
‘-jobname=STRING’ |
| 1915 |
‘-kpathsea-debug=NUMBER’ |
| 1916 |
‘-[no]parse-first-line’ |
| 1917 |
‘-output-directory’ |
| 1918 |
‘-progname=STRING’ |
| 1919 |
‘-recorder’ |
| 1920 |
‘-translate-file=TCXFILE’ |
| 1921 |
‘-8bit’ |
| 1922 |
These options are common to TeX, Metafont, and MetaPost. *Note |
| 1923 |
Common options::. |
| 1924 |
|
| 1925 |
‘-mktex=FILETYPE’ |
| 1926 |
‘-no-mktex=FILETYPE’ |
| 1927 |
Turn on or off the ‘mktex’ script associated with FILETYPE. The |
| 1928 |
only value that makes sense for FILETYPE is ‘mf’. |
| 1929 |
|
| 1930 |
|
| 1931 |
File: web2c.info, Node: Initial Metafont, Next: Modes, Prev: mf invocation, Up: Metafont |
| 1932 |
|
| 1933 |
6.2 Initial Metafont |
| 1934 |
==================== |
| 1935 |
|
| 1936 |
‘inimf’ is the "initial" form of Metafont, which does lengthy |
| 1937 |
initializations avoided by the "virgin" (‘vir’) form, so as to be |
| 1938 |
capable of dumping ‘.base’ files (*note Memory dumps::). For a detailed |
| 1939 |
comparison of virgin and initial forms, see *note Initial and virgin::. |
| 1940 |
|
| 1941 |
For a list of options and other information, see *note mf |
| 1942 |
invocation::. |
| 1943 |
|
| 1944 |
The only memory dump file commonly used with Metafont is the default |
| 1945 |
‘plain.base’, also known as ‘mf.base’ (again, *note Memory dumps::). It |
| 1946 |
is created by default during installation, but you can also do so by |
| 1947 |
hand if necessary: |
| 1948 |
mf -ini '\input plain; input modes; dump' |
| 1949 |
(The quotes prevent interpretation of the backslashes from the shell.) |
| 1950 |
Then install the resulting ‘plain.base’ where Metafont will find it, and |
| 1951 |
link ‘mf.base’ to it. |
| 1952 |
|
| 1953 |
For an explanation of the additional ‘modes.mf’ file, see *note |
| 1954 |
Modes::. This file has no counterpart in TeX or MetaPost. |
| 1955 |
|
| 1956 |
In the past, it was sometimes useful to create a base file |
| 1957 |
‘cmmf.base’ (a.k.a. ‘cm.base’), with the Computer Modern macros also |
| 1958 |
included in the base file. Nowadays, however, the additional time |
| 1959 |
required to read ‘cmbase.mf’ is exceedingly small, usually not enough to |
| 1960 |
be worth the administrative hassle of updating the ‘cmmf.base’ file when |
| 1961 |
you install a new version of ‘modes.mf’. People developing a typeface |
| 1962 |
with Metafont may find it worthwhile to create their own base file. |
| 1963 |
|
| 1964 |
|
| 1965 |
File: web2c.info, Node: Modes, Next: Online Metafont graphics, Prev: Initial Metafont, Up: Metafont |
| 1966 |
|
| 1967 |
6.3 Modes: Device definitions for Metafont |
| 1968 |
========================================== |
| 1969 |
|
| 1970 |
Running Metafont and creating Metafont base files requires information |
| 1971 |
that TeX and MetaPost do not: “mode” definitions which specify device |
| 1972 |
characteristics, so Metafont can properly rasterize the shapes. |
| 1973 |
|
| 1974 |
When making a base file, a file containing modes for |
| 1975 |
locally-available devices should be input after ‘plain.mf’. One |
| 1976 |
commonly used file is ‘modes.mf’ (<https://ctan.org/pkg/modes>); it |
| 1977 |
includes all known definitions. |
| 1978 |
|
| 1979 |
If, however, for some reason you have decreased the memory available |
| 1980 |
in your Metafont, you may need to copy ‘modes.mf’ and remove the |
| 1981 |
definitions irrelevant to you (probably most of them) instead of using |
| 1982 |
it directly. (Or, if you're a Metafont hacker, maybe you can suggest a |
| 1983 |
way to redefine ‘mode_def’ and/or ‘mode_setup’; right now, the amount of |
| 1984 |
memory used is approximately four times the total length of the |
| 1985 |
‘mode_def’ names, and that's a lot.) |
| 1986 |
|
| 1987 |
If you have a device not included in ‘modes.mf’, please see comments |
| 1988 |
in that file for how to create the new definition, and please send the |
| 1989 |
definition to <[email protected]> to get it included in the next |
| 1990 |
release of ‘modes.mf’. |
| 1991 |
|
| 1992 |
Usually, when you run Metafont you must supply the name of a mode |
| 1993 |
that was dumped in the base file. But you can also define the mode |
| 1994 |
characteristics dynamically, by invoking Metafont with an assignment to |
| 1995 |
‘smode’ instead of ‘mode’, like this: |
| 1996 |
mf '\smode:="newmode.mf"; mag:=MAGNIFICATION; input MFNAME' |
| 1997 |
This is most useful when you are working on the definition of a new |
| 1998 |
mode. |
| 1999 |
|
| 2000 |
The MAGNIFICATION and MFNAME arguments are explained in *note mf |
| 2001 |
invocation::. In the file ‘newmode.mf’, you should have the following |
| 2002 |
(with no ‘mode_def’ or ‘enddef’), if you are using ‘modes.mf’ |
| 2003 |
conventions: |
| 2004 |
mode_param (pixels_per_inch, DPI); |
| 2005 |
mode_param (blacker, B); |
| 2006 |
mode_param (fillin, F); |
| 2007 |
mode_param (o_correction, O); |
| 2008 |
mode_common_setup_; |
| 2009 |
(Of course, you should use real numbers for DPI, B, F, and O.) |
| 2010 |
|
| 2011 |
For more information on the use of ‘smode’, or if you are not using |
| 2012 |
‘modes.mf’, see page 269 of ‘The Metafontbook’. |
| 2013 |
|
| 2014 |
|
| 2015 |
File: web2c.info, Node: Online Metafont graphics, Next: gftodvi invocation, Prev: Modes, Up: Metafont |
| 2016 |
|
| 2017 |
6.4 Online Metafont graphics |
| 2018 |
============================ |
| 2019 |
|
| 2020 |
The Web2c implementation of Metafont can do online graphics with a |
| 2021 |
number of devices. (See ‘The Metafontbook’ for more information about |
| 2022 |
how to draw on your screen.) The default graphics support is determined |
| 2023 |
at compile time. |
| 2024 |
|
| 2025 |
The two Kpathsea configuration variables ‘screen_width’ and |
| 2026 |
‘screen_depth’ define the width and height of the window used by |
| 2027 |
Metafont. They can be set in the environment or a Kpathsea |
| 2028 |
configuration file (*note (Kpathsea)path sources::). They default to |
| 2029 |
1664 and 1200, respectively. |
| 2030 |
|
| 2031 |
Metafont examines the ‘MFTERM’ environment variable or config file |
| 2032 |
value at runtime, or the ‘TERM’ environment variable if ‘MFTERM’ is not |
| 2033 |
set, to determine the device support to use. Some devices are |
| 2034 |
system-specific and not always available. |
| 2035 |
|
| 2036 |
If ‘MFTERM’ is not set, but the ‘DISPLAY’ environment variable is set |
| 2037 |
(to a valid X server specification like ‘:0’), the Metafont window |
| 2038 |
support for X is used, assuming it was detected and included at compile |
| 2039 |
time. |
| 2040 |
|
| 2041 |
Here is a table of the possibilities, showing the ‘MFTERM’ value and |
| 2042 |
the corresponding ‘configure’ option(s) in parentheses. |
| 2043 |
|
| 2044 |
‘amiga’ |
| 2045 |
(‘--enable-amigawin’) Amiga systems. |
| 2046 |
|
| 2047 |
‘epsf’ |
| 2048 |
(‘--enable-epsfwin’) Pseudo-window server for Encapsulated |
| 2049 |
PostScript (see ‘web2c/window/epsf.c’). This device produces an |
| 2050 |
EPS file containing the graphics which would be displayed online on |
| 2051 |
other devices. The name of the EPS file defaults to metafont.eps |
| 2052 |
but can be changed by setting the MFEPSF environment variable to |
| 2053 |
the new filename. Contributed by Mathias Herberts. |
| 2054 |
|
| 2055 |
‘hp2627’ |
| 2056 |
(‘--enable-hp2627win’) HP2627a color graphics terminals. |
| 2057 |
|
| 2058 |
‘mftalk’ |
| 2059 |
(‘--enable-mftalkwin’) Generic window server (see |
| 2060 |
‘web2c/window/mftalk.c’). |
| 2061 |
|
| 2062 |
‘next’ |
| 2063 |
(‘--enable-nextwin’) NeXT window system. This requires a separate |
| 2064 |
program, called ‘DrawingServant’, available separately. See the |
| 2065 |
‘web2c/window/next.c’. |
| 2066 |
|
| 2067 |
‘regis’ |
| 2068 |
(‘--enable-regiswin’) Regis terminals. |
| 2069 |
|
| 2070 |
‘sun’ |
| 2071 |
(‘--enable-suntoolswin’) The old Suntools (not any flavor of X) |
| 2072 |
window system. (You can get the even older SunWindows ‘gfx’ system |
| 2073 |
with ‘sun-gfx.c’.) |
| 2074 |
|
| 2075 |
‘tek’ |
| 2076 |
(‘--enable-tektronixwin’) Tektronix terminals. |
| 2077 |
|
| 2078 |
‘uniterm’ |
| 2079 |
(‘--enable-unitermwin’) Uniterm, Simon Poole's emulator of a smart |
| 2080 |
Tektronix 4014 terminal. This may work with regular Tektronix |
| 2081 |
terminals as well; it's faster than the driver |
| 2082 |
‘--enable-tektronixwin’ selects. |
| 2083 |
|
| 2084 |
‘win32win’ |
| 2085 |
Microsoft Windows. |
| 2086 |
|
| 2087 |
‘xterm’ |
| 2088 |
‘--with-x’ The X window system (version 11). |
| 2089 |
|
| 2090 |
There are two variants of the X11 support, one that works with the |
| 2091 |
Xt toolkit (‘X11-Xt.c’), and another that works directly with Xlib |
| 2092 |
(‘X11-Xlib.c’). If ‘--with-mf-x-toolkit’ is specified when |
| 2093 |
building Metafont, the Xt version is used, else Xlib. |
| 2094 |
|
| 2095 |
Specify ‘--disable-mf-nowin’ in order not to build a separate |
| 2096 |
non-windows-capable Metafont executable ‘mf-nowin’. |
| 2097 |
|
| 2098 |
You cannot specify any of the usual X options (e.g., ‘-geometry’) |
| 2099 |
on the Metafont command line, but you can specify X resources in |
| 2100 |
your ‘~/.Xdefaults’ or ‘~/.Xresources’ file. The class name is |
| 2101 |
‘Metafont’. If you're using the Xt support, all the usual X |
| 2102 |
toolkit resources are supported. If you're using the Xlib support, |
| 2103 |
only the ‘geometry’ resource is supported. |
| 2104 |
|
| 2105 |
You specify the X display to which Metafont connects in the |
| 2106 |
‘DISPLAY’ environment variable, as usual. |
| 2107 |
|
| 2108 |
Writing support for a new device is straightforward. Aside from |
| 2109 |
defining the basic drawing routines that Metafont uses (see ‘mf.web’), |
| 2110 |
you only have to add another entry to the tables on the last page of |
| 2111 |
‘web2c/lib/texmfmp.c’. Or you can write an independent program and use |
| 2112 |
MFtalk (see ‘web2c/window/mftalk.c’). |
| 2113 |
|
| 2114 |
|
| 2115 |
File: web2c.info, Node: gftodvi invocation, Next: mft invocation, Prev: Online Metafont graphics, Up: Metafont |
| 2116 |
|
| 2117 |
6.5 GFtoDVI: Character proofs of fonts |
| 2118 |
====================================== |
| 2119 |
|
| 2120 |
GFtoDVI makes “proof sheets” from a GF bitmap file as output by, for |
| 2121 |
example, Metafont (*note Metafont::). This is an indispensable aid for |
| 2122 |
font designers or Metafont hackers. Synopsis: |
| 2123 |
|
| 2124 |
gftodvi [OPTION]... GFNAME[gf] |
| 2125 |
|
| 2126 |
The font GFNAME is searched for in the usual places (*note |
| 2127 |
(kpathsea)Glyph lookup::). To see all the relevant paths, set the |
| 2128 |
environment variable ‘KPATHSEA_DEBUG’ to ‘-1’ before running the |
| 2129 |
program. |
| 2130 |
|
| 2131 |
The suffix ‘gf’ is supplied if not already present. This suffix is |
| 2132 |
not an extension, no ‘.’ precedes it; for instance, ‘cmr10.600gf’. |
| 2133 |
|
| 2134 |
The output filename is the basename of GFNAME extended with ‘.dvi’, |
| 2135 |
e.g., ‘gftodvi /wherever/foo.600gf’ creates ‘./foo.dvi’. |
| 2136 |
|
| 2137 |
The characters from GFNAME appear one per page in the DVI output, |
| 2138 |
with labels, titles, and annotations, as specified in Appendix H |
| 2139 |
(Hardcopy Proofs) of ‘The Metafontbook’. |
| 2140 |
|
| 2141 |
GFtoDVI uses several fonts besides GFNAME itself: |
| 2142 |
|
| 2143 |
• “gray font” (default ‘gray’): for the pixels that make up the |
| 2144 |
character. Simply using black is not right, since then labels, key |
| 2145 |
points, and other information could not be shown. |
| 2146 |
|
| 2147 |
• “title font” (default ‘cmr8’): for the header information at the |
| 2148 |
top of each output page. |
| 2149 |
|
| 2150 |
• “label font” (default ‘cmtt10’): for the labels on key points of |
| 2151 |
the figure. |
| 2152 |
|
| 2153 |
• “slant font” (no default): for diagonal lines, which are otherwise |
| 2154 |
simulated using horizontal and vertical rules. |
| 2155 |
|
| 2156 |
To change the default fonts, you must use ‘special’ commands in your |
| 2157 |
Metafont source file, typically via commands like ‘slantfont slantlj4’. |
| 2158 |
There is no default slant font since no one printer is suitable as a |
| 2159 |
default. You can make your own by copying one of the existing files, |
| 2160 |
such as ‘.../fonts/source/public/misc/slantlj4.mf’ and then running ‘mf’ |
| 2161 |
on it. |
| 2162 |
|
| 2163 |
For testing purposes, you may it useful to run ‘mf-nowin rtest’ (hit |
| 2164 |
RETURN when it stops) to get a ‘gf’ file of a thorn glyph. Or use ‘mf’ |
| 2165 |
instead of ‘mf-nowin’ to have the glyph(s) displayed on the screen. |
| 2166 |
After that, ‘gftodvi rtest.2602gf’ should produce ‘rtest.dvi’, which you |
| 2167 |
process as usual. |
| 2168 |
|
| 2169 |
The program accepts the following option, as well as the standard |
| 2170 |
‘-verbose’, ‘-help’, and ‘-version’ (*note Common options::): |
| 2171 |
|
| 2172 |
‘-overflow-label-offset=POINTS’ |
| 2173 |
Typeset the so-called overflow labels, if any, POINTS TeX points |
| 2174 |
from the right edge of the character bounding box. The default is |
| 2175 |
a little over two inches (ten million scaled points, to be |
| 2176 |
precise). Overflow equations are used to locate coordinates when |
| 2177 |
their actual position is too crowded with other information. |
| 2178 |
|
| 2179 |
|
| 2180 |
File: web2c.info, Node: mft invocation, Prev: gftodvi invocation, Up: Metafont |
| 2181 |
|
| 2182 |
6.6 MFT: Prettyprinting Metafont source |
| 2183 |
======================================= |
| 2184 |
|
| 2185 |
MFT translates a Metafont or MetaPost program into a TeX document |
| 2186 |
suitable for typesetting. Synopsis: |
| 2187 |
|
| 2188 |
mft [OPTION]... SOURCENAME[.mf|.mp] |
| 2189 |
|
| 2190 |
MFT searches the usual places for SOURCENAME (*note |
| 2191 |
(kpathsea)Supported file formats::). To see all the relevant paths, set |
| 2192 |
the environment variable ‘KPATHSEA_DEBUG’ to ‘-1’ before running the |
| 2193 |
program. The output goes to the basename of SOURCENAME extended with |
| 2194 |
‘.tex’, e.g., ‘mft /wherever/foo.mf’ creates ‘./foo.tex’. |
| 2195 |
|
| 2196 |
The output uses the TeX macros defined in the file ‘mftmac.tex’ (for |
| 2197 |
Metafont) or ‘mptmac.tex’ (for MetaPost). |
| 2198 |
|
| 2199 |
Line breaks in the input are carried over into the output; moreover, |
| 2200 |
blank spaces at the beginning of a line are converted to quads of |
| 2201 |
indentation in the output. Thus, you have full control over the |
| 2202 |
indentation and line breaks. Each line of input is translated |
| 2203 |
independently of the others. |
| 2204 |
|
| 2205 |
Further control is allowed via comments: |
| 2206 |
• Metafont/MetaPost comments following a single ‘%’ should be valid |
| 2207 |
TeX input. But Metafont/MetaPost source material can be included |
| 2208 |
within vertical bars in a comment; this will be translated by MFT |
| 2209 |
as if it were regular code. For example, a Metafont comment like |
| 2210 |
‘% |x2r| is the tip of the bowl’ will be translated into the TeX ‘% |
| 2211 |
$x_{2r}$ is the ...’, i.e., the ‘x2r’ is treated as an identifier. |
| 2212 |
|
| 2213 |
• ‘%%’ indicates that the remainder of an input line should be copied |
| 2214 |
verbatim to the output. This is typically used to introduce |
| 2215 |
additional TeX material at the beginning or an MFT job, e.g. code |
| 2216 |
to modify the standard layout or the formatting macros defined in |
| 2217 |
‘mftmac.tex’, or to add a line saying ‘%%\bye’ at the end of the |
| 2218 |
job. (MFT doesn't add this automatically in order to allow |
| 2219 |
processing several files produces by MFT in the same TeX job.) |
| 2220 |
|
| 2221 |
• ‘%%% TOKEN1 OTHER-TOKENS’ introduces a change in MFT's formatting |
| 2222 |
rules; all the OTHER-TOKENS will henceforth be translated according |
| 2223 |
to the current conventions for TOKEN1. The tokens must be symbolic |
| 2224 |
(i.e., not numeric or string tokens). For example, the input line |
| 2225 |
%%% addto fill draw filldraw |
| 2226 |
says to format the ‘fill’, ‘draw’, and ‘filldraw’ operations of |
| 2227 |
plain Metafont just like the primitive token ‘addto’, i.e., in |
| 2228 |
boldface type. Without such reformatting commands, MFT would treat |
| 2229 |
‘fill’ like an ordinary tag or variable name. In fact, you need a |
| 2230 |
‘%%%’ command even to get parentheses to act like delimiters. |
| 2231 |
|
| 2232 |
• ‘%%%%’ introduces an MFT comment, i.e., MFT ignores the remainder |
| 2233 |
of such a line. |
| 2234 |
|
| 2235 |
• Five or more ‘%’ signs should not be used. |
| 2236 |
|
| 2237 |
(The above description was based on that in ‘mft.web’, written by |
| 2238 |
Donald Knuth.) |
| 2239 |
|
| 2240 |
The program accepts the following options, as well as the standard |
| 2241 |
‘-help’ and ‘-version’ (*note Common options::): |
| 2242 |
‘-change=CHFILE[.ch]’ |
| 2243 |
Apply the change file CHFILE as with Tangle and Weave (*note |
| 2244 |
WEB::). |
| 2245 |
|
| 2246 |
‘-metapost’ |
| 2247 |
Force interpretation of the input as MetaPost; this is the default |
| 2248 |
of the filename extension is ‘.mp’. |
| 2249 |
|
| 2250 |
‘-style=MFTFILE[.mft]’ |
| 2251 |
Read MFTFILE before anything else; a MFT style file typically |
| 2252 |
contains only MFT directives as described above. The default style |
| 2253 |
file is ‘plain.mft’ (for Metafont) or ‘mplain.mft’ (for MetaPost). |
| 2254 |
MFT files are searched along the ‘MFTINPUTS’ path (*note |
| 2255 |
(kpathsea)Supported file formats::). |
| 2256 |
|
| 2257 |
Other examples of MFT style files are ‘cmbase.mft’, which defines |
| 2258 |
formatting rules for the macros defined in ‘cm.base’, and ‘e.mft’, |
| 2259 |
which was used in the production of Knuth's Volume E, ‘Computer |
| 2260 |
Modern Typefaces’. |
| 2261 |
|
| 2262 |
Using an appropriate MFT style file, it is also possible to |
| 2263 |
configure MFT for typesetting MetaPost sources. However, MFT does |
| 2264 |
not search the usual places for MetaPost input files. |
| 2265 |
|
| 2266 |
If you use eight-bit characters in the input file, they are passed on |
| 2267 |
verbatim to the TeX output file; it is up to you to configure TeX to |
| 2268 |
print these properly. |
| 2269 |
|
| 2270 |
|
| 2271 |
File: web2c.info, Node: MetaPost, Next: BibTeX, Prev: Metafont, Up: Top |
| 2272 |
|
| 2273 |
7 MetaPost: Generating PostScript |
| 2274 |
********************************* |
| 2275 |
|
| 2276 |
MetaPost is a picture-drawing language similar to Metafont (*note |
| 2277 |
Metafont::), but instead of outputting bitmaps in a "font", it outputs |
| 2278 |
PostScript commands. It's primarily intended for creating technical |
| 2279 |
illustrations, but can also be used to create PostScript or OpenType |
| 2280 |
fonts (<https://ctan.org/pkg/metatype1>). |
| 2281 |
|
| 2282 |
MetaPost also provides for arbitrary integration of text and graphics |
| 2283 |
in a natural way, using any typesetter (TeX and Troff are both |
| 2284 |
supported) and a number of other subsidiary programs, described below. |
| 2285 |
|
| 2286 |
* Menu: |
| 2287 |
|
| 2288 |
* mpost invocation:: Invoking MetaPost. |
| 2289 |
* Initial MetaPost:: Making mems. |
| 2290 |
* dvitomp invocation:: DVI-to-MPX translation. |
| 2291 |
|
| 2292 |
|
| 2293 |
File: web2c.info, Node: mpost invocation, Next: Initial MetaPost, Up: MetaPost |
| 2294 |
|
| 2295 |
7.1 ‘mpost’ invocation |
| 2296 |
====================== |
| 2297 |
|
| 2298 |
MetaPost (installed as ‘mpost’) reads a series of pictures specified in |
| 2299 |
the MetaPost programming language, and outputs corresponding PostScript |
| 2300 |
code. This section merely describes the options available in the Web2c |
| 2301 |
implementation. For a complete description of the MetaPost language, |
| 2302 |
see AT&T technical report CSTR-162, generally available in |
| 2303 |
‘TEXMF/doc/metapost/’, where TEXMF is the root of TeX directory |
| 2304 |
structure. The MetaPost home page: <https://tug.org/metapost>. |
| 2305 |
|
| 2306 |
Also, a standard MetaPost package for drawing graphs is documented in |
| 2307 |
AT&T technical report CSTR-164, available as the file ‘mpgraph.ps’, |
| 2308 |
generally stored alongside ‘mpman.ps’. |
| 2309 |
|
| 2310 |
MetaPost processes its command line in a way analogous to Metafont |
| 2311 |
and TeX (*note ‘tex’ invocation: tex invocation.). Synopses: |
| 2312 |
|
| 2313 |
mpost [OPTION]... [MPNAME[.mp]] [MP-COMMANDS] |
| 2314 |
mpost [OPTION]... \FIRST-LINE |
| 2315 |
mpost [OPTION]... &MEM ARGS |
| 2316 |
|
| 2317 |
MetaPost searches the usual places for the main input file MPNAME |
| 2318 |
(*note (kpathsea)Supported file formats::), extending MPNAME with ‘.mp’ |
| 2319 |
if necessary. To see all the relevant paths, set the environment |
| 2320 |
variable ‘KPATHSEA_DEBUG’ to ‘-1’ before running the program. |
| 2321 |
|
| 2322 |
MetaPost writes its PostScript output to a series of files |
| 2323 |
‘BASEMPNAME.NNN’ (or perhaps ‘BASEMPNAME.ps’, very occasionally |
| 2324 |
‘BASEMPNAME.tfm’), where NNN are the figure numbers specified in the |
| 2325 |
input, typically to the ‘beginfig’ macro, and BASEMPNAME is the basename |
| 2326 |
of MPNAME, or ‘mpout’ if no input file was specified. MetaPost uses the |
| 2327 |
‘.ps’ extension when the figure number is out of range, e.g., if you say |
| 2328 |
‘beginfig(-1)’. |
| 2329 |
|
| 2330 |
You can use the output files as figures in a TeX document just as |
| 2331 |
with any other PostScript figures. For example, with this TeX command: |
| 2332 |
\special{psfile="FILENAME"} |
| 2333 |
or by using ‘epsf.tex’ (*note (dvips)EPSF macros::). |
| 2334 |
|
| 2335 |
The MetaPost construct |
| 2336 |
btex ... TEX-INPUT ... etex |
| 2337 |
generates a MetaPost picture expression corresponding to TEX-INPUT. |
| 2338 |
|
| 2339 |
The construct |
| 2340 |
verbatimtex ... TEX-INPUT ... etex |
| 2341 |
simply passes the TEX-INPUT through to TeX. For example, if you are |
| 2342 |
using LaTeX, your MetaPost input file must start with a ‘verbatimtex’ |
| 2343 |
block that gives the necessary ‘\documentclass’ (or ‘\documentstyle’) |
| 2344 |
‘\begin{document}’ command. You will also need to set the environment |
| 2345 |
variable ‘TEX’ to ‘latex’. |
| 2346 |
|
| 2347 |
TEX-INPUT need not be specifically TeX input; it could also be Troff. |
| 2348 |
In that case, you will need the ‘-m pictures’ Troff macro package |
| 2349 |
(unfortunately absent from many Troff implementations), or an equivalent |
| 2350 |
such as the ‘-m pspic’ macros from GNU groff described in grops(1). |
| 2351 |
|
| 2352 |
Naturally, you must use fonts that are supported by the typesetter; |
| 2353 |
specifically, you'll probably want to use standard PostScript fonts with |
| 2354 |
Troff. And only the TeX system understands Computer Modern or other |
| 2355 |
Metafont fonts; you can also use PostScript fonts with TeX, of course. |
| 2356 |
|
| 2357 |
MetaPost-generated PostScript figures which do use Computer Modern |
| 2358 |
fonts for labels cannot be directly previewed or printed. Instead, you |
| 2359 |
must include them in a TeX document and run the resulting DVI file |
| 2360 |
through Dvips to arrange for the downloading of the required fonts |
| 2361 |
(*note (dvips)Fonts in figures::). To help with this, the MetaPost |
| 2362 |
distribution provides a small TeX file ‘mproof.tex’ which is typically |
| 2363 |
called as: |
| 2364 |
tex mproof MP-OUTPUT-FILES... ; dvips mproof -o |
| 2365 |
The resulting file ‘mproof.ps’ can then be printed or previewed. |
| 2366 |
|
| 2367 |
To generate EPSF files, set the internal MetaPost variable |
| 2368 |
‘prologues’ positive. To make the output files self-contained, use only |
| 2369 |
standard PostScript fonts. MetaPost reads the same ‘psfonts.map’ file |
| 2370 |
as Dvips, to determine PostScript fonts that need to be downloaded |
| 2371 |
(*note (dvips)psfonts.map::). |
| 2372 |
|
| 2373 |
It is possible for pdfTeX to read MetaPost output directly; this is |
| 2374 |
in contrast to general EPSF files, which have to be converted for use |
| 2375 |
with PDF output. The easiest way is to name the MetaPost output files |
| 2376 |
with the ‘.mps’ extension. Then the LaTeX ‘\includegraphics’ command, |
| 2377 |
for example, will be able to read them, even when outputting PDF. |
| 2378 |
|
| 2379 |
MetaPost can write output files, via the ‘write’ primitive; this |
| 2380 |
opens a security hole. *Note tex invocation::. |
| 2381 |
|
| 2382 |
The program accepts the following options, as well as the standard |
| 2383 |
‘-help’ and ‘-version’ (*note Common options::): |
| 2384 |
‘-[no]-file-line-error’ |
| 2385 |
‘-halt-on-error’ |
| 2386 |
‘-ini’ |
| 2387 |
‘-interaction=STRING’ |
| 2388 |
‘-jobname=STRING’ |
| 2389 |
‘-kpathsea-debug=NUMBER’ |
| 2390 |
‘-[no]parse-first-line’ |
| 2391 |
‘-output-directory’ |
| 2392 |
‘-progname=STRING’ |
| 2393 |
‘-recorder’ |
| 2394 |
‘-translate-file=TCXFILE’ |
| 2395 |
‘-8bit’ |
| 2396 |
These options are common to TeX, Metafont, and MetaPost. *Note |
| 2397 |
Common options::. |
| 2398 |
|
| 2399 |
‘-debug’ |
| 2400 |
Print debugging information and leave temporary files in place. |
| 2401 |
|
| 2402 |
‘-mem=MPFILE’ |
| 2403 |
Preload MPFILE instead of via the program name of ‘%&’ line. This |
| 2404 |
is a MetaPost source file; MetaPost no longer has binary mem files. |
| 2405 |
|
| 2406 |
‘-numbersystem=STRING’ |
| 2407 |
Set number system mode where STRING is one of: ‘scaled double |
| 2408 |
binary interval decimal’. |
| 2409 |
|
| 2410 |
‘-restricted’ |
| 2411 |
Be secure: disable the ‘tex’, ‘makempx’ and editor commands. |
| 2412 |
|
| 2413 |
‘-s INTERNAL=VALUE’ |
| 2414 |
Set INTERNAL to VALUE, a string or integer. |
| 2415 |
|
| 2416 |
‘-T’ |
| 2417 |
‘-troff’ |
| 2418 |
Set the ‘prologues’ internal variable to ‘1’. |
| 2419 |
|
| 2420 |
‘-tex=TEXPROGRAM’ |
| 2421 |
When this option is given, the program TEXPROGRAM is used to |
| 2422 |
typeset the labels. |
| 2423 |
|
| 2424 |
|
| 2425 |
File: web2c.info, Node: Initial MetaPost, Next: dvitomp invocation, Prev: mpost invocation, Up: MetaPost |
| 2426 |
|
| 2427 |
7.2 Initial MetaPost |
| 2428 |
==================== |
| 2429 |
|
| 2430 |
As of MetaPost 1.504 (TeX Live 2011), MetaPost no longer dumps ‘.mem’ |
| 2431 |
files (*note Memory dumps::) and does not distinguish virgin and initial |
| 2432 |
forms (*note Initial and virgin::). Instead, the "initial" file name is |
| 2433 |
read in its source form--that is, ‘mpost.mp’ when the program is invoked |
| 2434 |
as ‘mpost’. This is considered to be "preloading" the source. |
| 2435 |
|
| 2436 |
For a list of options and other information, see *note mpost |
| 2437 |
invocation::. |
| 2438 |
|
| 2439 |
MetaPost provides a format with all the features of plain Metafont, |
| 2440 |
called ‘mfplain’. You can use that in the same way; just run ‘mfplain’ |
| 2441 |
instead of ‘mpost’. This lets you directly process Metafont source |
| 2442 |
files with MetaPost, producing character proofs (one file for each |
| 2443 |
character) similar to those produced with Metafont in proof mode and |
| 2444 |
GFtoDVI (*note gftodvi invocation::). |
| 2445 |
|
| 2446 |
|
| 2447 |
File: web2c.info, Node: dvitomp invocation, Prev: Initial MetaPost, Up: MetaPost |
| 2448 |
|
| 2449 |
7.3 DVItoMP: DVI to MPX conversion |
| 2450 |
================================== |
| 2451 |
|
| 2452 |
DVItoMP converts DVI files into low-level MetaPost commands in a |
| 2453 |
so-called MPX file. Synopsis: |
| 2454 |
|
| 2455 |
dvitomp DVIFILE[.dvi] [MPXFILE[.mpx]] |
| 2456 |
|
| 2457 |
If MPXFILE is not specified, the output goes to the basename of DVIFILE |
| 2458 |
extended with ‘.mpx’, e.g., ‘dvitomp /wherever/foo.dvi’ creates |
| 2459 |
‘./foo.mpx’. |
| 2460 |
|
| 2461 |
DVItoMP supports Dvips-style color specials, such as ‘color push |
| 2462 |
NAME’ and ‘color pop’, outputting them as ‘withcolor’ MetaPost commands. |
| 2463 |
|
| 2464 |
The only options are ‘-help’ and ‘-version’ (*note Common options::). |
| 2465 |
|
| 2466 |
|
| 2467 |
File: web2c.info, Node: BibTeX, Next: WEB, Prev: MetaPost, Up: Top |
| 2468 |
|
| 2469 |
8 BibTeX: Bibliographies |
| 2470 |
************************ |
| 2471 |
|
| 2472 |
BibTeX automates much of the job of typesetting bibliographies, and |
| 2473 |
makes bibliography entries reusable in many different contexts. |
| 2474 |
|
| 2475 |
* Menu: |
| 2476 |
|
| 2477 |
* bibtex invocation:: |
| 2478 |
* Basic BibTeX style files:: The standard and semi-standard styles. |
| 2479 |
|
| 2480 |
|
| 2481 |
File: web2c.info, Node: bibtex invocation, Next: Basic BibTeX style files, Up: BibTeX |
| 2482 |
|
| 2483 |
8.1 BibTeX invocation |
| 2484 |
===================== |
| 2485 |
|
| 2486 |
BibTeX creates a printable bibliography (‘.bbl’) file from references in |
| 2487 |
a ‘.aux’ file, generally written by TeX or LaTeX. The ‘.bbl’ file is |
| 2488 |
then incorporated on a subsequent run. The basic bibliographic |
| 2489 |
information comes from ‘.bib’ files, and a BibTeX style (‘.bst’) file |
| 2490 |
controls the precise contents of the ‘.bbl’ file. Synopsis: |
| 2491 |
|
| 2492 |
bibtex [OPTION]... AUXFILE[.aux] |
| 2493 |
|
| 2494 |
The output goes to the basename of AUXFILE extended with ‘.bbl’; for |
| 2495 |
example, ‘bibtex /wherever/foo.aux’ creates ‘./foo.bbl’. BibTeX also |
| 2496 |
writes a log file to the basename of AUXFILE extended with ‘.blg’. |
| 2497 |
|
| 2498 |
The names of the ‘.bib’ and ‘.bst’ files are specified in the ‘.aux’ |
| 2499 |
file as well, via the ‘\bibliography’ and ‘\bibliographystyle’ (La)TeX |
| 2500 |
macros. BibTeX searches for ‘.bib’ files using the ‘BIBINPUTS’ and |
| 2501 |
‘TEXBIB’ paths, and for ‘.bst’ files using ‘BSTINPUTS’ (*note |
| 2502 |
(kpathsea)Supported file formats::). It does no path searching for |
| 2503 |
‘.aux’ files. |
| 2504 |
|
| 2505 |
The program accepts the following options, as well as the standard |
| 2506 |
‘-help’ and ‘-version’ (*note Common options::): |
| 2507 |
‘-terse’ |
| 2508 |
Suppress the program banner and progress reports normally output. |
| 2509 |
|
| 2510 |
‘-min-crossrefs=N’ |
| 2511 |
If at least N (2 by default) bibliography entries refer to another |
| 2512 |
entry E via their ‘crossref’ field, include E in the .bbl file, |
| 2513 |
even if it was not explicitly referenced in the .aux file. For |
| 2514 |
example, E might be a conference proceedings as a whole, with the |
| 2515 |
cross-referencing entries being individual articles published in |
| 2516 |
the proceedings. |
| 2517 |
|
| 2518 |
If you want to avoid these automatic inclusions altogether, make N |
| 2519 |
a sufficiently large number, and be sure to remove any previous |
| 2520 |
.aux and .bbl files. Otherwise the option may appear to have no |
| 2521 |
effect, since BibTeX will have added the citation for E to the |
| 2522 |
.aux, and nothing will remove it. |
| 2523 |
|
| 2524 |
See also: |
| 2525 |
‘btxdoc.tex’ |
| 2526 |
Basic LaTeXable documentation for general BibTeX users. |
| 2527 |
|
| 2528 |
‘btxhak.tex’ |
| 2529 |
LaTeXable documentation for style designers. |
| 2530 |
|
| 2531 |
‘btxdoc.bib’ |
| 2532 |
BibTeX database file for the two above documents. |
| 2533 |
|
| 2534 |
‘xampl.bib’ |
| 2535 |
Example database file with all the standard entry types. |
| 2536 |
|
| 2537 |
‘<ftp://ftp.math.utah.edu/pub/tex/bib/>’ |
| 2538 |
A very large ‘.bib’ and ‘.bst’ collection, including references for |
| 2539 |
all the standard TeX books and a complete bibliography for TUGboat. |
| 2540 |
|
| 2541 |
|
| 2542 |
File: web2c.info, Node: Basic BibTeX style files, Prev: bibtex invocation, Up: BibTeX |
| 2543 |
|
| 2544 |
8.2 Basic BibTeX style files |
| 2545 |
============================ |
| 2546 |
|
| 2547 |
Here are descriptions of the four standard and four semi-standard basic |
| 2548 |
BibTeX styles. ‘CTAN:/biblio/bibtex’ contains these and many more (for |
| 2549 |
CTAN info, *note (kpathsea)unixtex.ftp::). |
| 2550 |
|
| 2551 |
‘plain’ |
| 2552 |
Sorts entries alphabetically, with numeric labels. Generally |
| 2553 |
formatted according to van Leunen's ‘A Handbook for Scholars’. The |
| 2554 |
other style files listed here are based on ‘plain’. |
| 2555 |
|
| 2556 |
‘abbrv’ |
| 2557 |
First names, month names, and journal names are abbreviated. |
| 2558 |
|
| 2559 |
‘acm’ |
| 2560 |
Names are printed in small caps. |
| 2561 |
|
| 2562 |
‘alpha’ |
| 2563 |
Alphanumeric labels, e.g., ‘Knu66’. |
| 2564 |
|
| 2565 |
‘apalike’ |
| 2566 |
No labels at all; instead, the year appears in parentheses after |
| 2567 |
the author. Use this in conjunction with ‘apalike.tex’ (plain TeX) |
| 2568 |
or ‘apalike.sty’ (LaTeX), which also changes the citations in the |
| 2569 |
text to be ‘(AUTHOR, YEAR)’. |
| 2570 |
|
| 2571 |
‘ieeetr’ |
| 2572 |
Numeric labels, entries in citation order, IEEE abbreviations, |
| 2573 |
article titles in quotes. |
| 2574 |
|
| 2575 |
‘siam’ |
| 2576 |
Numeric labels, alphabetic order, ‘Math. Reviews’ abbreviations, |
| 2577 |
names in small caps. |
| 2578 |
|
| 2579 |
‘unsrt’ |
| 2580 |
Lists entries in citation order, i.e., unsorted. |
| 2581 |
|
| 2582 |
‘btxbst.doc’ |
| 2583 |
The template file and documentation for the standard styles. |
| 2584 |
|
| 2585 |
|
| 2586 |
File: web2c.info, Node: WEB, Next: DVI utilities, Prev: BibTeX, Up: Top |
| 2587 |
|
| 2588 |
9 WEB: Literate programming |
| 2589 |
*************************** |
| 2590 |
|
| 2591 |
“WEB” languages allow you to write a single source file that can produce |
| 2592 |
both a compilable program and a well-formatted document describing the |
| 2593 |
program in as much detail as you wish to prepare. Writing in this kind |
| 2594 |
of dual-purpose language is called “literate programming”. (The Usenet |
| 2595 |
newsgroup ‘comp.programming.literate’ is devoted to this subject.) |
| 2596 |
|
| 2597 |
WEB-like languages have been implemented with many pairs of base |
| 2598 |
languages: Cweb provides C and Troff (*note References::); CWEB provides |
| 2599 |
C and TeX (‘CTAN:/web/c_cpp/cweb’); Spiderweb provides C, C++, Awk, Ada, |
| 2600 |
many others, and TeX (‘CTAN:/web/spiderweb’); and, of course, the |
| 2601 |
original WEB provides Pascal and TeX, the implementation languages for |
| 2602 |
the original TeX, Metafont, MetaPost, and related programs to come from |
| 2603 |
the TeX project at Stanford. |
| 2604 |
|
| 2605 |
Knuth's original WEB language is documented in the file ‘webman.tex’, |
| 2606 |
available as a formatted pdf in the ‘knuth-pdf’ page |
| 2607 |
(<https://ctan.org/pkg/knuth-pdf>). |
| 2608 |
|
| 2609 |
* Menu: |
| 2610 |
|
| 2611 |
* tangle invocation:: |
| 2612 |
* weave invocation:: |
| 2613 |
* pooltype invocation:: |
| 2614 |
|
| 2615 |
|
| 2616 |
File: web2c.info, Node: tangle invocation, Next: weave invocation, Up: WEB |
| 2617 |
|
| 2618 |
9.1 Tangle: Translate WEB to Pascal |
| 2619 |
=================================== |
| 2620 |
|
| 2621 |
Tangle creates a compilable Pascal program from a WEB source file (*note |
| 2622 |
WEB::). Synopsis: |
| 2623 |
|
| 2624 |
tangle [OPTION]... WEBFILE[.web] [CHANGEFILE[.ch]] |
| 2625 |
|
| 2626 |
The Pascal output is written to the basename of WEBFILE extended with |
| 2627 |
‘.p’; for example, ‘tangle /wherever/foo.web’ creates ‘./foo.p’. Tangle |
| 2628 |
applies CHANGEFILE to WEBFILE before writing the output; by default, |
| 2629 |
there is no change file. |
| 2630 |
|
| 2631 |
If the program makes use of the WEB string facility, Tangle writes |
| 2632 |
the string pool to the basename of WEBFILE extended with ‘.pool’. |
| 2633 |
|
| 2634 |
The Pascal output is packed into lines of 72 characters or less, with |
| 2635 |
the only concession to readability being the termination of lines at |
| 2636 |
semicolons when this can be done conveniently. |
| 2637 |
|
| 2638 |
The program accepts the following options, as well as the standard |
| 2639 |
‘--help’ and ‘--version’ (*note Common options::): |
| 2640 |
|
| 2641 |
‘-length=NUMBER’ |
| 2642 |
The number of characters that are considered significant in an |
| 2643 |
identifier. Whether underline characters are counted depends on |
| 2644 |
the ‘-underline’ option. The default value is 32, the original |
| 2645 |
tangle used 7, but this proved too restrictive for use by Web2c. |
| 2646 |
|
| 2647 |
‘-lowercase’ |
| 2648 |
‘-mixedcase’ |
| 2649 |
‘-uppercase’ |
| 2650 |
These options specify the case of identifiers in the output of |
| 2651 |
tangle. If ‘-uppercase’ (‘-lowercase’) is specified, tangle will |
| 2652 |
convert all identifiers to uppercase (lowercase). The default is |
| 2653 |
‘-mixedcase’, which specifies that the case will not be changed. |
| 2654 |
|
| 2655 |
‘-underline’ |
| 2656 |
When this option is given, tangle does not strip underline |
| 2657 |
characters from identifiers. |
| 2658 |
|
| 2659 |
‘-loose’ |
| 2660 |
‘-strict’ |
| 2661 |
These options specify how strict tangle must be when checking |
| 2662 |
identifiers for equality. The default is ‘-loose’, which means |
| 2663 |
that tangle will follow the rules set by the case-smashing and |
| 2664 |
underline options above. If ‘-strict’ is set, then identifiers |
| 2665 |
will always be stripped of underlines and converted to uppercase |
| 2666 |
before checking whether they collide. |
| 2667 |
|
| 2668 |
|
| 2669 |
File: web2c.info, Node: weave invocation, Next: pooltype invocation, Prev: tangle invocation, Up: WEB |
| 2670 |
|
| 2671 |
9.2 Weave: Translate WEB to TeX |
| 2672 |
=============================== |
| 2673 |
|
| 2674 |
Weave creates a TeX document from a WEB source file (*note WEB::), |
| 2675 |
assuming various macros defined in ‘webmac.tex’. It takes care of |
| 2676 |
typographic details such as page layout, indentation, and italicizing |
| 2677 |
identifiers. It also automatically gathers and outputs extensive |
| 2678 |
cross-reference information. Synopsis: |
| 2679 |
|
| 2680 |
weave [OPTION]... WEBFILE[.web] [CHANGEFILE[.ch]] |
| 2681 |
|
| 2682 |
The output is to the basename of WEBFILE extended with ‘.tex’; for |
| 2683 |
example, ‘weave /wherever/foo.web’ creates ‘./foo.tex’. Weave applies |
| 2684 |
CHANGEFILE to WEBFILE before writing the output; by default, there is no |
| 2685 |
change file. |
| 2686 |
|
| 2687 |
The Web2c version of Weave accepts 8-bit characters as themselves. |
| 2688 |
This can cause trouble with various internal WEB control codes, and |
| 2689 |
should not be relied on. |
| 2690 |
|
| 2691 |
The program accepts the following option, as well as the standard |
| 2692 |
‘-verbose’, ‘-help’ and ‘-version’ (*note Common options::): |
| 2693 |
‘-x’ |
| 2694 |
Omit the cross-reference information: the index, the list of WEB |
| 2695 |
module names, and the table of contents (an empty ‘CONTENTS.tex’ |
| 2696 |
file will still be written when the Weave output file is processed |
| 2697 |
by TeX using the default ‘webmac.tex’, though). |
| 2698 |
|
| 2699 |
Conventionally, WEB programmers should define the TeX ‘\title’ macro |
| 2700 |
at the beginning of the source file. Also, to get output of only |
| 2701 |
changed modules, one can say ‘\let\maybe=\iffalse’ (usually as the first |
| 2702 |
change in the change file). |
| 2703 |
|
| 2704 |
|
| 2705 |
File: web2c.info, Node: pooltype invocation, Prev: weave invocation, Up: WEB |
| 2706 |
|
| 2707 |
9.3 Pooltype: Display WEB pool files |
| 2708 |
==================================== |
| 2709 |
|
| 2710 |
Pooltype shows the so-called “string number” of each string in a WEB |
| 2711 |
pool file (*note WEB::), as output by Tangle (*note tangle |
| 2712 |
invocation::), including the first 256 strings corresponding to the |
| 2713 |
possible input characters. Pooltype primarily serves as an example of |
| 2714 |
WEB conventions to implementors of the TeX system. Synopsis: |
| 2715 |
|
| 2716 |
pooltype [OPTION]... POOLFILE[.pool] |
| 2717 |
|
| 2718 |
No path searching is done for POOLFILE. Output is to standard output. |
| 2719 |
|
| 2720 |
The only options are ‘--help’ and ‘--version’ (*note Common |
| 2721 |
options::). |
| 2722 |
|
| 2723 |
As an example of the output, here is the (edited) output for |
| 2724 |
‘tex.pool’: |
| 2725 |
0: "^^@" |
| 2726 |
1: "^^A" |
| 2727 |
... |
| 2728 |
255: "^^ff" |
| 2729 |
256: "pool size" |
| 2730 |
... |
| 2731 |
1314: "Using character substitution: " |
| 2732 |
(23617 characters in all.) |
| 2733 |
|
| 2734 |
In Metafont and MetaPost, the first 256 characters are represented as |
| 2735 |
single bytes (i.e., themselves), not in the ‘^^’ notation. Thus, |
| 2736 |
Pooltype shows the results after conversion for output. |
| 2737 |
|
| 2738 |
|
| 2739 |
File: web2c.info, Node: DVI utilities, Next: Font utilities, Prev: WEB, Up: Top |
| 2740 |
|
| 2741 |
10 DVI utilities |
| 2742 |
**************** |
| 2743 |
|
| 2744 |
TeX outputs a file in “DVI” (DeVice Independent) format as a compact |
| 2745 |
representation of the original document. DVI files can be translated to |
| 2746 |
meet the requirements of a real physical device, such as PostScript |
| 2747 |
printers (*note Introduction: (dvips)Top.), PCL printers (see dvilj(1)), |
| 2748 |
and X displays (see xdvi(1)). In fact, DVI translators are available |
| 2749 |
for virtually all common devices: see ‘CTAN:/dviware’ (for CTAN info, |
| 2750 |
*note (kpathsea)unixtex.ftp::). |
| 2751 |
|
| 2752 |
For the precise definition of the DVI file format, see (for example) |
| 2753 |
the source file ‘web2c/dvitype.web’. |
| 2754 |
|
| 2755 |
The DVI-processing programs in the Web2c distribution are not device |
| 2756 |
drivers; they perform generic utility functions. |
| 2757 |
|
| 2758 |
* Menu: |
| 2759 |
|
| 2760 |
* dvicopy invocation:: Expand virtual fonts. |
| 2761 |
* dvitype invocation:: DVI to human-readable text. |
| 2762 |
|
| 2763 |
|
| 2764 |
File: web2c.info, Node: dvicopy invocation, Next: dvitype invocation, Up: DVI utilities |
| 2765 |
|
| 2766 |
10.1 DVIcopy: Canonicalize virtual font references |
| 2767 |
================================================== |
| 2768 |
|
| 2769 |
DVIcopy reads a DVI file, expands any references to virtual fonts (*note |
| 2770 |
(dvips)Virtual fonts::) to base fonts, and writes the resulting DVI |
| 2771 |
file. Thus you can use virtual fonts even if your DVI processor does |
| 2772 |
not support them, by passing the documents through DVIcopy first. |
| 2773 |
Synopsis: |
| 2774 |
|
| 2775 |
dvicopy [OPTION]... [INDVI[.dvi] [OUTDVI[.dvi]]] |
| 2776 |
|
| 2777 |
DVIcopy reads standard input if INDVI is not specified, and writes |
| 2778 |
standard output if OUTDVI is not specified. |
| 2779 |
|
| 2780 |
The program accepts the following options, as well as the standard |
| 2781 |
‘-help’ and ‘-version’ (*note Common options::): |
| 2782 |
‘-magnification=INTEGER’ |
| 2783 |
Override existing magnification in INDVI with INTEGER; 1000 |
| 2784 |
specifies no magnification. This is equivalent to setting TeX's |
| 2785 |
‘\mag’ parameter. |
| 2786 |
|
| 2787 |
‘-max-pages=N’ |
| 2788 |
Process N pages; default is one million. |
| 2789 |
|
| 2790 |
‘-page-start=PAGE-SPEC’ |
| 2791 |
Start at the first page matching PAGE-SPEC, which is one or more |
| 2792 |
(signed) integers separated by periods, corresponding to TeX's |
| 2793 |
‘\count0...9’ parameters at ‘\shipout’ time; ‘*’ matches anything. |
| 2794 |
Examples: ‘3’, ‘1.*.-4’. |
| 2795 |
|
| 2796 |
|
| 2797 |
File: web2c.info, Node: dvitype invocation, Prev: dvicopy invocation, Up: DVI utilities |
| 2798 |
|
| 2799 |
10.2 DVItype: Plain text transliteration of DVI files |
| 2800 |
===================================================== |
| 2801 |
|
| 2802 |
DVItype translates a DeVice Independent (DVI) file (as output by TeX, |
| 2803 |
for example) to a plain text file that humans can read. It also serves |
| 2804 |
as a DVI-validating program, i.e., if DVItype can read a file, it's |
| 2805 |
correct. Synopsis: |
| 2806 |
|
| 2807 |
dvitype [OPTION]... DVIFILE[.dvi] |
| 2808 |
|
| 2809 |
DVItype does not read any bitmap files, but it does read TFM files for |
| 2810 |
fonts referenced in DVIFILE. The usual places are searched (*note |
| 2811 |
(kpathsea)Supported file formats::). To see all the relevant paths, set |
| 2812 |
the environment variable ‘KPATHSEA_DEBUG’ to ‘-1’ before running the |
| 2813 |
program. |
| 2814 |
|
| 2815 |
Output goes to standard output. |
| 2816 |
|
| 2817 |
The program accepts the following options, as well as the standard |
| 2818 |
‘-help’ and ‘-version’ (*note Common options::): |
| 2819 |
‘-dpi=REAL’ |
| 2820 |
Do pixel movement calculations at REAL pixels per inch; default |
| 2821 |
300.0. |
| 2822 |
|
| 2823 |
‘-magnification=INTEGER’ |
| 2824 |
Override existing magnification in INDVI with INTEGER; 1000 |
| 2825 |
specifies no magnification. This is equivalent to setting TeX's |
| 2826 |
‘\mag’ parameter. |
| 2827 |
|
| 2828 |
‘-max-pages=N’ |
| 2829 |
Process N pages; default is one million. |
| 2830 |
|
| 2831 |
‘-output-level=N’ |
| 2832 |
Verbosity level of output, from 0 to 4 (default 4): |
| 2833 |
• 0: Global document information only. |
| 2834 |
• 1: Most DVI commands included, and typeset characters |
| 2835 |
summarized. |
| 2836 |
• 2: Character and movement commands explicitly included. |
| 2837 |
• 3: DVI stack and current position calculations included. |
| 2838 |
• 4: Same information as level 3, but DVItype does random |
| 2839 |
positioning in the file, reading the DVI postamble first. |
| 2840 |
|
| 2841 |
‘-page-start=PAGE-SPEC’ |
| 2842 |
Start at the first page matching PAGE-SPEC, which is one or more |
| 2843 |
(signed) integers separated by periods, corresponding to TeX's |
| 2844 |
‘\count0...9’ parameters at ‘\shipout’ time; ‘*’ matches anything. |
| 2845 |
Examples: ‘1’, ‘5.*.-9’. |
| 2846 |
|
| 2847 |
‘-show-opcodes’ |
| 2848 |
Show numeric opcode values (in decimal) for DVI commands, in braces |
| 2849 |
after the command name. This can help in debugging DVI utilities. |
| 2850 |
We use decimal because in the DVI format documentation (in |
| 2851 |
‘dvitype.web’, among others) the opcodes are shown in decimal. |
| 2852 |
|
| 2853 |
* Menu: |
| 2854 |
|
| 2855 |
* dvitype output example:: |
| 2856 |
|
| 2857 |
|
| 2858 |
File: web2c.info, Node: dvitype output example, Up: dvitype invocation |
| 2859 |
|
| 2860 |
10.2.1 DVItype output example |
| 2861 |
----------------------------- |
| 2862 |
|
| 2863 |
As an example of the output from DVItype (see section above), here is |
| 2864 |
its (abridged) translation of the ‘story.dvi’ resulting from running the |
| 2865 |
example in ‘The TeXbook’, with ‘-output-level=4’ and ‘-show-opcodes’ on. |
| 2866 |
|
| 2867 |
... |
| 2868 |
Options selected: |
| 2869 |
Starting page = * |
| 2870 |
Maximum number of pages = 1000000 |
| 2871 |
Output level = 4 (the works) |
| 2872 |
Resolution = 300.00000000 pixels per inch |
| 2873 |
numerator/denominator=25400000/473628672 |
| 2874 |
magnification=1000; 0.00006334 pixels per DVI unit |
| 2875 |
' TeX output 1992.05.17:0844' |
| 2876 |
Postamble starts at byte 564. |
| 2877 |
maxv=43725786, maxh=30785863, maxstackdepth=3, totalpages=1 |
| 2878 |
Font 33: cmsl10---loaded at size 655360 DVI units |
| 2879 |
Font 23: cmbx10---loaded at size 655360 DVI units |
| 2880 |
Font 0: cmr10---loaded at size 655360 DVI units |
| 2881 |
|
| 2882 |
42: beginning of page 1 |
| 2883 |
87: push {141} |
| 2884 |
level 0:(h=0,v=0,w=0,x=0,y=0,z=0,hh=0,vv=0) |
| 2885 |
88: down3 -917504 {159} v:=0-917504=-917504, vv:=-58 |
| 2886 |
92: pop {142} |
| 2887 |
... |
| 2888 |
104: putrule {137} height 26214, width 30785863 (2x1950 pixels) |
| 2889 |
113: down3 5185936 {159} v:=655360+5185936=5841296, vv:=370 |
| 2890 |
117: push {141} |
| 2891 |
level 1:(h=0,v=5841296,w=0,x=0,y=0,z=0,hh=0,vv=370) |
| 2892 |
118: right4 12265425 {146} h:=0+12265425=12265425, hh:=777 |
| 2893 |
[ ] |
| 2894 |
123: fntdef1 23 {243}: cmbx10 |
| 2895 |
145: fntnum23 {194} current font is cmbx10 |
| 2896 |
146: setchar65 h:=12265425+569796=12835221, hh:=813 |
| 2897 |
147: w3 251220 {150} h:=12835221+251220=13086441, hh:=829 |
| 2898 |
151: setchar83 h:=13086441+418700=13505141, hh:=856 |
| 2899 |
... |
| 2900 |
164: setchar82 h:=17448202+565245=18013447, hh:=1142 |
| 2901 |
165: x0 -62805 {152} h:=18013447-62805=17950642, hh:=1138 |
| 2902 |
166: setchar89 h:=17950642+569796=18520438, hh:=1174 |
| 2903 |
[A SHORT STORY] |
| 2904 |
167: pop {142} |
| 2905 |
level 1:(h=0,v=5841296,w=0,x=0,y=0,z=0,hh=0,vv=370) |
| 2906 |
... |
| 2907 |
550: pop {142} |
| 2908 |
level 0:(h=0,v=42152922,w=0,x=0,y=0,z=0,hh=0,vv=2670) |
| 2909 |
551: down3 1572864 {159} v:=42152922+1572864=43725786, vv:=2770 |
| 2910 |
555: push {141} |
| 2911 |
level 0:(h=0,v=43725786,w=0,x=0,y=0,z=0,hh=0,vv=2770) |
| 2912 |
556: right4 15229091 {146} h:=0+15229091=15229091, hh:=965 |
| 2913 |
561: setchar49 h:=15229091+327681=15556772, hh:=986 |
| 2914 |
[ 1] |
| 2915 |
562: pop {142} |
| 2916 |
level 0:(h=0,v=43725786,w=0,x=0,y=0,z=0,hh=0,vv=2770) |
| 2917 |
563: eop {140} |
| 2918 |
|
| 2919 |
Explanation: |
| 2920 |
|
| 2921 |
• The DVItype options are recorded at the beginning, followed by |
| 2922 |
global information about the document, including fonts used. |
| 2923 |
|
| 2924 |
• Each DVI command is preceded by its byte position in the file |
| 2925 |
(‘42:’, ‘87:’, ...), and (because of the ‘-show-opcodes’) followed |
| 2926 |
by its decimal opcode value in braces (‘{141}’, ‘{142}’, ...). |
| 2927 |
|
| 2928 |
• The ‘level’ lines record information about the DVI stack; ‘h’ and |
| 2929 |
‘v’ define the current position in DVI units, while ‘hh’ and ‘vv’ |
| 2930 |
are the same in pixels. |
| 2931 |
|
| 2932 |
• Text sequences are summarized in brackets, as in ‘[A SHORT STORY]’ |
| 2933 |
and the ‘[ 1]’. |
| 2934 |
|
| 2935 |
|
| 2936 |
File: web2c.info, Node: Font utilities, Next: Legalisms, Prev: DVI utilities, Up: Top |
| 2937 |
|
| 2938 |
11 Font utilities |
| 2939 |
***************** |
| 2940 |
|
| 2941 |
The Web2c programs described here convert between various TeX-related |
| 2942 |
font formats; the first section below briefly describes the formats. |
| 2943 |
GFtoPK is the only one that is routinely used, as Metafont outputs GF |
| 2944 |
format, but it's most efficient for device drivers to use PK. |
| 2945 |
|
| 2946 |
The precise definitions of the PK, GF, TFM, PL, VF, and VPL formats |
| 2947 |
mentioned below are in the source files that read them; ‘pktype.web’, |
| 2948 |
‘gftype.web’, ‘tftopl.web’, etc. |
| 2949 |
|
| 2950 |
* Menu: |
| 2951 |
|
| 2952 |
* Font file formats:: Explanations of GF, PK, TFM, VF, ... |
| 2953 |
* gftopk invocation:: GF -> PK (compact) |
| 2954 |
* pktogf invocation:: PK -> GF (expand). |
| 2955 |
* pktype invocation:: PK -> human-readable text. |
| 2956 |
* gftype invocation:: GF -> human-readable text. |
| 2957 |
* tftopl invocation:: TFM -> PL (for editing TFM). |
| 2958 |
* pltotf invocation:: PL -> TFM (make editing results usable). |
| 2959 |
* vftovp invocation:: VF -> VPL (tftopl for virtual fonts). |
| 2960 |
* vptovf invocation:: VPL -> VF (pltotf for virtual fonts). |
| 2961 |
* Font utilities available elsewhere:: Type 1, BDF, editors, etc. |
| 2962 |
|
| 2963 |
|
| 2964 |
File: web2c.info, Node: Font file formats, Next: gftopk invocation, Up: Font utilities |
| 2965 |
|
| 2966 |
11.1 Font file formats |
| 2967 |
====================== |
| 2968 |
|
| 2969 |
For another perspective on this, *note (dvips)Font concepts::. |
| 2970 |
|
| 2971 |
Font files come in several varieties, with suffixes like: |
| 2972 |
.tfm .*pk .*gf .*pxl (obsolete) .pl .mf .vf .vpl |
| 2973 |
Each represents a file format. |
| 2974 |
|
| 2975 |
A TFM (TeX font metric) file is a compact binary file that contains |
| 2976 |
information about each character in a font, about combinations of |
| 2977 |
characters within that font, and about the font as a whole. The font |
| 2978 |
metric information contained in TFM files is device-independent units is |
| 2979 |
used by TeX to do typesetting. Unlike the bitmap (raster) fonts |
| 2980 |
described below, TFM font files contain no information about the shapes |
| 2981 |
of characters. They describe rectangular areas and combinations |
| 2982 |
thereof, but not what will eventually be printed in those areas. |
| 2983 |
|
| 2984 |
Since TeX does scaling calculations, one TFM file serves for all |
| 2985 |
magnifications of a given typeface. On the other hand, the best printed |
| 2986 |
results are obtained when magnified (or reduced fonts) are not produced |
| 2987 |
geometrically (as done by PostScript, for example) but rather optically, |
| 2988 |
with each size a separate design (as done with Computer Modern and the |
| 2989 |
EC fonts, for example); then a separate TFM file is needed for each |
| 2990 |
size. |
| 2991 |
|
| 2992 |
At any rate, TeX produces a DVI (DeVice Independent) file from your |
| 2993 |
source document. In order to print DVI files on real devices, you need |
| 2994 |
font files defining digitized character shapes and other data. Then |
| 2995 |
previewers and printer-driver programs can translate your DVI files into |
| 2996 |
something usable by your monitor or printer. Bitmap fonts come with |
| 2997 |
suffixes such as ‘.600pk’ or ‘.600gf’ or ‘.3000pxl’, where the ‘600’ is |
| 2998 |
the horizontal dots-per-inch resolution at which the font was produced, |
| 2999 |
and the ‘pk’ or ‘gf’ or ‘pxl’ indicates the font format. Outline fonts |
| 3000 |
in PostScript Type 1 format have suffixes such as ‘.pfa’ or ‘.pfb’. |
| 3001 |
|
| 3002 |
Fonts in pk (packed) format are in the tightly packed raster format |
| 3003 |
that is pretty much the standard today. They take up less space than |
| 3004 |
fonts in the gf (generic font) format that Metafont generates, and far |
| 3005 |
less space than fonts in pxl format. Fonts in pxl format take up gross |
| 3006 |
amounts of disk space and permit only 128 characters. They are |
| 3007 |
obsolete. |
| 3008 |
|
| 3009 |
Font files with the ‘.pl’ (property list) suffix are the plain text |
| 3010 |
(human-readable) analog of the binary ‘.tfm’ files. The TFtoPL and |
| 3011 |
PLtoTF programs convert between the two formats (*note tftopl |
| 3012 |
invocation:: and *note pltotf invocation::). |
| 3013 |
|
| 3014 |
Font files with the ‘.mf’ suffix are in Metafont source format. |
| 3015 |
These are the files used by Metafont to generate rastered fonts for |
| 3016 |
specific typefaces at specific magnifications for the specific |
| 3017 |
resolution and type of mapping used by your device. |
| 3018 |
|
| 3019 |
The suffix ‘.vf’ identifies "virtual font" files, for which ‘.vpl’ is |
| 3020 |
the human-readable analog. See *Note vftovp invocation::, and *note |
| 3021 |
vptovf invocation::. For further discussion of virtual fonts, see |
| 3022 |
‘CTAN:/doc/virtual-fonts.knuth’, ‘CTAN:/help/virtualfonts.txt’, and |
| 3023 |
*note (dvips)Virtual fonts::. |
| 3024 |
|
| 3025 |
(This section is based on documentation in the original Unix TeX |
| 3026 |
distribution by Pierre MacKay and Elizabeth Tachikawa.) |
| 3027 |
|
| 3028 |
|
| 3029 |
File: web2c.info, Node: gftopk invocation, Next: pktogf invocation, Prev: Font file formats, Up: Font utilities |
| 3030 |
|
| 3031 |
11.2 GFtoPK: Generic to packed font conversion |
| 3032 |
============================================== |
| 3033 |
|
| 3034 |
GFtoPK converts a generic font (GF) file output by, for example, |
| 3035 |
Metafont (*note mf invocation::) to a packed font (PK) file. PK files |
| 3036 |
are considerably smaller than the corresponding gf files, so they are |
| 3037 |
generally the bitmap font format of choice. Some DVI-processing |
| 3038 |
programs, notably Dvips, only support PK files and not GF files. |
| 3039 |
Synopsis: |
| 3040 |
|
| 3041 |
gftopk [OPTION]... GFNAME.DPI[gf] [PKFILE] |
| 3042 |
|
| 3043 |
The font GFNAME is searched for in the usual places (*note |
| 3044 |
(kpathsea)Glyph lookup::). To see all the relevant paths, set the |
| 3045 |
environment variable ‘KPATHSEA_DEBUG’ to ‘-1’ before running the |
| 3046 |
program. |
| 3047 |
|
| 3048 |
The suffix ‘gf’ is supplied if not already present. This suffix is |
| 3049 |
not an extension; no ‘.’ precedes it: for instance, ‘cmr10.600gf’. |
| 3050 |
|
| 3051 |
If PKFILE is not specified, the output is written to the basename of |
| 3052 |
‘GFNAME.DPIpk’, e.g., ‘gftopk /wherever/cmr10.600gf’ creates |
| 3053 |
‘./cmr10.600pk’. |
| 3054 |
|
| 3055 |
The only options are ‘--verbose’, ‘--help’, and ‘--version’ (*note |
| 3056 |
Common options::). |
| 3057 |
|
| 3058 |
|
| 3059 |
File: web2c.info, Node: pktogf invocation, Next: pktype invocation, Prev: gftopk invocation, Up: Font utilities |
| 3060 |
|
| 3061 |
11.3 PKtoGF: Packed to generic font conversion |
| 3062 |
============================================== |
| 3063 |
|
| 3064 |
PKtoGF converts a packed font (PK) file to a generic font (GF) file. |
| 3065 |
Since PK format is much more compact than GF format, the most likely |
| 3066 |
reason to do this is to run GFtype (*note gftype invocation::) on the |
| 3067 |
result, so you can see the bitmap images. Also, a few old utility |
| 3068 |
programs do not support PK format. Synopsis: |
| 3069 |
|
| 3070 |
pktogf [OPTION]... PKNAME.DPI[pk] [GFFILE] |
| 3071 |
|
| 3072 |
The font PKNAME is searched for in the usual places (*note |
| 3073 |
(kpathsea)Glyph lookup::). To see all the relevant paths, set the |
| 3074 |
environment variable ‘KPATHSEA_DEBUG’ to ‘-1’ before running the |
| 3075 |
program. |
| 3076 |
|
| 3077 |
The suffix ‘pk’ is supplied if not already present. This suffix is |
| 3078 |
not an extension; no ‘.’ precedes it: for instance, ‘cmr10.600pk’. |
| 3079 |
|
| 3080 |
If GFFILE is not specified, the output is written to the basename of |
| 3081 |
‘PKNAME.DPIgf’, e.g., ‘pktogf /wherever/cmr10.600pk’ creates |
| 3082 |
‘./cmr10.600gf’. |
| 3083 |
|
| 3084 |
The only options are ‘--verbose’, ‘--help’, and ‘--version’ (*note |
| 3085 |
Common options::). |
| 3086 |
|
| 3087 |
|
| 3088 |
File: web2c.info, Node: pktype invocation, Next: gftype invocation, Prev: pktogf invocation, Up: Font utilities |
| 3089 |
|
| 3090 |
11.4 PKtype: Plain text transliteration of packed fonts |
| 3091 |
======================================================= |
| 3092 |
|
| 3093 |
PKtype translates a packed font (PK) bitmap file (as output by GFtoPK, |
| 3094 |
for example) to a plain text file that humans can read. It also serves |
| 3095 |
as a PK-validating program, i.e., if PKtype can read a file, it's |
| 3096 |
correct. Synopsis: |
| 3097 |
|
| 3098 |
pktype PKNAME.DPI[pk] |
| 3099 |
|
| 3100 |
The font PKNAME is searched for in the usual places (*note |
| 3101 |
(kpathsea)Glyph lookup::). To see all the relevant paths, set the |
| 3102 |
environment variable ‘KPATHSEA_DEBUG’ to ‘-1’ before running the |
| 3103 |
program. |
| 3104 |
|
| 3105 |
The suffix ‘pk’ is supplied if not already present. This suffix is |
| 3106 |
not an extension; no ‘.’ precedes it: for instance, ‘cmr10.600pk’. |
| 3107 |
|
| 3108 |
The translation is written to standard output. |
| 3109 |
|
| 3110 |
The only options are ‘-help’ and ‘-version’ (*note Common options::). |
| 3111 |
|
| 3112 |
As an example of the output, here is the (abridged) translation of |
| 3113 |
the letter 'K' in ‘cmr10’, as rendered at 600dpi with the mode ‘ljfour’ |
| 3114 |
from ‘modes.mf’ (<https://ctan.org/pkg/modes>). |
| 3115 |
|
| 3116 |
955: Flag byte = 184 Character = 75 Packet length = 174 |
| 3117 |
Dynamic packing variable = 11 |
| 3118 |
TFM width = 815562 dx = 4259840 |
| 3119 |
Height = 57 Width = 57 X-offset = -3 Y-offset = 56 |
| 3120 |
[2]23(16)17(8)9(25)11(13)7(27)7(16)7(28)4(18)7(28)2(20)7(27)... |
| 3121 |
... |
| 3122 |
(14)9(24)12(5)[2]23(13)21 |
| 3123 |
|
| 3124 |
Explanation: |
| 3125 |
|
| 3126 |
‘955’ |
| 3127 |
The byte position in the file where this character starts. |
| 3128 |
|
| 3129 |
‘Flag byte’ |
| 3130 |
‘Dynamic packing variable’ |
| 3131 |
Related to the packing for this character; see the source code. |
| 3132 |
|
| 3133 |
‘Character’ |
| 3134 |
The character code, in decimal. |
| 3135 |
|
| 3136 |
‘Packet length’ |
| 3137 |
The total length of this character definition, in bytes. |
| 3138 |
|
| 3139 |
‘TFM width’ |
| 3140 |
The device-independent (TFM) width of this character. It is 2^24 |
| 3141 |
times the ratio of the true width to the font's design size. |
| 3142 |
|
| 3143 |
‘dx’ |
| 3144 |
The device-dependent width, in “scaled pixels”, i.e., units of |
| 3145 |
horizontal pixels times 2^16. |
| 3146 |
|
| 3147 |
‘Height’ |
| 3148 |
‘Width’ |
| 3149 |
The bitmap height and width, in pixels. |
| 3150 |
|
| 3151 |
‘X-offset’ |
| 3152 |
‘Y-offset’ |
| 3153 |
Horizontal and vertical offset from the upper left pixel to the |
| 3154 |
reference (origin) pixel for this character, in pixels (right and |
| 3155 |
down are positive). The “reference pixel” is the pixel that |
| 3156 |
occupies the unit square in Metafont; the Metafont reference point |
| 3157 |
is the lower left hand corner of this pixel. Put another way, the |
| 3158 |
x-offset is the negative of the left side bearing; the right side |
| 3159 |
bearing is the horizontal escapement minus the bitmap width plus |
| 3160 |
the x-offset. |
| 3161 |
|
| 3162 |
‘[2]23(16)...’ |
| 3163 |
Finally, run lengths of black pixels alternate with parenthesized |
| 3164 |
run lengths of white pixels, and brackets indicate a repeated row. |
| 3165 |
|
| 3166 |
|
| 3167 |
File: web2c.info, Node: gftype invocation, Next: tftopl invocation, Prev: pktype invocation, Up: Font utilities |
| 3168 |
|
| 3169 |
11.5 GFtype: Plain text transliteration of generic fonts |
| 3170 |
======================================================== |
| 3171 |
|
| 3172 |
GFtype translates a generic font (GF) bitmap file (as output by |
| 3173 |
Metafont, for example) to a plain text file that humans can read. It |
| 3174 |
also serves as a GF-validating program, i.e., if GFtype can read a file, |
| 3175 |
it's correct. Synopsis: |
| 3176 |
|
| 3177 |
gftype [OPTION]... GFNAME.DPI[gf] |
| 3178 |
|
| 3179 |
The font GFNAME is searched for in the usual places (*note |
| 3180 |
(kpathsea)Glyph lookup::). To see all the relevant paths, set the |
| 3181 |
environment variable ‘KPATHSEA_DEBUG’ to ‘-1’ before running the |
| 3182 |
program. |
| 3183 |
|
| 3184 |
The suffix ‘gf’ is supplied if not already present. This suffix is |
| 3185 |
not an extension; no ‘.’ precedes it: for instance, ‘cmr10.600gf’. |
| 3186 |
|
| 3187 |
The translation is written to standard output. |
| 3188 |
|
| 3189 |
The program accepts the following options, as well as the standard |
| 3190 |
‘-help’ and ‘-version’ (*note Common options::): |
| 3191 |
‘-images’ |
| 3192 |
Show the characters' bitmaps using asterisks and spaces. |
| 3193 |
|
| 3194 |
‘-mnemonics’ |
| 3195 |
Translate all commands in the GF file. |
| 3196 |
|
| 3197 |
As an example of the output, here is the (abridged) translation of |
| 3198 |
the letter 'K' in ‘cmr10’, as rendered at 600dpi with the mode ‘ljfour’ |
| 3199 |
from ‘modes.mf’ (<https://ctan.org/pkg/modes>), with both ‘-mnemonics’ |
| 3200 |
and ‘-images’ enabled. |
| 3201 |
|
| 3202 |
GFtype outputs the information about a character in two places: a |
| 3203 |
main definition and a one-line summary at the end. We show both. Here |
| 3204 |
is the main definition: |
| 3205 |
|
| 3206 |
2033: beginning of char 75: 3<=m<=60 0<=n<=56 |
| 3207 |
(initially n=56) paint (0)24(12)20 |
| 3208 |
2043: newrow 0 (n=55) paint 24(12)20 |
| 3209 |
2047: newrow 0 (n=54) paint 24(12)20 |
| 3210 |
2051: newrow 0 (n=53) paint 24(12)20 |
| 3211 |
2055: newrow 7 (n=52) paint 10(21)13 |
| 3212 |
2059: newrow 8 (n=51) paint 8(23)9 |
| 3213 |
... |
| 3214 |
2249: newrow 8 (n=5) paint 8(23)11 |
| 3215 |
2253: newrow 7 (n=4) paint 10(22)12 |
| 3216 |
2257: newrow 0 (n=3) paint 24(11)22 |
| 3217 |
2261: newrow 0 (n=2) paint 24(11)22 |
| 3218 |
2265: newrow 0 (n=1) paint 24(11)22 |
| 3219 |
2269: newrow 0 (n=0) paint 24(11)22 |
| 3220 |
2273: eoc |
| 3221 |
.<--This pixel's lower left corner is at (3,57) in METAFONT coordinates |
| 3222 |
************************ ******************** |
| 3223 |
************************ ******************** |
| 3224 |
************************ ******************** |
| 3225 |
************************ ******************** |
| 3226 |
********** ************* |
| 3227 |
******** ********* |
| 3228 |
... |
| 3229 |
******** *********** |
| 3230 |
********** ************ |
| 3231 |
************************ ********************** |
| 3232 |
************************ ********************** |
| 3233 |
************************ ********************** |
| 3234 |
************************ ********************** |
| 3235 |
.<--This pixel's upper left corner is at (3,0) in METAFONT coordinates |
| 3236 |
|
| 3237 |
Explanation: |
| 3238 |
|
| 3239 |
‘2033’ |
| 3240 |
‘2043’ |
| 3241 |
‘...’ |
| 3242 |
The byte position in the file where each GF command starts. |
| 3243 |
|
| 3244 |
‘beginning of char 75’ |
| 3245 |
The character code, in decimal. |
| 3246 |
|
| 3247 |
‘3<=m<=60 0<=n<=56’ |
| 3248 |
The character's bitmap lies between 3 and 60 (inclusive) |
| 3249 |
horizontally, and between 0 and 56 (inclusive) vertically. (m is a |
| 3250 |
column position and n is a row position.) Thus, 3 is the left side |
| 3251 |
bearing. The right side bearing is the horizontal escapement |
| 3252 |
(given below) minus the maximum m. |
| 3253 |
|
| 3254 |
‘(initially n=56) paint (0)24(12)20’ |
| 3255 |
The first row of pixels: 0 white pixels, 24 black pixels, 12 white |
| 3256 |
pixels, etc. |
| 3257 |
|
| 3258 |
‘newrow 0 (n=55) paint 24(12)20’ |
| 3259 |
The second row of pixels, with zero leading white pixels on the |
| 3260 |
row. |
| 3261 |
|
| 3262 |
‘eoc’ |
| 3263 |
The end of the main character definition. |
| 3264 |
|
| 3265 |
Here is the GF postamble information that GFtype outputs at the end: |
| 3266 |
|
| 3267 |
Character 75: dx 4259840 (65), width 815562 (64.57289), loc 2033 |
| 3268 |
|
| 3269 |
Explanation: |
| 3270 |
|
| 3271 |
‘dx’ |
| 3272 |
The device-dependent width, in “scaled pixels”, i.e., units of |
| 3273 |
horizontal pixels times 2^16. The ‘(65)’ is simply the same number |
| 3274 |
rounded. If the vertical escapement is nonzero, it would appear |
| 3275 |
here as a ‘dy’ value. |
| 3276 |
|
| 3277 |
‘width’ |
| 3278 |
The device-independent (TFM) width of this character. It is 2^24 |
| 3279 |
times the ratio of the true width to the font's design size. The |
| 3280 |
‘64.57289’ is the same number converted to pixels. |
| 3281 |
|
| 3282 |
‘loc’ |
| 3283 |
The byte position in the file where this character starts. |
| 3284 |
|
| 3285 |
|
| 3286 |
File: web2c.info, Node: tftopl invocation, Next: pltotf invocation, Prev: gftype invocation, Up: Font utilities |
| 3287 |
|
| 3288 |
11.6 TFtoPL: TeX font metric to property list conversion |
| 3289 |
======================================================== |
| 3290 |
|
| 3291 |
TFtoPL translates a TeX font metric (TFM, *note (dvips)Metric files::) |
| 3292 |
file (as output by Metafont, for example) to “property list format” (a |
| 3293 |
list of parenthesized items describing the font) that humans can edit or |
| 3294 |
read. This program is mostly used by people debugging TeX |
| 3295 |
implementations, writing font utilities, etc. Synopsis: |
| 3296 |
|
| 3297 |
tftopl [OPTION]... TFMNAME[.tfm] [PLFILE[.pl]] |
| 3298 |
|
| 3299 |
The font TFMNAME (extended with ‘.tfm’ if necessary) is searched for |
| 3300 |
in the usual places (*note (kpathsea)Supported file formats::). To see |
| 3301 |
all the relevant paths, set the environment variable ‘KPATHSEA_DEBUG’ to |
| 3302 |
‘-1’ before running the program. |
| 3303 |
|
| 3304 |
If PLFILE (which is extended with ‘.pl’ if necessary) is not |
| 3305 |
specified, the property list file is written to standard output. The |
| 3306 |
property list file can be converted back to TFM format by the companion |
| 3307 |
program TFtoPL (see the next section). |
| 3308 |
|
| 3309 |
The program accepts the following option, as well as the standard |
| 3310 |
‘-verbose’, ‘-help’ and ‘-version’ (*note Common options::): |
| 3311 |
‘-charcode-format=TYPE’ |
| 3312 |
Output character codes in the PL file according to TYPE: either |
| 3313 |
‘octal’ or ‘ascii’. Default is ‘ascii’ for letters and digits, |
| 3314 |
octal for all other characters. Exception: if the font's coding |
| 3315 |
scheme starts with ‘TeX math sy’ or ‘TeX math ex’, all character |
| 3316 |
codes are output in octal. |
| 3317 |
|
| 3318 |
In ‘ascii’ format, character codes that correspond to graphic |
| 3319 |
characters, except for left and right parentheses, are output as a |
| 3320 |
‘C’ followed by the single character: ‘C K’, for example. In octal |
| 3321 |
format, character codes are output as the letter ‘O’ followed by |
| 3322 |
octal digits, as in ‘O 113’ for ‘K’. |
| 3323 |
|
| 3324 |
‘octal’ format is useful for symbol and other non-alphabetic fonts, |
| 3325 |
where using ASCII characters for the character codes is merely |
| 3326 |
confusing. |
| 3327 |
|
| 3328 |
As an example of the output, here is the (abridged) property list |
| 3329 |
translation of ‘cmr10.tfm’: |
| 3330 |
|
| 3331 |
(FAMILY CMR) |
| 3332 |
(FACE O 352) |
| 3333 |
(CODINGSCHEME TEX TEXT) |
| 3334 |
(DESIGNSIZE R 10.0) |
| 3335 |
(COMMENT DESIGNSIZE IS IN POINTS) |
| 3336 |
(COMMENT OTHER SIZES ARE MULTIPLES OF DESIGNSIZE) |
| 3337 |
(CHECKSUM O 11374260171) |
| 3338 |
(FONTDIMEN |
| 3339 |
(SLANT R 0.0) |
| 3340 |
(SPACE R 0.333334) |
| 3341 |
(STRETCH R 0.166667) |
| 3342 |
(SHRINK R 0.111112) |
| 3343 |
(XHEIGHT R 0.430555) |
| 3344 |
(QUAD R 1.000003) |
| 3345 |
(EXTRASPACE R 0.111112) |
| 3346 |
) |
| 3347 |
(LIGTABLE |
| 3348 |
... |
| 3349 |
(LABEL C f) |
| 3350 |
(LIG C i O 14) |
| 3351 |
(LIG C f O 13) |
| 3352 |
(LIG C l O 15) |
| 3353 |
(KRN O 47 R 0.077779) |
| 3354 |
(KRN O 77 R 0.077779) |
| 3355 |
(KRN O 41 R 0.077779) |
| 3356 |
(KRN O 51 R 0.077779) |
| 3357 |
(KRN O 135 R 0.077779) |
| 3358 |
(STOP) |
| 3359 |
... |
| 3360 |
) |
| 3361 |
... |
| 3362 |
(CHARACTER C f |
| 3363 |
(CHARWD R 0.305557) |
| 3364 |
(CHARHT R 0.694445) |
| 3365 |
(CHARIC R 0.077779) |
| 3366 |
(COMMENT |
| 3367 |
(LIG C i O 14) |
| 3368 |
(LIG C f O 13) |
| 3369 |
(LIG C l O 15) |
| 3370 |
(KRN O 47 R 0.077779) |
| 3371 |
(KRN O 77 R 0.077779) |
| 3372 |
... |
| 3373 |
) |
| 3374 |
) |
| 3375 |
... |
| 3376 |
|
| 3377 |
As you can see, the general format is a list of parenthesized |
| 3378 |
“properties”, nested where necessary. |
| 3379 |
|
| 3380 |
• The first few items (‘FAMILY’, ‘FACE’, and so on) are the so-called |
| 3381 |
“headerbyte” information from Metafont, giving general information |
| 3382 |
about the font. |
| 3383 |
|
| 3384 |
• The ‘FONTDIMEN’ property defines the TeX ‘\fontdimen’ values. |
| 3385 |
|
| 3386 |
• The ‘LIGTABLE’ property defines the ligature and kerning table. |
| 3387 |
‘LIG’ properties define ligatures: in the example above, an ‘f’ (in |
| 3388 |
the ‘LABEL’) followed by an ‘i’ is a ligature, i.e., a typesetting |
| 3389 |
program like TeX replaces those two consecutive characters by the |
| 3390 |
character at position octal '014 in the current font--presumably |
| 3391 |
the 'fi' ligature. ‘KRN’ properties define kerns: if an ‘f’ is |
| 3392 |
followed by character octal '047 (an apostrophe), TeX inserts a |
| 3393 |
small amount of space between them: 0.077779 times the design size |
| 3394 |
the font was loaded at (about three-quarters of a printer's point |
| 3395 |
by default in this case, or .001 inches). |
| 3396 |
|
| 3397 |
• The ‘CHARACTER’ property defines the dimensions of a character: its |
| 3398 |
width, height, depth, and italic correction, also in design-size |
| 3399 |
units, as explained in the previous item. For our example 'f', the |
| 3400 |
depth is zero, so that property is omitted. TFtoPL also inserts |
| 3401 |
any kerns and ligatures for this character as a comment. |
| 3402 |
|
| 3403 |
|
| 3404 |
File: web2c.info, Node: pltotf invocation, Next: vftovp invocation, Prev: tftopl invocation, Up: Font utilities |
| 3405 |
|
| 3406 |
11.7 PLtoTF: Property list to TeX font metric conversion |
| 3407 |
======================================================== |
| 3408 |
|
| 3409 |
PLtoTF translates a property list file (as output by TFtoPL, for |
| 3410 |
example) to TeX font metric (TFM, *note (dvips)Metric files::) format. |
| 3411 |
It's much easier for both programs and humans to create the (plain text) |
| 3412 |
property list files and let PLtoTF take care of creating the binary TFM |
| 3413 |
equivalent than to output TFM files directly. Synopsis: |
| 3414 |
|
| 3415 |
pltotf [OPTION]... PLFILE[.pl] [TFMFILE[.tfm]] |
| 3416 |
|
| 3417 |
If TFMFILE (extended with ‘.tfm’ if necessary) is not specified, the |
| 3418 |
TFM file is written to the basename of ‘PLFILE.tfm’, e.g., ‘pltotf |
| 3419 |
/wherever/cmr10.pl’ creates ‘./cmr10.tfm’. (Since TFM files are binary, |
| 3420 |
writing to standard output by default is undesirable.) |
| 3421 |
|
| 3422 |
The only options are ‘-verbose’, ‘-help’, and ‘-version’ (*note |
| 3423 |
Common options::). |
| 3424 |
|
| 3425 |
For an example of property list format, see the previous section. |
| 3426 |
|
| 3427 |
|
| 3428 |
File: web2c.info, Node: vftovp invocation, Next: vptovf invocation, Prev: pltotf invocation, Up: Font utilities |
| 3429 |
|
| 3430 |
11.8 VFtoVP: Virtual font to virtual property lists |
| 3431 |
=================================================== |
| 3432 |
|
| 3433 |
VFtoVP translates a virtual font metric (VF, *note (dvips)Virtual |
| 3434 |
fonts::) file and its accompanying TeX font metric (TFM, *note |
| 3435 |
(dvips)Metric files::) file (as output by VPtoVF, for example) to |
| 3436 |
“virtual property list format” (a list of parenthesized items describing |
| 3437 |
the virtual font) that humans can edit or read. This program is mostly |
| 3438 |
used by people debugging virtual font utilities. Synopsis: |
| 3439 |
|
| 3440 |
vftovp [OPTION]... VFNAME[.vf] [TFMNAME[.tfm] [VPLFILE[.vpl]]] |
| 3441 |
|
| 3442 |
The fonts VFNAME and TFMNAME (extended with ‘.vf’ and ‘.tfm’ if |
| 3443 |
necessary) are searched for in the usual places (*note |
| 3444 |
(kpathsea)Supported file formats::). To see all the relevant paths, set |
| 3445 |
the environment variable ‘KPATHSEA_DEBUG’ to ‘-1’ before running the |
| 3446 |
program. If TFMNAME is not specified, VFNAME (without a trailing ‘.vf’) |
| 3447 |
is used. |
| 3448 |
|
| 3449 |
If VPLFILE (extended with ‘.vpl’ if necessary) is not specified, the |
| 3450 |
property list file is written to standard output. The property list |
| 3451 |
file can be converted back to VF and TFM format by the companion program |
| 3452 |
VFtoVP (see the next section). |
| 3453 |
|
| 3454 |
The program accepts the following option, as well as the standard |
| 3455 |
‘-verbose’, ‘-help’ and ‘-version’ (*note Common options::): |
| 3456 |
‘-charcode-format=TYPE’ |
| 3457 |
Output character codes in the PL file according to TYPE: either |
| 3458 |
‘octal’ or ‘ascii’. Default is ‘ascii’ for letters and digits, |
| 3459 |
octal for all other characters. Exception: if the font's coding |
| 3460 |
scheme starts with ‘TeX math sy’ or ‘TeX math ex’, all character |
| 3461 |
codes are output in octal. |
| 3462 |
|
| 3463 |
In ‘ascii’ format, character codes that correspond to graphic |
| 3464 |
characters, except for left and right parentheses, are output as a |
| 3465 |
‘C’ followed by the single character: ‘C K’, for example. In octal |
| 3466 |
format, character codes are output as the letter ‘O’ followed by |
| 3467 |
octal digits, as in ‘O 113’ for ‘K’. |
| 3468 |
|
| 3469 |
‘octal’ format is useful for symbol and other non-alphabetic fonts, |
| 3470 |
where using ASCII characters for the character codes is merely |
| 3471 |
confusing. |
| 3472 |
|
| 3473 |
|
| 3474 |
File: web2c.info, Node: vptovf invocation, Next: Font utilities available elsewhere, Prev: vftovp invocation, Up: Font utilities |
| 3475 |
|
| 3476 |
11.9 VPtoVF: Virtual property lists to virtual font |
| 3477 |
=================================================== |
| 3478 |
|
| 3479 |
VPtoVF translates a virtual property list file (as output by VFtoVP, for |
| 3480 |
example) to virtual font (VF, *note (dvips)Virtual fonts::) and TeX font |
| 3481 |
metric (TFM, *note (dvips)Metric files::) files. It's much easier for |
| 3482 |
both programs and humans to create the (plain text) property list files |
| 3483 |
and let VPtoVF take care of creating the binary VF and TFM equivalents |
| 3484 |
than to output them directly. Synopsis: |
| 3485 |
|
| 3486 |
vptovf [OPTION]... VPLFILE[.vpl] [VFFILE[.vf] [TFMFILE[.tfm]]] |
| 3487 |
|
| 3488 |
If VFFILE (extended with ‘.vf’ if necessary) is not specified, the VF |
| 3489 |
output is written to the basename of ‘VPLFILE.vf’; similarly for |
| 3490 |
TFMFILE. For example, ‘vptovf /wherever/ptmr.vpl’ creates ‘./ptmr.vf’ |
| 3491 |
and ‘./ptmr.tfm’. |
| 3492 |
|
| 3493 |
The only options are ‘-verbose’, ‘-help’, and ‘-version’ (*note |
| 3494 |
Common options::). |
| 3495 |
|
| 3496 |
|
| 3497 |
File: web2c.info, Node: Font utilities available elsewhere, Prev: vptovf invocation, Up: Font utilities |
| 3498 |
|
| 3499 |
11.10 Font utilities available elsewhere |
| 3500 |
======================================== |
| 3501 |
|
| 3502 |
The Web2c complement of font utilities merely implements a few basic |
| 3503 |
conversions. Many other more sophisticated font utilities exist; most |
| 3504 |
are in ‘CTAN:/fonts/utilities’ (for CTAN info, *note |
| 3505 |
(kpathsea)unixtex.ftp::). Here are some of the most commonly-requested |
| 3506 |
items: |
| 3507 |
|
| 3508 |
• AFM (Adobe font metric) to TFM conversion: *note (dvips)Invoking |
| 3509 |
afm2tfm::, and ‘CTAN:/fonts/utilities/afmtopl’. |
| 3510 |
|
| 3511 |
• BDF (the X bitmap format) conversion: |
| 3512 |
<ftp://ftp.tug.org/tex/bdf.tar.gz>. |
| 3513 |
|
| 3514 |
• Creating fonts using MetaPost: MetaType1: |
| 3515 |
<https://ctan.org/pkg/metatype1>. This was used to create the |
| 3516 |
Latin Modern font family (<https://ctan.org/pkg/lm>), which extends |
| 3517 |
Computer Modern to a larger repertoire of scripts. |
| 3518 |
|
| 3519 |
• Editing of bitmap fonts: Xbfe from the GNU font utilities mentioned |
| 3520 |
below; the X BDF-editing programs ‘xfed’ and ‘xfedor’; finally, if |
| 3521 |
your fonts have only 128 characters, you can use the old ‘gftopxl’, |
| 3522 |
‘pxtoch’, and ‘chtopx’ programs from <ftp://ftp.tug.org/tex/web>. |
| 3523 |
|
| 3524 |
• Editing of outline fonts: FontForge, |
| 3525 |
<https://fontforge.sourceforge.net>. This is a very elaborate |
| 3526 |
program with support for many outline formats (Type 1, OpenType, |
| 3527 |
TrueType, ...), and many advanced font editing features. |
| 3528 |
|
| 3529 |
• PK bitmaps from PostScript outline fonts: gsftopk from the ‘xdvi’ |
| 3530 |
distribution. Alternatively, ‘ps2pk’, from |
| 3531 |
‘CTAN:/fonts/utilities/ps2pk’. |
| 3532 |
|
| 3533 |
• PostScript Type 1 font format conversion (i.e., between PFA and PFB |
| 3534 |
formats): <https://www.lcdf.org/type>. |
| 3535 |
|
| 3536 |
• Tracing bitmaps to fitted outlines: Autotrace |
| 3537 |
(<http://autotrace.sourceforge.net>), Potrace |
| 3538 |
(<http://potrace.sourceforge.net>). For Metafont fonts, either of |
| 3539 |
the two programs ‘mftrace’ (<http://www.xs4all.nl/~hanwen/mftrace>) |
| 3540 |
or ‘textrace’ (<http://textrace.sourceforge.net>) make the job |
| 3541 |
easier. |
| 3542 |
|
| 3543 |
• Virtual font creation: <https://ctan.org/pkg/fontinst>. |
| 3544 |
|
| 3545 |
|
| 3546 |
File: web2c.info, Node: Legalisms, Next: References, Prev: Font utilities, Up: Top |
| 3547 |
|
| 3548 |
Appendix A Legalisms |
| 3549 |
******************** |
| 3550 |
|
| 3551 |
In general, each file has its own copyright notice stating the copying |
| 3552 |
permissions for that file. Following is a summary. |
| 3553 |
|
| 3554 |
The Stanford TeX programs and Web2c system itself are in the public |
| 3555 |
domain (<https://tug.org/texlive/copying.html>). The sources may be |
| 3556 |
copied verbatim, or used as the starting point of new software under |
| 3557 |
different names; however, per the wishes of the authors, they should be |
| 3558 |
modified only through a ‘.ch’ file, but this is in the nature of a |
| 3559 |
development request rather than a legal requirement. |
| 3560 |
|
| 3561 |
MLTeX, pdfTeX, LuaTeX, XeTeX, and all the other derived engines have |
| 3562 |
used various license terms for their additions to the base code, often |
| 3563 |
the GPL (see <https://www.gnu.org/licenses/#GPL>) or (for example) the |
| 3564 |
file ‘web2c/pdftexdir/COPYINGv2’. They also mostly make use of |
| 3565 |
additional libraries with their own (compatible) terms. Please see each |
| 3566 |
program's sources. |
| 3567 |
|
| 3568 |
The Kpathsea library is covered by the GNU Lesser General Public |
| 3569 |
License (*note (kpathsea)Introduction::). Therefore, the _binaries_ |
| 3570 |
resulting from a standard Web2c compilation are also covered by the |
| 3571 |
LGPL; so if you (re)distribute the binaries, you must also (offer to) |
| 3572 |
distribute the complete source that went into those binaries. See |
| 3573 |
<https://gnu.org/licenses/#LGPL> or the file |
| 3574 |
‘kpathsea/COPYING.LESSERv2’. |
| 3575 |
|
| 3576 |
|
| 3577 |
File: web2c.info, Node: References, Next: Index, Prev: Legalisms, Up: Top |
| 3578 |
|
| 3579 |
Appendix B References |
| 3580 |
********************* |
| 3581 |
|
| 3582 |
1. Kpathsea: *Note Introduction: (kpathsea)Top. |
| 3583 |
|
| 3584 |
2. Dvips and Afm2tfm: *Note Introduction: (dvips)Top. |
| 3585 |
|
| 3586 |
3. The TeX Users Group: <https://tug.org>. For an introduction to the |
| 3587 |
TeX system, see <https://tug.org/begin.html>. |
| 3588 |
|
| 3589 |
4. TUGboat, the principal journal for the TeX world: |
| 3590 |
<https://tug.org/TUGboat>. |
| 3591 |
|
| 3592 |
5. TeX and computer typesetting in general: |
| 3593 |
<https://ftp.math.utah.edu/pub/tex/bib/texbook1.bib> and |
| 3594 |
‘texbook3.bib’, among others. |
| 3595 |
|
| 3596 |
6. For a bibliography of formal articles and technical reports on the |
| 3597 |
TeX project, see the books ‘TeX: The Program’ or ‘Metafont: The |
| 3598 |
Program’ cited below. |
| 3599 |
|
| 3600 |
7. [Bil87] Neenie Billawala. Write-white printing engines and tuning |
| 3601 |
fonts with Metafont. ‘TUGboat’, 8(1):29-32, April 1987. |
| 3602 |
<https://tug.org/TUGboat/tb08-1/tb17billawala.pdf>. |
| 3603 |
|
| 3604 |
8. [Hob89] John D. Hobby. A Metafont-like system with PS output. |
| 3605 |
‘TUGboat’, 10(4):505-512, December 1989. |
| 3606 |
<https://tug.org/metapost>. |
| 3607 |
|
| 3608 |
9. [Hob92] John D. Hobby. A User's Manual for MetaPost. Technical |
| 3609 |
Report CSTR-162, AT&T Bell Laboratories, 1992. |
| 3610 |
|
| 3611 |
10. [Hob93] John D. Hobby. Drawing Graphs with MetaPost. Technical |
| 3612 |
Report CSTR-164, AT&T Bell Laboratories, 1993. |
| 3613 |
|
| 3614 |
11. [HS91] Samuel P. Harbison and Guy L. Steele Jr. ‘C--A Reference |
| 3615 |
Manual’. Prentice-Hall, Upper Saddle River, NJ 07458, USA, third |
| 3616 |
edition, 1991. An authoritative reference to the C programming |
| 3617 |
language, and a good companion to Kernighan and Ritchie. |
| 3618 |
|
| 3619 |
12. [KL93] Donald E. Knuth and Silvio Levy. ‘The CWEB System of |
| 3620 |
Structured Documentation, Version 3.0’. Addison-Wesley, Reading, |
| 3621 |
MA, USA, 1993. <https://ctan.org/pkg/cweb>. |
| 3622 |
|
| 3623 |
13. [Knu84] Donald E. Knuth. A torture test for TeX. Report No. |
| 3624 |
STAN-CS-84-1027, Stanford University, Department of Computer |
| 3625 |
Science, 1984. |
| 3626 |
|
| 3627 |
14. [Knu86a] Donald E. Knuth. A Torture Test for METAFONT. Report No. |
| 3628 |
STAN-CS-86-1095, Stanford University, Department of Computer |
| 3629 |
Science, 1986. |
| 3630 |
|
| 3631 |
15. [Knu86b] Donald E. Knuth. ‘The TeXbook’, volume A of ‘Computers |
| 3632 |
and Typesetting’. Addison-Wesley, Reading, MA, USA, 1986. |
| 3633 |
|
| 3634 |
16. [Knu86c] Donald E. Knuth. ‘TeX: The Program’, volume B of |
| 3635 |
‘Computers and Typesetting’. Addison-Wesley, Reading, MA, USA, |
| 3636 |
1986. |
| 3637 |
|
| 3638 |
17. [Knu86d] Donald E. Knuth. ‘The METAFONTbook’, volume C of |
| 3639 |
‘Computers and Typesetting’. Addison-Wesley, Reading, MA, USA, |
| 3640 |
1986. |
| 3641 |
|
| 3642 |
18. [Knu86e] Donald E. Knuth. ‘METAFONT: The Program’, volume D of |
| 3643 |
‘Computers and Typesetting’. Addison-Wesley, Reading, MA, USA, |
| 3644 |
1986. |
| 3645 |
|
| 3646 |
19. [Knu86f] Donald E. Knuth. ‘Computer Modern Typefaces’, volume E |
| 3647 |
of ‘Computers and Typesetting’. Addison-Wesley, Reading, MA, USA, |
| 3648 |
1986. |
| 3649 |
|
| 3650 |
20. [Knu89] Donald E. Knuth. The errors of TeX. ‘Software--Practice |
| 3651 |
and Experience’, 19(7):607-681, July 1989. This is an updated |
| 3652 |
version of Knuth:1988:ET. |
| 3653 |
|
| 3654 |
21. [Knu90] Donald Knuth. Virtual Fonts: More Fun for Grand Wizards. |
| 3655 |
‘TUGboat’, 11(1):13-23, April 1990. |
| 3656 |
<https://tug.org/TUGboat/tb11-1/tb27knut.pdf>. |
| 3657 |
|
| 3658 |
22. [Knu92] Donald E. Knuth. ‘Literate Programming’. CSLI Lecture |
| 3659 |
Notes Number 27. Stanford University Center for the Study of |
| 3660 |
Language and Information, Stanford, CA, USA, 1992. |
| 3661 |
|
| 3662 |
23. [Lam94] Leslie Lamport. ‘LaTeX: A Document Preparation System: |
| 3663 |
User's Guide and Reference Manual’. Addison-Wesley, Reading, MA, |
| 3664 |
USA, second edition, 1994. Reprinted with corrections, 1996. |
| 3665 |
|
| 3666 |
24. [Lia83] Franklin Mark Liang. Word hy-phen-a-tion by com-put-er. |
| 3667 |
Technical Report STAN-CS-83-977, Stanford University, August 1983. |
| 3668 |
<https://tug.org/docs/liang/liang-thesis.pdf>. |
| 3669 |
|
| 3670 |
25. [Mac91] Pierre A. MacKay. Looking at the pixels: Quality control |
| 3671 |
for 300 dpi laser printer fonts, especially Metafonts. In Robert |
| 3672 |
A. Morris and Jacques Andre, editors, ‘Raster Imaging and Digital |
| 3673 |
Typography II--Papers from the second RIDT meeting, held in Boston, |
| 3674 |
Oct. 14-16, 1991’, pages 205-215, New York, 1991. Cambridge |
| 3675 |
University Press. |
| 3676 |
|
| 3677 |
|
| 3678 |
File: web2c.info, Node: Index, Prev: References, Up: Top |
| 3679 |
|
| 3680 |
Index |
| 3681 |
***** |
| 3682 |
|
| 3683 |
|