Directory support/light-latex-make

This is yet another build tool for documents. The features of llmk are:

• it works solely with texlua,
• using TOML to declare the settings,
• no complicated nesting of configuration, and
• modern default settings (make Lua de facto standard!)

See the bundled reference manual (llmk.pdf) for the full specification of the program. The following sections are for a quick guidance.

Installation

This software is included in Live and MiK as Package light-latex-make. If you are using one of the latest distributions, you normally don't need to install it by yourself (for Live, please use the tlmgr command to install it, if the package is missing).

In case the package is not installed in your system or you want to use the latest (development) version of the program, you have to install it manually. You can acquire any material related to this software from our GitHub repository. The installation procedure is very simple anyway because the llmk.lua is the standalone executable. Running texlua <path>/llmk.lua should work in any case. In UNIX-like systems, the easiest way to install the program is copy or symlink the file llmk.lua as llmk in any place in the PATH.

Basic Usage

The most simple way to use llmk is to write the build settings into the document itself. The settings can be written as TOML format in comments of a source file, and those have to be placed between the comment lines only with the consecutive + characters (at least three).

Here's a very simple example:

% hello.tex

% +++
% latex = "xelatex"
% +++

\documentclass{article}
\begin{document}

Hello \textsf{llmk}!

\end{document}


Suppose we save this file as hello.tex, then run

Supports for other magic comment formats

A few other magic comment formats that are supported by existing tools are also supported by llmk.

The directives supported by Shop and friends, which typically start with % !TEX, can be used instead of latex and bibtex keys. E.g.,

%! TEX TS-program = xelatex
%! BIB TS-program = biber
\documentclass{article}


is equivalent to:

% +++
% latex = "xelatex"
% bibtex = "biber"
% +++
\documentclass{article}


Another supported format is shebang-like directive that is supported by Ya mode for Emacs. E.g.,

%#!pdflatex
\documentclass{article}


is equivalent to:

% +++
% latex = "pdflatex"
% +++
\documentclass{article}


Note that this magic comment is effective only on the first line of a source file. Note also that if a TOML field exist in the file, the TOML field has higher priority and all the other magic comments will be ignored.

Action Clean/Clobber

Similar to latexmk, Actions --clean (-c) and --clobber (-C) are available.

• The --clean action removes temporary files such as *.aux and *.log.
• The --clobber action removes all generated files including final PDFs.

Specifically,

\$ llmk --clean FILE...

removes files generated by the specified FILEs. In case you omit the argument FILE, files generated by the source files are removed. In both cases, the files to remove by these actions can be customized (see the reference manual for the details).

Custom compile sequence

You can setup custom sequence for processing documents; use sequence key to specify the order of programs to process the documents and specify the detailed settings for each program in the programs table.

For the simple use, you can specify the command name in the top-level just like latex = "lualatex", which is already shown in the former examples.

However, it is impossible to specify more detailed settings (e.g., command-line options) with this simple manner. If you want to change those settings as well, you have to use tables of TOML; write [programs.<name>] and then write the each setting following to that:

# custom sequence
sequence = ["latex", "bibtex", "latex", "dvipdf"]

# quick settings
dvipdf = "dvipdfmx"

# detailed settings for each program
[programs.latex]
command = "uplatex"
opts = ["-halt-on-error"]
args = ["%T"]

[programs.bibtex]
command = "biber"
args = ["%B"]

In the args keys in each program, some format specifiers are available. Those specifiers will be replaced to appropriate strings before executing the programs:

• %S: the file name given to llmk as an argument (source)
• %T: the target for each program
• %B: the base name of %S

This way is a bit complicated but strong enough allowing you to use any kind of outer programs.

Available TOML keys

The following is the list of available TOML keys in llmk. See the reference manual for the details.

• bibtex (type: string, default: "bibtex")
• clean_files (type: string or array of strings, default: ["%B.aux", "%B.bbl", "%B.bcf", "%B-blx.bib", "%B.blg", "%B.fls", "%B.idx", "%B.ilg", "%B.ind", "%B.log", "%B.nav", "%B.out", "%B.run.xml", "%B.snm", "%B.toc", "%B.vrb"])
• clobber_files (type: string or array of strings, default: ["%B.pdf", "%B.dvi", "%B.ps", "%B.synctex.gz"])
• dvipdf (type: string, default: "dvipdfmx")
• dvips (type: string, default: "dvips")
• extra_clean_files (type: string or array of strings, default: [])
• latex (type: string, default: "lualatex")
• llmk_version (type: string)
• makeindex (type: string, default: "makeindex")
• max_repeat (type: integer, default: 5)
• programs (type: table)
• <program name>
• args (type: string or array of strings, default: ["%T"])
• aux_file (type: string)
• aux_empty_size (type: integer)
• command (type: string, required)
• generated_target (type: boolean, default: false)
• opts (type: string or array of strings)
• postprocess (type: string)
• target (type: string, default: "%S")
• ps2pdf (type: string, default: "ps2pdf")
• sequence (type: array of strings, default: ["latex", "bibtex", "makeindex", "dvipdf"])
• source (type: string or array of strings, only for llmk.toml)

Default programs table

The following is the default values in the programs table in TOML format.

[programs.bibtex]
command = "bibtex"
target = "%B.bib"
args = ["%B"]
postprocess = "latex"

[programs.dvipdf]
command = "dvipdfmx"
target = "%B.dvi"
generated_target = true

[programs.dvips]
command = "dvips"
target = "%B.dvi"
generated_target = true

[programs.latex]
command = "lualatex"
opts = ["-interaction=nonstopmode", "-file-line-error", "-synctex=1"]
aux_file = "%B.aux"
aux_empty_size = 9

[programs.makeindex]
command = "makeindex"
target = "%B.idx"
generated_target = true
postprocess = "latex"

[programs.ps2pdf]
command = "ps2pdf"
target = "%B.ps"
generated_target = true

Acknowledgements

This project has been supported by the Development Fund created by the Users Group (No. 29). I would like to thank all contributors and the people who gave me advice and suggestions for new features for the llmk project.

Third-party software

Takuto ASAKURA (wtsnjp)