Usage¶

Getting started¶

cd my-document           # or any subdirectory of it
ktex init                # create ktex.toml, with one target per main .tex file
ktex                     # build the default target

ktex init is optional: without a ktex.toml, ktex builds the only main .tex file of the current directory. A configuration file lets you build from any subdirectory, name several documents, and set options. See ktex init below.

Building¶

ktex                     # default target of ktex.toml, else the only main .tex file of the directory
ktex thesis.tex          # a given file
ktex slides              # the "slides" target of ktex.toml

build is the default subcommand: ktex thesis.tex is the same as ktex build thesis.tex. Without a configuration file, ktex picks the only .tex file of the current directory that contains \documentclass.

Options of ktex build:

Command-line options take precedence over ktex.toml. Paths given on the command line are relative to the current directory.

ktex build -e lualatex -b bibtex -n 2 thesis.tex
ktex -d .                # build in place, the old way
ktex -o ~/thesis.pdf     # write the PDF elsewhere
ktex -v                  # also show the raw output of LaTeX and Biber
ktex -w                  # build, then rebuild on every change

Watch mode¶

With -w/--watch, ktex builds the document, then waits and rebuilds it each time one of its source files changes, until you press Ctrl-C. Keep the PDF open in a viewer that reloads it when it changes. The PDF is only replaced when a build succeeds, so you keep reading the previous version while a build runs or after a failed one.

The watched files are the ones the last build read inside the source directory: the INPUT lines of the .fls file that TeX writes with -recorder (.tex files, local classes and packages, images…), plus the bibliography databases (even outside the source directory), read by Biber or BibTeX outside TeX. Files of the TeX distribution and files produced by the build are not watched. The files are checked twice a second; a change made while a build runs triggers another build right after it.

Limits: a file that the document doesn't read yet (a new chapter that \input refers to but that doesn't exist) is watched only once a build has read it. Changes to ktex.toml are taken into account only when ktex is restarted.

Other commands¶

ktex init

Create a ktex.toml for the LaTeX project of the current directory: the closest directory, from the current one up (without leaving the git repository), that contains main .tex files. It defines one target per main file, the first one being the default target; standalone and subfiles documents are left out. It does nothing if a ktex.toml already applies to the current directory.

ktex check [target]

Re-analyze the log of the last build and rewrite the report, without building anything. With -o FILE, the report goes to another file.

ktex clean [target] [--dry-run] [--keep-logs]

Remove the build directory and the auxiliary files left in the sources. It never touches the sources or the final PDF (see Internals).

ktex corrupt-aux [target]

List the .aux files truncated by an interrupted run.

ktex targets

List the targets of ktex.toml. The first one is the default target.

Files produced¶

With the default prefix output:

• in the build directory: output.1.log, output.2.log… (the raw output of each pass, which the terminal only shows with -v) and output.bib.log;
• next to the sources: the PDF and output.errors.log, the full report.

When there are errors, the terminal only shows the errors, because warnings and undefined references often follow from them. It only details bad boxes with --boxes. The full report always contains everything.

Exit status¶

ktex build returns 0 if the build succeeded. Otherwise it returns a non-zero status and the previous PDF is kept. A configuration error (unknown target, invalid ktex.toml…) returns 2. In watch mode, ktex returns the status of the last build when you stop it.

Language¶

Messages, help and the report are in English, or in French when the locale is French (LANGUAGE, LC_ALL, LC_MESSAGES or LANG, in that order, as with gettext). The KTEX_LANG environment variable takes precedence:

KTEX_LANG=en ktex        # English, whatever the locale
KTEX_LANG=fr ktex        # French

Messages quoted from TeX, LaTeX packages and Biber are left as they are.