home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 5 Edit / 05-Edit.zip / texlatex.zip / web2c72.zip / info / web2c.info-1 (.txt) < prev    next >
GNU Info File  |  1999-09-14  |  53KB  |  984 lines
  1. This is Info file web2c.info, produced by Makeinfo version 1.68 from
  2. the input file web2c.texi.
  3. INFO-DIR-SECTION TeX
  4. START-INFO-DIR-ENTRY
  5. * Web2c: (web2c).                    TeX, Metafont, and companion programs.
  6. * bibtex: (web2c)bibtex invocation.             Maintaining bibliographies.
  7. * dmp: (web2c)dmp invocation.                   Troff->MPX (MetaPost pictures).
  8. * dvicopy: (web2c)dvicopy invocation.           Virtual font expansion
  9. * dvitomp: (web2c)dvitomp invocation.           DVI to MPX (MetaPost pictures).
  10. * dvitype: (web2c)dvitype invocation.           DVI to human-readable text.
  11. * gftodvi: (web2c)gftodvi invocation.           Generic font proofsheets.
  12. * gftopk: (web2c)gftopk invocation.             Generic to packed fonts.
  13. * gftype: (web2c)gftype invocation.             GF to human-readable text.
  14. * inimf: (web2c)inimf invocation.               Initial Metafont.
  15. * inimpost: (web2c)inimpost invocation.         Initial MetaPost.
  16. * initex: (web2c)initex invocation.             Initial TeX.
  17. * makempx: (web2c)makempx invocation.           MetaPost label typesetting.
  18. * mf: (web2c)mf invocation.                     Creating typeface families.
  19. * mft: (web2c)mft invocation.                   Prettyprinting Metafont source.
  20. * mltex: (web2c)MLTeX.                          Multi-lingual TeX.
  21. * mpost: (web2c)mpost invocation.               Creating technical diagrams.
  22. * mpto: (web2c)mpto invocation.                 MetaPost label extraction.
  23. * newer: (web2c)newer invocation.               Compare modification times.
  24. * patgen: (web2c)patgen invocation.             Creating hyphenation patterns.
  25. * pktogf: (web2c)pktogf invocation.             Packed to generic fonts.
  26. * pktype: (web2c)pktype invocation.             PK to human-readable text.
  27. * pltotf: (web2c)pltotf invocation.             Property list to TFM.
  28. * pooltype: (web2c)pooltype invocation.         Display WEB pool files.
  29. * tangle: (web2c)tangle invocation.             WEB to Pascal.
  30. * tex: (web2c)tex invocation.                   Typesetting.
  31. * tftopl: (web2c)tftopl invocation.             TFM -> property list.
  32. * vftovp: (web2c)vftovp invocation.             Virtual font -> virtual pl.
  33. * virmf: (web2c)virmf invocation.               Virgin Metafont.
  34. * virmpost: (web2c)virmpost invocation.         Virgin MetaPost.
  35. * virtex: (web2c)virtex invocation.             Virgin TeX.
  36. * vptovf: (web2c)vptovf invocation.             Virtual pl -> virtual font.
  37. * weave: (web2c)weave invocation.               WEB to TeX.
  38. END-INFO-DIR-ENTRY
  39.   This file documents the installation and use of the programs in Web2c,
  40. an implementation of Donald Knuth's TeX system.
  41.   Copyright (C) 1996, 97 K. Berry & O. Weber.
  42.   Permission is granted to make and distribute verbatim copies of this
  43. manual provided the copyright notice and this permission notice are
  44. preserved on all copies.
  45.   Permission is granted to copy and distribute modified versions of this
  46. manual under the conditions for verbatim copying, provided that the
  47. entire resulting derived work is distributed under the terms of a
  48. permission notice identical to this one.
  49.   Permission is granted to copy and distribute translations of this
  50. manual into another language, under the above conditions for modified
  51. versions, except that this permission notice may be stated in a
  52. translation
  53. File: web2c.info,  Node: Top,  Next: Introduction,  Up: (dir)
  54. Web2c
  55. *****
  56.   This document describes how to install and use the programs in the
  57. Web2c implementation of the TeX system, especially for Unix systems.  It
  58. corresponds to Web2c version 7.2, released in November 1997.
  59. * Menu:
  60. * Introduction::                A brief introduction.
  61. * Installation::                How to compile and install Web2c.
  62. * Commonalities::               Option syntax, standard options, memory dumps.
  63. * TeX::                         Typesetting.
  64. * Metafont::                    Typeface design.
  65. * MetaPost::                    Technical illustrations.
  66. * BibTeX::                      Reusable bibliographies.
  67. * WEB::                         Literate programming.
  68. * DVI utilities::               DVI expansion.
  69. * Font utilities::              Font format conversion.
  70. * Legalisms::                   Blah blah blah.
  71. * References::                  Books and such.
  72. * Index::                       General index.
  73. File: web2c.info,  Node: Introduction,  Next: Installation,  Prev: Top,  Up: Top
  74. Introduction
  75. ************
  76.   This manual corresponds to version 7.2 of Web2c, released in
  77. November 1997.
  78.   "Web2c" is the name of a TeX implementation, originally for Unix, but
  79. now also running under DOS, Amiga, and other operating systems. By "TeX
  80. implementation", we mean all of the standard programs developed by the
  81. Stanford TeX project directed by Donald E. Knuth: Metafont, DVItype,
  82. GFtoDVI, BibTeX, Tangle, etc., as well as TeX itself. Other programs
  83. are also included: DVIcopy, written by Peter Breitenlohner, MetaPost
  84. and its utilities (derived from Metafont), by John Hobby, etc.
  85.   General strategy: Web2c works, as its name implies, by translating the
  86. WEB source in which TeX is written into C source code. Its output is
  87. not self-contained, however; it makes extensive use of many macros and
  88. functions in a library (the `web2c/lib' directory in the sources).
  89. Therefore, it will not work without change on an arbitrary WEB program.
  90.   Availability: All of Web2c is freely available--"free" both in the
  91. sense of no cost (free ice cream) and of having the source code to
  92. modify and/or redistribute (free speech).  (*Note unixtex.ftp:
  93. (kpathsea)unixtex.ftp, for the practical details of how to obtain
  94. Web2c.)  Different parts of the Web2c distribution have different
  95. licensing terms, however, reflecting the different circumstances of
  96. their creation; consult each source file for exact details.  The main
  97. practical implication for redistributors of Web2c is that the
  98. executables are covered by the GNU Public License, and therefore anyone
  99. who gets a binary distribution must also get the sources, as explained
  100. by the terms of the GPL (*note Copying: (kpathsea)Copying.). The GPL
  101. covers the Web2c executables, including `tex', because the Free
  102. Software Foundation sponsored the initial development of the Kpathsea
  103. library that Web2c uses.  The basic source files from Stanford, however,
  104. have their own copyright terms or are in the public domain, and are not
  105. covered by the GPL.
  106.   History: Tomas Rokicki originated the TeX-to-C system in 1987,
  107. working from the first change files for TeX under Unix, which were done
  108. primarily by Howard Trickey and Pavel Curtis. Tim Morgan then took over
  109. development and maintenance for a number of years; the name changed to
  110. Web-to-C somewhere in there.  In 1990, Karl Berry became the
  111. maintainer.  He made many changes to the original sources, and started
  112. using the shorter name Web2c.  In 1997, Olaf Weber took over.  Dozens of
  113. other people have contributed; their names are listed in the
  114. `ChangeLog' files.
  115.   Other acknowledgements: The University of Massachusetts at Boston
  116. (particularly Rick Martin and Bob Morris) has provided computers and ftp
  117. access to me for many years.  Richard Stallman at the Free Software
  118. Foundation employed me while I wrote the original path searching library
  119. (for the GNU font utilities).  (rms also gave us Emacs, GDB, and GCC,
  120. without which I cannot imagine developing Web2c.)  And, of course, TeX
  121. would not exist in the first place without Donald E. Knuth.
  122.   Further reading: *Note References::.
  123. File: web2c.info,  Node: Installation,  Next: Commonalities,  Prev: Introduction,  Up: Top
  124. Installation
  125. ************
  126.   (A copy of this chapter is in the distribution file `web2c/INSTALL'.)
  127.   Installing Web2c is mostly the same as installing any other
  128. Kpathsea-using program.  Therefore, for the basic steps involved, see
  129. *Note Installation: (kpathsea)Installation.  (A copy is in the file
  130. `kpathsea/INSTALL'.)
  131.   One peculiarity to Web2c is that the source distribution comes in two
  132. files: `web.tar.gz' and `web2c.tar.gz'.  You must retrieve and unpack
  133. them both.  (We have two because the former archive contains the very
  134. large and seldom-changing original WEB source files.)  *Note
  135. unixtex.ftp: (kpathsea)unixtex.ftp.
  136.   Another peculiarity is the MetaPost program.  Although it has been
  137. installed previously as `mp', as of Web2c 7.0 the installed name is now
  138. `mpost', to avoid conflict with the `mp' program that does
  139. prettyprinting.  This approach was recommended by the MetaPost author,
  140. John Hobby.  If you as the TeX administrator wish to make it available
  141. under its shorter name as well, you will have to set up a link or some
  142. such yourself.  And of course individual users can do the same.
  143.   For solutions to common installation problems and information on how
  144. to report a bug, see the file `kpathsea/BUGS' (*note Bugs:
  145. (kpathsea)Bugs.).  See also the Web2c home page,
  146. `http://www.tug.org/web2c'.
  147.   Points worth repeating:
  148.    * Before starting the standard compilation and installation you must
  149.      install the basic fonts, macros, and other library files.  *Note
  150.      Installation: (kpathsea)Installation.
  151.    * If you do not wish to use the standard file locations, see *Note
  152.      Changing search paths: (kpathsea)Changing search paths.
  153.    * Some Web2c features are enabled or disabled at `configure' time,
  154.      as described in the first section below.
  155. * Menu:
  156. * configure options::           Especially -with and -enable.
  157. * Compile-time options::        Unusual -D's.
  158. * Additional targets::        Breaking down the task.
  159. * Triptrap::                    Running the torture tests.
  160. * Runtime options::             Array sizes and the like.
  161. File: web2c.info,  Node: configure options,  Next: Compile-time options,  Up: Installation
  162. `configure' options
  163. ===================
  164.   This section gives pointers to descriptions of the `--with' and
  165. `--enable' `configure' arguments that Web2c accepts.  Some are specific
  166. to Web2c, others are generic to all Kpathsea-using programs.
  167.   For a list of all the options `configure' accepts, run `configure
  168. --help'.  The generic options are listed first, and the
  169. package-specific options come last.
  170.   For a description of the generic options (which mainly allow you to
  171. specify installation directories) and basic `configure' usage, see
  172. *Note Running `configure' scripts: (autoconf)Invoking configure, a copy
  173. is in the file `kpathsea/CONFIGURE'.
  174. `--disable-dump-share'
  175.      Do not make fmt/base/mem files sharable across different endian
  176.      architectures.  *Note Hardware and memory dumps::.
  177. `--without-maketexmf-default'
  178. `--without-maketexpk-default'
  179. `--without-maketextfm-default'
  180. `--with-maketextex-default'
  181.      Enable or disable the dynamic generation programs.  *Note mktex
  182.      configuration: (kpathsea)mktex configuration.  The defaults are
  183.      the inverse of the options, i.e., everything is enabled except
  184.      `mktextex'.
  185. `--enable-auto-core'
  186.      Dump `core' if the input file is
  187.      `HackyInputFileNameForCoreDump.tex'.  *Note Preloaded
  188.      executables::.
  189. `--enable-shared'
  190.      Build Kpathsea as a shared library.  *Note Shared library:
  191.      (kpathsea)Shared library.
  192. `--with-editor=CMD'
  193.      Change the default editor invoked by the `e' interactive command.
  194.      *Note Editor invocation::.
  195. `--with-epsfwin'
  196. `--with-hp2627win'
  197. `--with-mftalkwin'
  198. `--with-nextwin'
  199. `--with-regiswin'
  200. `--with-suntoolswin'
  201. `--with-tektronixwin'
  202. `--with-unitermwin'
  203. `--with-x'
  204. `--with-x-toolkit=KIT'
  205. `--with-x11win'
  206. `--with-x11'
  207.      Define Metafont graphics support; by default, no graphics support
  208.      is enabled.  *Note Online Metafont graphics::.
  209. `--x-includes=DIR'
  210. `--x-libraries=DIR'
  211.      Define the locations of the X11 include files and libraries; by
  212.      default, `configure' does its best to guess).  *Note Optional
  213.      Features: (autoconf)Optional Features.  A copy is in
  214.      `kpathsea/CONFIGURE'.
  215. File: web2c.info,  Node: Compile-time options,  Next: Additional targets,  Prev: configure options,  Up: Installation
  216. Compile-time options
  217. ====================
  218.   In addition to the `configure' options listed in the previous
  219. section, there are a few things that can be affected at compile-time
  220. with C definitions, rather than with `configure'.  Using any of these
  221. is unusual.
  222.   To specify extra compiler flags (`-DNAME' in this case), the simplest
  223. thing to do is:
  224.      make XCFLAGS="CCOPTIONS"
  225.    You can also set the `CFLAGS' environment variable before running
  226. `configure'.  *Note configure environment: (kpathsea)configure
  227. environment.
  228. Anyway, here are the possibilities:
  229. `-DFIXPT'
  230. `-DNO_MF_ASM'
  231.      Use the original WEB fixed-point routines for Metafont and MetaPost
  232.      arithmetic calculations regarding fractions.  By default,
  233.      assembly-language routines are used on x86 hardware with GNU C
  234.      (unless `NO_MF_ASM' is defined), and floating-point routines are
  235.      used otherwise.
  236. `-DIPC_DEBUG'
  237.      Report on various interprocess communication activities.  *Note
  238.      IPC and TeX: IPC and TeX.
  239. File: web2c.info,  Node: Additional targets,  Next: Triptrap,  Prev: Compile-time options,  Up: Installation
  240. Additional targets
  241. ==================
  242.   Web2c has several Make targets besides the standard ones.  You can
  243. invoke these either in the top level directory of the source
  244. distribution (the one containing `kpathsea/' and `web2c/'), or in the
  245. `web2c/' directory.
  246. `c-sources'
  247.      Make only the C files, translated from the Web sources, presumably
  248.      because you want to take them to a non-Unix machine.
  249. `formats'
  250. `install-formats'
  251.      Make or install all the memory dumps (*note Memory dumps::.).  By
  252.      default, the standard plain formats plus `latex.fmt' are made.  You
  253.      can add other formats by redefining the `fmts', `bases', and
  254.      `mems' variables.  See the top of `web2c/Makefile' for the
  255.      possibilities.
  256. `fmts'
  257. `install-fmts'
  258.      Make or install the TeX `.fmt' files. *Note initex invocation::.
  259. `bases'
  260. `install-bases'
  261.      Make or install the Metafont `.base' files.  *Note inimf
  262.      invocation::.
  263. `mems'
  264. `install-mems'
  265.      Make or install the MetaPost `.mem' files.  *Note inimpost
  266.      invocation::.
  267. `triptrap'
  268. `trip'
  269. `trap'
  270. `mptrap'
  271.      To run the torture tests for TeX, Metafont, and MetaPost
  272.      (respectively).  See the next section.
  273. File: web2c.info,  Node: Triptrap,  Next: Runtime options,  Prev: Additional targets,  Up: Installation
  274. Trip, trap, and mptrap: Torture tests
  275. =====================================
  276.   To validate your TeX, Metafont, and MetaPost executables, run `make
  277. triptrap'.  This runs the trip, trap, and mptrap "torture tests".  See
  278. the files `triptrap/tripman.tex', `triptrap/trapman.tex', and
  279. `triptrap/mptrap.readme' for detailed information and background on the
  280. tests.
  281.   The differences between your executables' behavior and the standard
  282. values will show up on your terminal.  The usual differences (these are
  283. all acceptable) are:
  284.    * string usage and table sizes;
  285.    * glue set ratios;
  286.    * `down4', `right4', and `y4' commands in DVItype output;
  287.    * dates and times.
  288. Any other differences are trouble. The most common culprit in the past
  289. has been compiler bugs, especially when optimizing.  *Note TeX or
  290. Metafont failing: (kpathsea)TeX or Metafont failing.
  291.   The files `trip.diffs', `mftrap.diffs', and `mptrap.diffs' in the
  292. `triptrap' directory show the standard diffs against the original
  293. output.  If you diff your diffs against these files, you should come up
  294. clean.  For example
  295.      make trip >&mytrip.diffs
  296.      diff triptrap/trip.diffs mytrip.diffs
  297.   To run the tests separately, use the targets `trip', `trap', and
  298. `mptrap'.
  299.   To run simple tests for all the programs as well as the torture tests,
  300. run `make check'.  You can compare the output to the distributed file
  301. `tests/check.log' if you like.
  302. File: web2c.info,  Node: Runtime options,  Prev: Triptrap,  Up: Installation
  303. Runtime options
  304. ===============
  305.   Besides the configure- and compile-time options described in the
  306. previous sections, you can control a number of parameters (in
  307. particular, array sizes) in the `texmf.cnf' runtime file read by
  308. Kpathsea (*note Config files: (kpathsea)Config files.).
  309.   Rather than exhaustively listing them here, please see the last
  310. section of the distributed `kpathsea/texmf.cnf'.  Some of the more
  311. interesting values:
  312. `main_memory'
  313.      Total words of memory available, for TeX, Metafont, and MetaPost.
  314.      Must remake the format file after changing.
  315. `extra_mem_bot'
  316.      Extra space for "large" TeX data structures: boxes, glue,
  317.      breakpoints, et al.  If you use PiCTeX, you may well want to set
  318.      this.
  319. `font_mem_size'
  320.      Words of font info available for TeX; this is approximately the
  321.      total size of all TFM files read.
  322. `hash_extra'
  323.      Additional space for the hash table of control sequence names.
  324.      Approximately 10,000 control sequences can be stored in the main
  325.      hash table; if you have a large book with numerous
  326.      cross-references, this might not be enough, and thus you will want
  327.      to set `hash_extra'.
  328.   Of course, ideally all arrays would be dynamically expanded as
  329. necessary, so the only limiting factor would be the amount of swap space
  330. available.  Unfortunately, implementing this is extremely difficult, as
  331. the fixed size of arrays is assumed in many places throughout the source
  332. code.  These runtime limits are a practical compromise between the
  333. compile-time limits in previous versions, and truly dynamic arrays.  (On
  334. the other hand, the Web2c BibTeX implementation does do dynamic
  335. reallocation of some arrays.)
  336. File: web2c.info,  Node: Commonalities,  Next: TeX,  Prev: Installation,  Up: Top
  337. Commonalities
  338. *************
  339.   Many aspects of the TeX system are the same among more than one
  340. program, so we describe all those pieces together, here.
  341. * Menu:
  342. * Option conventions::   Order doesn't matter, - or -, = or ` ' for values.
  343. * Common options::       -help -version -verbose, and TeX/MF/MP options.
  344. * Path searching::       Features of the common path searching library.
  345. * Output file location:: TEXMFOUTPUT allows output in places other than `.'.
  346. * Three programs::       TeX, Metafont, and MetaPost have a lot in common.
  347. File: web2c.info,  Node: Option conventions,  Next: Common options,  Up: Commonalities
  348. Option conventions
  349. ==================
  350.   To provide a clean and consistent behavior, we chose to have all these
  351. programs use the GNU function `getopt_long_only' to parse command lines.
  352.   As a result, you can:
  353.    * give the options in any order, interspersed as you wish with
  354.      non-option arguments;
  355.    * use `-' or `--' to start an option name;
  356.    * use any unambiguous abbreviation for an option name;
  357.    * separate option names and values with either `=' or one or more
  358.      spaces;
  359.    * use filenames that would otherwise look like options by putting
  360.      them after an option `--'.
  361.   By convention, non-option arguments, if specified, generally define
  362. the name of an input file, as documented for each program.
  363.   If a particular option with a value is given more than once, it is the
  364. last value that counts.
  365.   For example, the following command line specifies the options `foo',
  366. `bar', and `verbose'; gives the value `baz' to the `abc' option, and
  367. the value `xyz' to the `quux' option; and specifies the filename
  368. `-myfile-'.
  369.      -foo --bar -verb -abc=baz -quux karl --quux xyz -- -myfile-
  370. File: web2c.info,  Node: Common options,  Next: Path searching,  Prev: Option conventions,  Up: Commonalities
  371. Common options
  372. ==============
  373.   All of these programs accept the standard GNU `--help' and
  374. `--version' options, and several programs accept `--verbose'.  Rather
  375. than writing identical descriptions in every node, they are described
  376. here.
  377. `--help'
  378.      Print a usage message listing basic usage and all available
  379.      options to standard output, then exit successfully.
  380. `--verbose'
  381.      Print progress reports to standard output.
  382. `--version'
  383.      Print the version number to standard output, then exit
  384.      successfully.
  385.   TeX, Metafont, and MetaPost have additional options in common:
  386. `-kpathsea-debug=NUMBER'
  387.      Set path searching debugging flags according to the bits of NUMBER
  388.      (*note Debugging: (kpathsea)Debugging.).  You can also specify
  389.      this in `KPATHSEA_DEBUG' environment variable (for all Web2c
  390.      programs).  (The command line value overrides.)  The most useful
  391.      value is `-1', to get all available output.
  392. `-ini'
  393.      Enable the "initial" form of the program (*note Initial and
  394.      virgin::.).  This is implicitly set if the program name is `initex'
  395.      resp. `inimf' resp. `inimpost'.
  396. `-interaction=STRING'
  397.      Set the interaction mode from the command line.  The STRING must
  398.      be one of `batchmode', `nonstopmode', `scrollmode', or
  399.      `errorstopmode'.
  400. `-fmt=DUMPNAME'
  401. `-base=DUMPNAME'
  402. `-mem=DUMPNAME'
  403.      Use DUMPNAME instead of the program name or a `%&' line to
  404.      determine the name of the memory dump file read (`fmt' for TeX,
  405.      `base' for Metafont, `mem' for MetaPost).  *Note Memory dumps::.
  406.      Also set the program name to DUMPNAME.  When creating a dump, this
  407.      option will also set the name of the dump file.
  408. `-progname=STRING'
  409.      Set program (and memory dump) name to STRING.  This may affect the
  410.      search paths and other values used (*note Config files:
  411.      (kpathsea)Config files.).  Using this option is equivalent to
  412.      making a link named STRING to the binary and then invoking the
  413.      binary under that name.  *Note Memory dumps::.
  414. File: web2c.info,  Node: Path searching,  Next: Output file location,  Prev: Common options,  Up: Commonalities
  415. Path searching
  416. ==============
  417.   All of the Web2c programs, including TeX, which do path searching use
  418. the Kpathsea routines to do so.  The precise names of the environment
  419. and configuration file variables which get searched for particular file
  420. formatted are therefore documented in the Kpathsea manual (*note
  421. Supported file formats: (kpathsea)Supported file formats.).  Reading
  422. `texmf.cnf' (*note Config files: (kpathsea)Config files.), invoking
  423. `mktex...' scripts (*note mktex scripts: (kpathsea)mktex scripts.), and
  424. so on are all handled by Kpathsea.
  425.   The programs which read fonts make use of another Kpathsea feature:
  426. `texfonts.map', which allows arbitrary aliases for the actual names of
  427. font files; for example, `Times-Roman' for `ptmr8r.tfm'.  The
  428. distributed (and installed by default) `texfonts.map' includes aliases
  429. for many widely available PostScript fonts by their PostScript names.
  430. File: web2c.info,  Node: Output file location,  Next: Three programs,  Prev: Path searching,  Up: Commonalities
  431. Output file location
  432. ====================
  433.   All the programs generally follow the usual convention for output
  434. files.  Namely, they are placed in the directory current when the
  435. program is run, regardless of any input file location; or, in a few
  436. cases, output is to standard output.
  437.   For example, if you run `tex /tmp/foo', for example, the output will
  438. be in `./foo.dvi' and `./foo.log', not `/tmp/foo.dvi' and
  439. `/tmp/foo.log'.
  440.   However, if the current directory is not writable, the main programs
  441. (TeX, Metafont, MetaPost, and BibTeX) make an exception: if the
  442. environment variable or config file value `TEXMFOUTPUT' is set (it is
  443. not by default), output files are written to the directory specified.
  444. This is useful when you are in some read-only distribution directory,
  445. perhaps on a CD-ROM, and want to TeX some documentation, for example.
  446. File: web2c.info,  Node: Three programs,  Prev: Output file location,  Up: Commonalities
  447. Three programs: Metafont, MetaPost, and TeX
  448. ===========================================
  449.   TeX, Metafont, and MetaPost have a number of features in common.
  450. Besides the ones here, the common command-line options are described in
  451. the previous section.  The configuration file options that let you
  452. control some array sizes and other features are described in *Note
  453. Runtime options::.
  454. * Menu:
  455. * Initial and virgin::          Making memory dumps vs. production runs.
  456. * Memory dumps::                .fmt/.base/.mem files for fast startup.
  457. * Editor invocation::           The `e' response at errors.
  458. * \input filenames::            ~ and $ expansion in TeX/MF/MP.
  459. File: web2c.info,  Node: Initial and virgin,  Next: Memory dumps,  Up: Three programs
  460. Initial and virgin
  461. ------------------
  462.   The TeX, Metafont, and MetaPost programs each have two main variants,
  463. called initial and virgin.  As of Web2c 7, one executable suffices for
  464. both variants.
  465.   The initial form is enabled if:
  466.   1. the `-ini' option was specified; or
  467.   2. the program name is `initex' resp. `inimf' resp.  `inimpost'; or
  468.   3. the first line of the main input file is `%&ini';
  469. otherwise, the virgin form is used.
  470.   The "virgin" form is the one generally invoked for production use.
  471. The first thing it does is read a memory dump (*note Determining the
  472. memory dump to use::.), and then proceeds on with the main job.
  473.   The "initial" form is generally used only to create memory dumps (see
  474. the next section).  It starts up more slowly than the virgin form,
  475. because it must do lengthy initializations that are encapsulated in the
  476. memory dump file.
  477.   In the past, there was a third form, "preloaded" executables.  This
  478. is no longer recommended or widely used; but see the section below if
  479. you're interested anyway.  In this case, the memory dump file was read
  480. in to the virgin form, a core dump of the running executable was done,
  481. and the `undump' program run to create a new binary.  Nowadays, reading
  482. memory dumps is fast enough that this is generally no longer worth the
  483. cost in disk space and unshared executables.
  484. * Menu:
  485. * Preloaded executables::
  486. File: web2c.info,  Node: Preloaded executables,  Up: Initial and virgin
  487. Preloaded executables
  488. .....................
  489.   Specifying `--enable-auto-core' to `configure' tells TeX, Metafont,
  490. and MetaPost to suicide with a `SIGQUIT' on an input filename of
  491. `HackyInputFileNameForCoreDump.tex' (all three programs use the `.tex'
  492. suffix). This produces a memory dump of the running executable in a
  493. file `core'.  (This is unrelated to the standard memory dump feature in
  494. these programs; *note Memory dumps::.).
  495.   You don't actually need to do this to produce a core dump.  Just
  496. typing your quit character (usually <CTRL-\>) when the program is
  497. waiting for input (at `**') will have the same result.  But a few sites
  498. want to reliably generate a core dump without human intervention; that's
  499. what `--enable-auto-core' is for.
  500.   With the program `undump', you can use `core' to reconstitute a
  501. "preloaded" executable, which does not need to read a `.fmt' file to
  502. get started.  Although preloaded executables save startup time, they
  503. have a big disadvantage: neither the disk space to store them nor their
  504. code segments (at runtime) can be shared.  Therefore, if both `tex' and
  505. `latex' are running, twice as much memory will be consumed, to the
  506. general detriment of performance.
  507.   The `undump' program is not part of the Web2c distribution, but you
  508. can get it from the CTAN archives as `CTAN:/support/undump', and it is
  509. included in several TeX distributions (*note unixtex.ftp:
  510. (kpathsea)unixtex.ftp.).
  511. File: web2c.info,  Node: Memory dumps,  Next: Editor invocation,  Prev: Initial and virgin,  Up: Three programs
  512. Memory dumps
  513. ------------
  514.   In typical use, TeX, Metafont, and MetaPost require a large number of
  515. macros to be predefined; therefore, they support "memory dump" files,
  516. which can be read much more efficiently than ordinary source code.
  517. * Menu:
  518. * Creating memory dumps::
  519. * Determining the memory dump to use::
  520. * Hardware and memory dumps::
  521. File: web2c.info,  Node: Creating memory dumps,  Next: Determining the memory dump to use,  Up: Memory dumps
  522. Creating memory dumps
  523. .....................
  524.   The programs all create memory dumps in slightly idiosyncratic
  525. (thought substantially similar) way, so we describe the details in
  526. separate sections (references below).  The basic idea is to run the
  527. initial version of the program (*note Initial and virgin::.), read the
  528. source file to define the macros, and then execute the `\dump'
  529. primitive.
  530.   Also, each program uses a different filename extension for its memory
  531. dumps, since although they are completely analogous they are not
  532. interchangeable (TeX cannot read a Metafont memory dump, for example).
  533.   Here is a list of filename extensions with references to examples of
  534. creating memory dumps:
  535.      (`.fmt') *Note initex invocation::.
  536. Metafont
  537.      (`.base') *Note inimf invocation::.
  538. MetaPost
  539.      (`.mem') *Note inimpost invocation::.
  540.   When making memory dumps, the programs read environment variables and
  541. configuration files for path searching and other values as usual.  If
  542. you are making a new installation and have environment variables
  543. pointing to an old one, for example, you will probably run into
  544. difficulties.
  545. File: web2c.info,  Node: Determining the memory dump to use,  Next: Hardware and memory dumps,  Prev: Creating memory dumps,  Up: Memory dumps
  546. Determining the memory dump to use
  547. ..................................
  548.   The virgin form (*note Initial and virgin::.) of each program always
  549. reads a memory dump before processing normal source input.  All three
  550. programs determine the memory dump to use in the same way:
  551.   1. If the first non-option command-line argument begins with `&', the
  552.      program uses the remainder of that argument as the memory dump
  553.      name.  For example, running `tex \&super' reads `super.fmt'.  (The
  554.      backslash protects the `&' against interpretation by the shell.)
  555.   2. If the `-fmt' resp. `-base' resp. `-mem' option is specified, its
  556.      value is used.
  557.   3. If the `-progname' option is specified, its value is used.
  558.   4. If the first line of the main input file (which must be specified
  559.      on the command line, not in response to `**') is `%&DUMP', and
  560.      DUMP is an existing memory dump of the appropriate type, DUMP is
  561.      used.  As a special case, `%&ini' means the initial form of the
  562.      program (*note Initial and virgin::.).
  563.   5. Otherwise, the program uses the program invocation name, most
  564.      commonly `tex' resp. `mf' resp. `mpost'.  For example, if `latex'
  565.      is a link to `tex', and the user runs `latex foo', `latex.fmt'
  566.      will be used.
  567. File: web2c.info,  Node: Hardware and memory dumps,  Prev: Determining the memory dump to use,  Up: Memory dumps
  568. Hardware and memory dumps
  569. .........................
  570.   By default, memory dump files are generally sharable between
  571. architectures of different types; specifically, on machines of different
  572. endianness (*note Byte order: (libc)Byte order.).  (This is a feature
  573. of the Web2c implementation, and is not true of all TeX
  574. implementations.)  If you specify `--disable-dump-share' to
  575. `configure', however, memory dumps will be endian-dependent.
  576.   The reason to do this is speed.  To achieve endian-independence, the
  577. reading of memory dumps on LittleEndian architectures, such as PC's and
  578. DEC architectures, is somewhat slowed (all the multibyte values have to
  579. be swapped).  Usually, this is not noticeable, and the advantage of
  580. being able to share memory dumps across all platforms at a site far
  581. outweighs the speed loss.  But if you're installing Web2c for use on
  582. LittleEndian machines only, perhaps on a PC being used only by you, you
  583. may wish to get maximum speed.
  584.   TeXnically, even without `--disable-dump-share', sharing of `.fmt'
  585. files cannot be guaranteed to work.  Floating-point values are always
  586. written in native format, and hence will generally not be readable
  587. across platforms.  Fortunately, TeX uses floating point only to
  588. represent glue ratios, and all common formats (plain, LaTeX, AMSTeX,
  589. ...) do not do any glue setting at `.fmt'-creation time.  Metafont and
  590. MetaPost do not use floating point in any dumped value at all.
  591.   Incidentally, different memory dump files will never compare equal
  592. byte-for-byte, because the program always dumps the current date and
  593. time. So don't be alarmed by just a few bytes difference.
  594.   If you don't know what endianness your machine is, and you're curious,
  595. here is a little C program to tell you. (The `configure' script
  596. contains a similar program.)  This is from the book `C: A Reference
  597. Manual', by Samuel P. Harbison and Guy L. Steele Jr. (*note
  598. References::.).
  599.      main ()
  600.      {
  601.        /* Are we little or big endian?  From Harbison&Steele.  */
  602.        union
  603.        {
  604.          long l;
  605.          char c[sizeof (long)];
  606.        } u;
  607.        u.l = 1;
  608.        if (u.c[0] == 1)
  609.          printf ("LittleEndian\n");
  610.        else if (u.c[sizeof (long) - 1] == 1)
  611.          printf ("BigEndian\n");
  612.        else
  613.          printf ("unknownEndian");
  614.      
  615.        exit (u.c[sizeof (long) - 1] == 1);
  616.      }
  617. File: web2c.info,  Node: Editor invocation,  Next: \input filenames,  Prev: Memory dumps,  Up: Three programs
  618. Editor invocation
  619. -----------------
  620.   TeX, Metafont, and MetaPost all (by default) stop and ask for user
  621. intervention at an error.  If the user responds with `e' or `E', the
  622. program invokes an editor.
  623.   Specifying `--with-editor=CMD' to `configure' sets the default editor
  624. command string to CMD.  The environment variables/configuration values
  625. `TEXEDIT', `MFEDIT', and `MPEDIT' (respectively) override this.  If
  626. `--with-editor' is not specified, the default is `vi +%d %s'.
  627.   In this string, `%d' is replaced by the line number of the error, and
  628. `%s' is replaced by the name of the current input file.
  629. File: web2c.info,  Node: \input filenames,  Prev: Editor invocation,  Up: Three programs
  630. `\input' filenames
  631. ------------------
  632.   TeX, Metafont, and MetaPost source programs can all read other source
  633. files with the `\input' (TeX) and `input' (MF and MP) primitives:
  634.      \input NAME % in TeX
  635.   The file NAME can always be terminated with whitespace; for Metafont
  636. and MetaPost, the statement terminator `;' also works.  (LaTeX and
  637. other macro packages provide other interfaces to `\input' that allow
  638. different notation; here we are concerned only with the primitive
  639. operation.)  This means that `\input' filenames cannot directly contain
  640. whitespace, even though Unix has no trouble.  Sorry.
  641.   On the other hand, various C library routines and Unix itself use the
  642. null byte (character code zero, ASCII NUL) to terminate strings.  So
  643. filenames in Web2c cannot contain nulls, even though TeX itself does
  644. not treat NUL specially.
  645.   Furthermore, some older Unix variants do not allow eight-bit
  646. characters (codes 128-255) in filenames.
  647.   For maximal portability of your document across systems, use only the
  648. characters `a'-`z', `0'-`9', and `.', and restrict your filenames to at
  649. most eight characters (not including the extension), and at most a
  650. three-character extension.  Do not use anything but simple filenames,
  651. since directory separators vary among systems; instead, add the
  652. necessary directories to the appropriate search path.
  653.   Finally, the present Web2c implementation does `~' and `$' expansion
  654. on NAME, unlike Knuth's original implementation and older versions of
  655. Web2c.  Thus:
  656.      \input ~jsmith/$foo.bar
  657.   will dereference the environment variable or Kpathsea config file
  658. value `foo' and read that file extended with `.bar' in user `jsmith''s
  659. home directory.  (You can also use braces, as in `${foo}bar' if you
  660. want to follow the variable name with a letter, numeral, or `_'.)
  661.   (So you could define an environment variable value including
  662. whitespace and get the program to read such a filename that way, if you
  663. need to.)
  664.   In all the common TeX formats (plain TeX, LaTeX, AMSTeX), the
  665. characters `~' and `~' have special category codes, so to actually use
  666. these in a document you have to change their catcodes or use `\string'.
  667. (The result is unportable anyway, see the suggestions above.)  The
  668. place where they are most likely to be useful is when typing
  669. interactively.
  670. File: web2c.info,  Node: TeX,  Next: Metafont,  Prev: Commonalities,  Up: Top
  671. TeX: Typesetting
  672. ****************
  673.   TeX is a typesetting system: it was especially designed to handle
  674. complex mathematics, as well as most ordinary text typesetting.
  675.   TeX is a batch language, like C or Pascal, and not an interactive
  676. "word processor": you compile a TeX input file into a corresponding
  677. device-independent (DVI) file (and then translate the DVI file to the
  678. commands for a particular output device).  This approach has both
  679. considerable disadvantages and considerable advantages.  For a complete
  680. description of the TeX language, see `The TeXbook' (*note
  681. References::.).  Many other books on TeX, introductory and otherwise,
  682. are available.
  683. * Menu:
  684. * tex invocation::              Invoking TeX.
  685. * initex invocation::           Initial TeX.
  686. * virtex invocation::           Virgin TeX.
  687. * Formats::                     Major TeX macro packages.
  688. * Languages and hyphenation::   TeX supports many human languages.
  689. * IPC and TeX::                 DVI output to a socket.
  690. * TeX extensions::              Changes to the TeX language.
  691. File: web2c.info,  Node: tex invocation,  Next: initex invocation,  Up: TeX
  692. `tex' invocation
  693. ================
  694.   TeX (usually invoked as `tex') formats the given text and commands,
  695. and outputs a corresponding device-independent representation of the
  696. typeset document.  This section merely describes the options available
  697. in the Web2c implementation.  For a complete description of the TeX
  698. typesetting language, see `The TeXbook' (*note References::.).
  699.   TeX, Metafont, and MetaPost process the command line (described here)
  700. and determine their memory dump (fmt) file in the same way (*note
  701. Memory dumps::.).  Synopses:
  702.      tex [OPTION]... [TEXNAME[.tex]] [TEX-COMMANDS]
  703.      tex [OPTION]... \FIRST-LINE
  704.      tex [OPTION]... &FMT ARGS
  705.   TeX searches the usual places for the main input file TEXNAME (*note
  706. Supported file formats: (kpathsea)Supported file formats.), extending
  707. TEXNAME with `.tex' if necessary.  To see all the relevant paths, set
  708. the environment variable `KPATHSEA_DEBUG' to `-1' before running the
  709. program.
  710.   After TEXNAME is read, TeX processes any remaining TEX-COMMANDS on
  711. the command line as regular TeX input.  Also, if the first non-option
  712. argument begins with a TeX escape character (usually `\'), TeX
  713. processes all non-option command-line arguments as a line of regular
  714. TeX input.
  715.   If no arguments or options are specified, TeX prompts for an input
  716. file name with `**'.
  717.   TeX writes the main DVI output to the file `BASETEXNAME.dvi', where
  718. BASETEXNAME is the basename of TEXNAME, or `texput' if no input file
  719. was specified.  A DVI file is a device-independent binary
  720. representation of your TeX document.  The idea is that after running
  721. TeX, you translate the DVI file using a separate program to the
  722. commands for a particular output device, such as a PostScript printer
  723. (*note Introduction: (dvipsk)Top.) or an X Window System display (see
  724. xdvi(1)).
  725.   TeX also reads TFM files for any fonts you load in your document with
  726. the `\font' primitive.  By default, it runs an external program named
  727. `mktextfm' to create any nonexistent TFM files.  You can disable this
  728. at configure-time or runtime (*note mktex configuration:
  729. (kpathsea)mktex configuration.).  This is enabled mostly for the sake
  730. of the EC fonts, which can be generated at any size.
  731.   TeX can write output files, via the `\openout' primitive; this opens
  732. a security hole vulnerable to Trojan horse attack: an unwitting user
  733. could run a TeX program that overwrites, say, `~/.rhosts'.  (MetaPost
  734. has a `write' primitive with similar implications).  To alleviate this,
  735. there is a configuration variable `openout_any', which selects one of
  736. three levels of security.  When it is set to `a' (for "any"), no
  737. restrictions are imposed.  When it is set to `r' (for "restricted"),
  738. filenames beginning with `.' are disallowed (except `.tex' because
  739. LaTeX needs it).  When it is set to `p' (for "paranoid") additional
  740. restrictions are imposed: an absolute filename must refer to a file in
  741. (a subdirectory) of `TEXMFOUTPUT', and any attempt to go up a directory
  742. level is forbidden (that is, paths may not contain a `..'  component).
  743. The paranoid setting is the default.  (For backwards compatibility, `y'
  744. and `1' are synonyms of `a', while `n' and `0' are synonyms for `r'.)
  745.   In any case, all `\openout' filenames are recorded in the log file,
  746. except those opened on the first line of input, which is processed when
  747. the log file has not yet been opened.  (If you as a TeX administrator
  748. wish to implement more stringent rules on `\openout', modifying the
  749. function `openoutnameok' in `web2c/lib/texmfmp.c' is intended to
  750. suffice.)
  751.   The program accepts the following options, as well as the standard
  752. `-help' and `-version' (*note Common options::.):
  753. `-kpathsea-debug=NUMBER'
  754. `-ini'
  755. `-fmt=FMTNAME'
  756. `-progname=STRING'
  757.      These options are common to TeX, Metafont, and MetaPost.  *Note
  758.      Common options::.
  759. `-ipc'
  760. `-ipc-start'
  761.      With either option, TeX writes its DVI output to a socket as well
  762.      as to the usual `.dvi' file.  With `-ipc-start', TeX also opens a
  763.      server program at the other end to read the output.  *Note IPC and
  764.      TeX: IPC and TeX.
  765.      These options are available only if the `--enable-ipc' option was
  766.      specified to `configure' during installation of Web2c.
  767. `-mktex=FILETYPE'
  768. `-no-mktex=FILETYPE'
  769.      Turn on or off the `mktex' script associated with FILETYPE.  The
  770.      only values that make sense for FILETYPE are `tex' and `tfm',
  771. `-mltex'
  772.      If `INITEX' (*note Initial and virgin::.), enable MLTeX extensions
  773.      such as `\charsubdef'.  Implicitly set if the program name is
  774.      `mltex'.  *Note MLTeX: MLTeX.
  775. `-output-comment=STRING'
  776.      Use STRING as the DVI file comment.  Ordinarily, this comment
  777.      records the date and time of the TeX run, but if you are doing
  778.      regression testing, you may not want the DVI file to have this
  779.      spurious difference.  This is also taken from the environment
  780.      variable and config file value `output_comment'.
  781. `-shell-escape'
  782.      Enable the `\write18{SHELL-COMMAND}' feature.  This is also
  783.      enabled if the environment variable or config file value
  784.      `shell_escape' is set to `t'.  (For backwards compatibility, `y'
  785.      and `1' are accepted as synonyms of `t').  It is disabled by
  786.      default to avoid security problems.  When enabled, the
  787.      SHELL-COMMAND string (which first undergoes the usual TeX
  788.      expansions, just as in `\special') is passed to the command shell
  789.      (via the C library function `system').  The output of
  790.      SHELL-COMMAND is not diverted anywhere, so it will not appear in
  791.      the log file.  The system call either happens at `\output' time or
  792.      right away, according to the absence or presence of the
  793.      `\immediate' prefix, as usual for `\write'.  (If you as a TeX
  794.      administrator wish to implement more stringent rules on what can
  795.      be executed, you will need to modify `tex.ch'.)
  796. File: web2c.info,  Node: initex invocation,  Next: virtex invocation,  Prev: tex invocation,  Up: TeX
  797. `initex' invocation
  798. ===================
  799.   `initex' is the "initial" form of TeX, which does lengthy
  800. initializations avoided by the "virgin" (`vir') form, so as to be
  801. capable of dumping `.fmt' files (*note Memory dumps::.).  For a
  802. detailed comparison of virgin and initial forms, *note Initial and
  803. virgin::..
  804.   For a list of options and other information, *note tex invocation::..
  805.   Unlike Metafont and MetaPost, many format files are commonly used with
  806. TeX.  The standard one implementing the features described in the
  807. `TeXbook' is `plain.fmt', also known as `tex.fmt' (again, *note Memory
  808. dumps::.).  It is created by default during installation, but you can
  809. also do so by hand if necessary (e.g., if an update to `plain.tex' is
  810. issued):
  811.      initex '\input plain \dump'
  812. (The quotes prevent interpretation of the backslashes from the shell.)
  813. Then install the resulting `plain.fmt' in `$(fmtdir)'
  814. (`/usr/local/share/texmf/web2c' by default), and link `tex.fmt' to it.
  815.   The necessary invocation for generating a format file differs for each
  816. format, so instructions that come with the format should explain.  The
  817. top-level `web2c' Makefile has targets for making most common formats:
  818. plain latex amstex texinfo eplain.  *Note Formats::, for more details
  819. on TeX formats.
  820. File: web2c.info,  Node: virtex invocation,  Next: Formats,  Prev: initex invocation,  Up: TeX
  821. `virtex' invocation
  822. ===================
  823.   `virtex' is the "virgin" form of TeX, which avoids the lengthy
  824. initializations done by the "initial" (`ini') form, and is thus what is
  825. generally used for production work.  For a detailed comparison of
  826. virgin and initial forms, *note Initial and virgin::..
  827.   For a list of options and other information, see *Note tex
  828. invocation::.
  829. File: web2c.info,  Node: Formats,  Next: Languages and hyphenation,  Prev: virtex invocation,  Up: TeX
  830. Formats
  831. =======
  832.   TeX "formats" are large collections of macros, possibly dumped into a
  833. `.fmt' file (*note Memory dumps::.) by `initex' (*note initex
  834. invocation::.).  A number of formats are in reasonably widespread use,
  835. and the Web2c Makefile has targets to make the versions current at the
  836. time of release.  You can change which formats are automatically built
  837. by setting the `fmts' Make variable; by default, only the `plain' and
  838. `latex' formats are made.
  839.   You can get the latest versions of most of these formats from the CTAN
  840. archives in subdirectories of `CTAN:/macros' (for CTAN info, *note
  841. unixtex.ftp: (kpathsea)unixtex.ftp.).  The archive
  842. `ftp://ftp.tug.org/tex/lib.tar.gz' (also available from CTAN) contains
  843. most of these formats (although perhaps not the absolute latest
  844. version), among other things.
  845. latex
  846.      The most widely used format.  The current release is named `LaTeX
  847.      2e'; new versions are released approximately every six months, with
  848.      patches issued as needed.  The old release was called `LaTeX 2.09',
  849.      and is no longer maintained or supported.  LaTeX attempts to
  850.      provide generic markup instructions, such as "emphasize", instead
  851.      of specific typesetting instructions, such as "use the 10pt
  852.      Computer Modern italic font".
  853. amstex
  854.      The official typesetting system of the American Mathematical
  855.      Society, used to produce nearly all of its publications, e.g.,
  856.      `Mathematical Reviews'.  Like LaTeX, it encourages generic markup
  857.      commands.  The AMS also provides a LaTeX package for authors who
  858.      prefer LaTeX (see the `amslatex' item below).
  859. texinfo
  860.      The documentation system developed and maintained by the Free
  861.      Software Foundation for their software manuals.  It can be
  862.      automatically converted into plain text, a machine-readable
  863.      on-line format called `info', HTML, etc.
  864. eplain
  865.      The "expanded plain" format provides various common features (e.g.,
  866.      symbolic cross-referencing, tables of contents, indexing, citations
  867.      using BibTeX), for those authors who prefer to handle their own
  868.      high-level formatting.
  869. lamstex
  870.      Augments AMSTeX with LaTeX-like features.
  871. amslatex
  872.      An LaTeX package (see `latex' item above), that augments LaTeX
  873.      with AMSTeX-like features.
  874. slitex
  875.      An obsolete LaTeX 2.09 format for making slides.  It is replaced by
  876.      the `slides' document class.
  877. File: web2c.info,  Node: Languages and hyphenation,  Next: IPC and TeX,  Prev: Formats,  Up: TeX
  878. Languages and hyphenation
  879. =========================
  880.   TeX supports most natural languages.  See also *Note TeX extensions:
  881. TeX extensions.
  882. * Menu:
  883. * MLTeX::                Multi-lingual TeX.
  884. * patgen invocation::    Creating hyphenation patterns.
  885. File: web2c.info,  Node: MLTeX,  Next: patgen invocation,  Up: Languages and hyphenation
  886. MLTeX: Multi-lingual TeX
  887. ------------------------
  888.   Multi-lingual TeX (`mltex') is an extension of TeX originally written
  889. by Michael Ferguson and now updated and maintained by Bernd Raichle.
  890. It allows the use of non-existing glyphs in a font by declaring glyph
  891. substitutions.  These are restricted to substitutions of an accented
  892. character glyph, which need not be defined in the current font, by its
  893. appropriate `\accent' construction using a base and accent character
  894. glyph, which do have to exist in the current font.  This substitution
  895. is automatically done behind the scenes, if necessary, and thus MLTeX
  896. additionally supports hyphenation of words containing an accented
  897. character glyph for fonts missing this glyph (e.g., Computer Modern).
  898. Standard TeX suppresses hyphenation in this case.
  899.   MLTeX works at `.fmt'-creation time: the basic idea is to specify the
  900. `-mltex' option to TeX when you `\dump' a format.  Then, when you
  901. subsequently invoke TeX and read that `.fmt' file, the MLTeX features
  902. described below will be enabled.
  903.   Generally, you use special macro files to create an MLTeX `.fmt'
  904. file.  See:
  905.      CTAN:/systems/generic/mltex
  906.      `ftp://ftp.univ-rennes1.fr/pub/GUTenberg/french/'
  907.   The sections below describe the two new primitives that MLTeX defines.
  908. Aside from these, MLTeX is completely compatible with standard TeX.
  909. * Menu:
  910. * \charsubdef::                 Character substitution definitions.
  911. * \tracingcharsubdef::          Tracing substitutions.
  912. File: web2c.info,  Node: \charsubdef,  Next: \tracingcharsubdef,  Up: MLTeX
  913. `\charsubdef': Character substitutions
  914. ......................................
  915.   The most important primitive MLTeX adds is `\charsubdef', used in a
  916. way reminiscent of `\chardef':
  917.      \charsubdef COMPOSITE [=] ACCENT BASE
  918.   Each of COMPOSITE, ACCENT, and BASE are font glyph numbers, expressed
  919. in the usual TeX syntax: `\e symbolically, '145 for octal, "65 for hex,
  920. 101 for decimal.
  921.   MLTeX's `\charsubdef' declares how to construct an accented character
  922. glyph (not necessarily existing in the current font) using two
  923. character glyphs (that do exist).  Thus it defines whether a character
  924. glyph code, either typed as a single character or using the `\char'
  925. primitive, will be mapped to a font glyph or to an `\accent' glyph
  926. construction.
  927.   For example, if you assume glyph code 138 (decimal) for an
  928. e-circumflex and you are using the Computer Modern fonts, which have
  929. the circumflex accent in position 18 and lowercase `e' in the usual
  930. ASCII position 101 decimal, you would use `\charsubdef' as follows:
  931.      \charsubdef 138 = 18 101
  932.   For the plain TeX format to make use of this substitution, you have
  933. to redefine the circumflex accent macro `\^' in such a way that if its
  934. argument is character `e' the expansion `\char138 ' is used instead of
  935. `\accent18 e'.  Similar `\charsubdef' declaration and macro
  936. redefinitions have to be done for all other accented characters.
  937.   To disable a previous `\charsubdef C', redefine C as a pair of zeros.
  938. For example:
  939.      \charsubdef '321 = 0 0  % disable N tilde
  940. (Octal '321 is the ISO Latin-1 value for the Spanish N tilde.)
  941.   `\charsubdef' commands should only be given once.  Although in
  942. principle you can use `\charsubdef' at any time, the result is
  943. unspecified.  If `\charsubdef' declarations are changed, usually either
  944. incorrect character dimensions will be used or MLTeX will output
  945. missing character warnings.  (The substitution of a `\charsubdef' is
  946. used by TeX when appending the character node to the current horizontal
  947. list, to compute the width of a horizontal box when the box gets
  948. packed, and when building the `\accent' construction at
  949. `\shipout'-time.  In summary, the substitution is accessed often, so
  950. changing it is not desirable, nor generally useful.)
  951. File: web2c.info,  Node: \tracingcharsubdef,  Prev: \charsubdef,  Up: MLTeX
  952. `\tracingcharsubdef': Substitution diagnostics
  953. ..............................................
  954.   To help diagnose problems with `\charsubdef', MLTeX provides a new
  955. primitive parameter, `\tracingcharsubdef'.  If positive, every use of
  956. `\charsubdef' will be reported.  This can help track down when a
  957. character is redefined.
  958.   In addition, if the TeX parameter `\tracinglostchars' is 100 or more,
  959. the character substitutions actually performed at `\shipout'-time will
  960. be recorded.
  961. File: web2c.info,  Node: patgen invocation,  Prev: MLTeX,  Up: Languages and hyphenation
  962. Patgen: Creating hyphenation patterns
  963. -------------------------------------
  964.   Patgen creates hyphenation patterns from dictionary files for use with
  965. TeX. Synopsis:
  966.      patgen DICTIONARY PATTERNS OUTPUT TRANSLATE
  967.   Each argument is a filename. No path searching is done. The output is
  968. written to the file OUTPUT.
  969.   In addition, Patgen prompts interactively for other values.
  970.   For more information, see `Word hy-phen-a-tion by com-puter' by Frank
  971. Liang (*note References::.), and also the `patgen.web' source file.
  972.   The only options are `-help' and `-version' (*note Common options::.).
  973. File: web2c.info,  Node: IPC and TeX,  Next: TeX extensions,  Prev: Languages and hyphenation,  Up: TeX
  974. IPC and TeX
  975. ===========
  976.   (Sorry, but I'm not going to write this unless someone actually uses
  977. this feature. Let me know.)
  978.   This functionality is available only if the `--enable-ipc' option was
  979. specified to `configure' during installation of Web2c (*note
  980. Installation::.).
  981.   If you define `IPC_DEBUG' before compilation (e.g., with `make
  982. XCFLAGS=-DIPC_DEBUG'), TeX will print messages to standard error about
  983. its socket operations.  This may be helpful if you are, well, debugging.
  984.