Specialities

This section describes features that were added to the MiKTeX implementation of TeX & Friends.

Automatic Package Installation

All MiKTeX programs can be configured in such a way that missing packages are automatically installed (see the section called “Automatic Package Installation”).

It is possible to override the global configuration setting with these command line options:

--disable-installer

Missing packages will not be installed.

--enable-installer

Missing packages will be installed.

Finding out Package Usages

The command line option --record-package-usages can be used to find out which packages are used in a job.

For example, you would say

latex -record-package-usages=packages.txt test

to create the file packages.txt, which contains the names of the packages used by test.tex.

If test.tex looks like this:

\documentclass{scrartcl}
\begin{document}
Hello, world!
\end{document}

Then the resulting packages.txt would contain these lines:

cm
koma-script
ltxbase

The package list can be handed over to the package manager (see mpm(1)), e.g.

mpm --update-some=packages.txt

would ensure that you have the latest versions installed.

Suppressing Screen Output

The option --quiet suppresses all diagnostic messages. No screen output is produced, unless there are errors. The --quiet option implies --c-style-errors and --interaction=batchmode, i.e. errors will be shown in a “C style form and do not stop the compilation process.

For example, the input file foo.tex

\documentclass{article}
\begin{document}
What's \This?
\end{documnt}

would cause TeX to print one error message, as in the following example:

> latex -quiet foo.tex
foo.tex:3: Undefined control sequence
> 

Setting the Name of the Output File

You can change the name of all output files by using the option --job-name=name. This switch actually sets the name of the TeX job and has an effect of the output file names, because these names are derived from the job name. Look at the following example:

> latex -job-name=foo sample2e
This is TeX, Version 3.14159 (MiKTeX 2.2)
(D:\texmf\tex\latex\base\sample2e.tex
LaTeX2e <2001/06/01>
Babel <v3.7h> and hyphenation patterns for english, german, ngerman, loaded.
(D:\texmf\tex\latex\base\article.cls
Document Class: article 2001/04/21 v1.4e Standard LaTeX document class
(D:\texmf\tex\latex\base\size10.clo))
No file foo.aux.
(D:\texmf\tex\latex\base\omscmr.fd) [1] [2] [3] (foo.aux) )
Output written on foo.dvi (3 pages, 7256 bytes).
Transcript written on foo.log.
> 

Note the altered output file names: foo.aux, foo.dvi and foo.log.

Auto-insertion of Source Specials

What Are Source Specials?

Source specials are pieces of information embedded in a DVI file. They make a connection between the source file location (e.g., “line 100 in foo.tex”) and the DVI location (e.g., “page 2 in foo.dvi”). Source specials can improve the edit-compile-view-edit cycle:

  1. You edit the source file with a TeX editor.

  2. You compile the source file.

  3. You execute a special editor command to open the previewer Yap, going directly to the page that corresponds to the cursor location in your editor window.

  4. You navigate through the viewed document.

  5. You double-click somewhere inside the viewed document; this causes Yap to bring the editor window back to the front, moving the text cursor directly to the line that corresponds to the view location.

How to Insert Source Specials

The TeX compiler option --src-specials directs TeX to insert source specials into the DVI file.

You would say

latex -src-specials foo.tex

to create the DVI file foo.dvi with embedded source specials.

Quoted File Names

The TeX compiler can handle quoted file names. This makes it possible to specify long file names that contain spaces.

For example, to compile the input file long file name.tex, you start TeX as follows:

latex "long file name"

This produces the DVI file "long file name.dvi". The log file is named "long file name.log".

You can, to some extent, use quoted file names inside the TeX document. For example:

\input{"extra long file name"}

This would cause TeX to read the file "extra long file name.tex".

Things get a little bit complicated if you want to use the LaTeX primitive \include. You have to write something like the following:

\include{"extra\space long\space file\space name"}

Specifying Additional Input Directories

The command-line option --include-directory=dir causes the program to include dir into the list of input directories.

For example:

latex --include-directory="C:\My Styles" foo.tex

This prepends C:\My Styles to the input search path, i.e., C:\My Styles will be searched first, when TeX tries to find an input file.

Specifying the Output Directory

The option --output-directory=dir causes TeX to create all output files in another directory.

For example:

> mkdir C:\texoutput
> latex -output-directory=C:\texoutput sample2e.tex
...
> 

This ensures that all output files (foo.dvi, foo.log, ) will be created in C:\texoutput\.

Specifying the Directory for Auxiliary Files

The option --aux-directory=dir causes TeX to create auxiliary files in another directory. For example:

> mkdir C:\texoutput
> mkdir C:\tobedeleted
> latex -output-directory=C:\texoutput -aux-directory=C:\tobedeleted foo.tex
...
> 

