summaryrefslogtreecommitdiff
path: root/support/light-latex-make/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'support/light-latex-make/README.md')
-rw-r--r--support/light-latex-make/README.md236
1 files changed, 236 insertions, 0 deletions
diff --git a/support/light-latex-make/README.md b/support/light-latex-make/README.md
new file mode 100644
index 0000000000..9b6c51325a
--- /dev/null
+++ b/support/light-latex-make/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))