1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
|
[](https://travis-ci.org/wtsnjp/llmk)
[](https://ci.appveyor.com/project/wtsnjp/llmk)
This is yet another build tool for LaTeX 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 LuaTeX 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.
## Basic Usage
The easiest way to use **llmk** is to write the build settings into the LaTeX document itself. The settings can be written as [TOML](https://toml.io) 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:
```latex
% hello.tex
% +++
% latex = "xelatex"
% +++
\documentclass{article}
\begin{document}
Hello \textsf{llmk}!
\end{document}
```
Suppose we save this file as `hello.tex`, then run
```
$ llmk hello.tex
```
will produce a PDF document (`hello.pdf`) with XeLaTeX, since it is specified in the TOML line of the source.
You can find other example LaTeX document files in the [examples](https://github.com/wtsnjp/llmk/tree/master/examples) directory.
### Action Clean/Clobber
Similar to [latexmk](http://personal.psu.edu/jcc8/software/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 `FILE`s. Files removed by these actions can be customized.
## Advanced Usage
### Using llmk.toml
Alternatively, you can write your build settings in an independent file named `llmk.toml` (this file name is fixed).
```toml
# llmk.toml
latex = "lualatex"
source = "hello.tex"
```
If you run llmk without any argument, llmk will load `llmk.toml` in the working directory, and compile files specified by `source` key with the settings written in the file.
```
$ llmk
```
### 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 [TeXShop](https://pages.uoregon.edu/koch/texshop/) 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 [YaTeX mode for Emacs](https://www.yatex.org/). 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 LaTeX 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.
### Custom compile sequence
You can setup custom sequence for processing LaTeX documents; use `sequence` key to specify the order of programs to process the documents and specify the detailed settings for each program.
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:
```toml
# 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.log", "%B.toc", "%B.out", "%B.bbl", "%B.bcf", "%B.blg", "%B-blx.bib", "%B.idx", "%B.ilg", "%B.fls", "%B.run.xml"]`)
* `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"`)
* `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.
```toml
[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 [TeX Development Fund](https://www.tug.org/tc/devfund/) created by the TeX 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.
## License
Copyright 2018-2020 Takuto ASAKURA ([wtsnjp](https://twitter.com/wtsnjp))
This software is licensed under [the MIT license](./LICENSE).
### Third-party software
* [toml.lua](https://github.com/jonstoler/lua-toml): Copyright 2017 Jonathan Stoler. Licensed under [the MIT license](https://github.com/jonstoler/lua-toml/blob/master/LICENSE).
---
Takuto ASAKURA ([wtsnjp](https://twitter.com/wtsnjp))
|