This ensures that 1) foo.dvi will be created in C:\texoutput\ and 2) all other files (foo.log, ) will be created in C:\tobedeleted\..

Running Programs From Within TeX

\write18

TeX handles output stream 18 in a special way: the token list is interpreted as a command line. If the \write18 feature is enabled (see below), then \write18{toklist} starts the command interpreter (usually cmd.exe) to carry out the command specified by toklist. For example:

\write18{dir}

lists the files and sub-directories of the current directory.

[Note]Note

The \write18 feature is only partially enabled by default to avoid security problems: only well known commands are allowed. You fully enable the feature by specifying --enable-write18 on the TeX command-line.

Piped Input and Output

TeX's input/output primitives can be used for unidirectional interprocess communication by prepending a pipe symbol to the file name.

If this feature is enabled, then \input "|command" starts the command interpreter (usually cmd.exe) to carry out the command. The output of the command becomes the input of TeX. For example:

\input "|dir/b"

typesets the file names of the current directory.

Likewise, it is possible to let TeX write something into the input stream of a command. For example:

\immediate\openout1 = "|unix2dos|sort > sorted"
\immediate\write 1 {b}
\immediate\write 1 {a}
\immediate\write 1 {c}
\immediate\closeout1
\input sorted

typesets a b c.

[Note]Note

Piped input and output is disabled by default to avoid security problems. You enable the feature by specifying --enable-pipes on the TeX command-line.

TCX Files: Character Translations

This section is “borrowed” from the Web2C manual.

TCX (TeX character translation) files help TeX support direct input of 8-bit international characters if fonts containing those characters are being used. Specifically, they map an input (keyboard) character code to the internal TeX character code (a superset of ASCII).

Of the various proposals for handling more than one input encoding, TCX files were chosen because they follow Knuth's original ideas for the use of the xchr and xord tables. He ventured that these would be changed in the WEB source in order to adjust the actual version to a given environment. It turned out, however, that recompiling the WEB sources is not as simple task as Knuth predicted; therefore, TCX files, providing the possibility of changing of the conversion tables on on-the-fly, has been implemented instead.

This approach limits the portability of TeX documents, as some implementations do not support it (or use a different method for input-internal reencoding). It may also be problematic to determine the encoding to use for a TeX document of unknown provenance; in the worst case, failure to do so correctly may result in subtle errors in the typeset output.

While TCX files can be used with any format, using them breaks the LaTeX inputenc package. This is why you should either use tcxfile or inputenc in LaTeX input files, but never both.

This is entirely independent of the MLTeX extension: whereas a TCX file defines how an input keyboard character is mapped to TeX's internal code, MLTeX defines substitutions for a non-existing character glyph in a font with a \accent construction made out of two separate character glyphs. TCX files involve no new primitives; it is not possible to specify that an input (keyboard) character maps to more than one character.

Specifying TCX files:

  • You can specify a TCX file to be used for a particular TeX run by specifying the command-line option -translate-file=tcxfile or (preferably) specifying it explicitly in the first line of the main document:

    %& -translate-file=tcxfile

  • TCX files are searched for along the TCXPath path.

  • initex ignores TCX files.

MiKTeX comes with at least two TCX files, il1-t1.tcx and il2-t1.tcx. These support ISO Latin 1 and ISO Latin 2, respectively, with Cork-encoded fonts (a.k.a.: the T1 encoding). TCX files for Czech, Polish, and Slovak are also provided.

Syntax of TCX files:

  1. Line-oriented. Blank lines are ignored.

  2. Whitespace is ignored except as a separator.

  3. Comments start with % and continue to the end of the line.

  4. Otherwise, a line consists of one or two character codes:

    src [dest]
  5. Each character code may be specified in octal with a leading 0, hexadecimal with a leading 0x, or decimal otherwise. Values must be between 0 and 255, inclusive (decimal).

  6. If the dest code is not specified, it is taken to be the same as src.

  7. If the same src code is specified more than once, it is the last definition that counts.

Finally, here's what happens: when TeX sees an input character with code src: it 1) changes src to dest; and 2) makes code the destprintable”, i.e., printed as-is in diagnostics and the log file instead of in ^^ notation.

By default, no characters are translated, and character codes between 32 and 126 inclusive (decimal) are printable. It is not possible to make these (or any) characters unprintable.

Specifying translations for the printable ASCII characters (codes 32127) will yield unpredictable results. Additionally you shouldn't make the following characters printable: ^^I (TAB), ^^J (line feed), ^^M (carriage return), and ^^? (delete), since TeX uses them in various ways.

Thus, the idea is to specify the input (keyboard) character code for src, and the output (font) character code for dest.