diff options
Diffstat (limited to 'support/lua/llmk/README.md')
-rw-r--r-- | support/lua/llmk/README.md | 236 |
1 files changed, 236 insertions, 0 deletions
diff --git a/support/lua/llmk/README.md b/support/lua/llmk/README.md new file mode 100644 index 0000000000..9b6c51325a --- /dev/null +++ b/support/lua/llmk/README.md @@ -0,0 +1,236 @@ +![llmk: The Light LaTeX Make](./llmk-logo.png) + +[![Build Status](https://travis-ci.org/wtsnjp/llmk.svg?branch=master)](https://travis-ci.org/wtsnjp/llmk) +[![Build status](https://ci.appveyor.com/api/projects/status/1papc7m85kl9iph1?svg=true)](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)) |