summaryrefslogtreecommitdiff
path: root/support/light-latex-make/llmk.tex
diff options
context:
space:
mode:
Diffstat (limited to 'support/light-latex-make/llmk.tex')
-rw-r--r--support/light-latex-make/llmk.tex908
1 files changed, 908 insertions, 0 deletions
diff --git a/support/light-latex-make/llmk.tex b/support/light-latex-make/llmk.tex
new file mode 100644
index 0000000000..2bb140dc0e
--- /dev/null
+++ b/support/light-latex-make/llmk.tex
@@ -0,0 +1,908 @@
+% llmk: the reference manual
+% Copyright 2020 Takuto ASAKURA (wtsnjp)
+
+% +++
+% latex = "xelatex"
+% +++
+\documentclass[draft]{llmk-doc}
+
+% Metadata
+\title{llmk: Light {\LaTeX} Make}
+\author{Takuto Asakura (wtsnjp)}
+\subtitle{Reference Manual}
+\date{v0.1.0\quad\today}
+\keywords{llmk, build-tool, toml, lua, luatex}
+
+\begin{document}
+
+\maketitle
+
+\section{Overview}
+
+The \prog{llmk} program is yet another build tool specific for {\LaTeX}
+documents. Its aim is to provide a simple way to specify a workflow of
+processing {\LaTeX} documents and encourage people to always explicitly show
+the right workflow for each document.
+
+The main features of \prog{llmk} are all about the above purpose. First, you
+can write the workflows either in an external file \code{llmk.toml} or in a
+{\LaTeX} document source in a form of magic comments. Further, multiple magic
+comment formats can be used. Second, it is fully cross-platform. The only
+requirement of the program is the \code{texlua} command; \prog{llmk} makes a
+uniform way to describe the workflows available for nearly all {\TeX}
+environments. Third, it behaves exactly the same in any environment. At this
+point, \prog{llmk} intentionally does not provide any method for user
+configuration. Therefore, one can guarantee that a {\LaTeX} document with an
+\prog{llmk} setup, the process of typesetting the document must be reproduced
+in any {\TeX} environment with the program.
+
+% TODO: explain that llmk is included in TeX Live and MiKTeX when ready
+
+\subsection{Learning \prog{llmk}}
+
+The bundled \href{https://github.com/wtsnjp/llmk/blob/master/README.md}
+{\code{README.md}} has a general introduction for the program. If you are new
+to \prog{llmk} and looking for a quick guidance, you are recommended to read it
+first. Conversely, this document can be regarded as a reference manual: it
+contains detailed descriptions for every feature of \prog{llmk} as much as
+possible, but unsuitable for getting general ideas of its basic usage.
+
+\begin{samepage}
+All official resources are available from the repository on GitHub:
+%
+\begin{quote}
+\url{https://github.com/wtsnjp/llmk}
+\end{quote}
+%
+Notably, you can find some example {\LaTeX} documents with \prog{llmk} setups
+in the \href{https://github.com/wtsnjp/llmk/tree/master/examples}
+{\code{examples}} directory.
+% TODO: mention wiki on github when some contents are gathered?
+\end{samepage}
+
+The design concept of \prog{llmk} is described in a separate TUGboat
+article~\cite{asakura2020}. It will not give you practical tips, but if you are
+interested in the underlying ideas of the program, it should be worth reading.
+The differences from other similar tools, \eg\prog{latexmk}~\cite{latexmk} and
+\prog{arara}~\cite{arara}, are also discussed in the article.
+
+\subsection{Reporting bugs and requesting features}
+
+If you get trouble with \prog{llmk} or think you have found a bug, please
+report it by creating either an issue or a pull request on the GitHub
+repository:
+%
+\begin{quote}
+\url{https://github.com/wtsnjp/llmk/issues}
+\end{quote}
+%
+If you do not want to use GitHub for some reasons, it is also fine to directly
+send an email to the author (\email{tkt.asakura@gmail.com}).
+
+The \prog{llmk} program is currently version \code{0.x} and still growing in
+any aspect. At this moment, requests for new features are also welcome; the
+author cannot promise to implement the requested features, but will happy to
+take them into account. Before making a request, it is strongly recommended to
+read the article about the design concept~\cite{asakura2020}.
+
+One more thing: as you can see, the author of the program is not a native
+English speaker. Thus, there should be plenty of grammatical errors and
+unnatural sentences in the documentation, including this manual itself.
+Correction for such writing issues is particularly welcome.
+
+\section{Command-line interface}
+
+\subsection{Command usage}
+\label{sec:command}
+
+The full usage of \prog{llmk} can be summarized as follows:
+%
+\begin{htcode}
+llmk \meta{options} \meta{files}
+\end{htcode}
+
+Herein, \meta{options} are the command-line options, that start with the hyphen
+character |-|, and \meta{files} are the arguments for the |llmk| command.
+
+\subsubsection*{Arguments \meta{files}}
+
+You can specify the filenames of the source {\TeX} files, normally the files
+with \code{.tex} or \code{.ltx} extensions, as the arguments for the \code{llmk}
+command. When one or more \meta{files} are specified, \prog{llmk} will read
+either the TOML field (Section~\ref{sec:toml}) or another supported magic
+comment (Section~\ref{sec:magic-comment}) in each of the source files and
+process it with the specified workflow in the given order.
+
+As well as the \code{tex} command, you can omit the \code{.tex} extensions and
+just give the basenames of the files for the argument; when a \meta{basename},
+which must not contain any dot character, is given and the file that exactly
+matches to the name does not exist, \prog{llmk} will automatically add the
+\code{.tex} extension and process it like any other if the file
+|\meta{basename}.tex| exists.
+
+Note that \prog{llmk} naively pass the given filenames to invoked commands.
+Filenames that contains special characters of {\TeX}, \eg |#| and |%|, are very
+likely to be causes of troubles. Moreover, at this point \prog{llmk} does not
+any specific features to take care of multi-byte characters: filenames
+including multi-byte characters may work in some cases but can be cause of
+problems\footnote{The author admits that \prog{llmk} needs to be enhanced in
+this aspect: it should have better features to treat various filenames with
+multi-byte characters, though the author is negative to support special
+characters of {\TeX}. Suggestions and patches in this direction are especially
+welcome.}. Using filenames that contain only the characters in the range of the
+ASCII code, except special characters of {\TeX}, is the safest way to go at any
+rate.
+
+Alternatively, if the argument is not specified, \prog{llmk} will read the
+special TOML file \code{llmk.toml} in the working directory and execute the
+workflow specified in the file (see Section~\ref{sec:toml}). In case the
+argument is not specified and the \code{llmk.toml} does not exist, it will
+result in an error. When \prog{llmk} executes the workflow specified in the
+file \code{llmk.toml}, all magic comments, including TOML fields and other
+formats, in each source {\LaTeX} files specified in the \ckey{source} array
+will be ignored.
+
+\subsubsection*{Command-line options \meta{options}}
+
+We have tried to implement a GNU-compatible option parser. Short options, each of
+which consists of a single letter, must start with a single hyphen |-|.
+Multiple short options can be specified with a single hyphen, \eg |-vs| is
+equivalent to |-v -s|. Long options have to be following double hyphens |--|.
+All options must be specified before the first argument. A string beginning
+with a hyphen after the first argument will be treated as an argument starting
+with a hyphen.
+
+When two or more options are specified, \prog{llmk} applies them in the given
+order. If contradicting options are specified, \eg \sopt{q} v.s.\ \sopt{v}, the
+option in the latter position wins over the former one.
+
+The following is the full list of available command-line options:
+
+\begin{clopt}{\sopt{c}, \lopt{clean}}
+Removes temporary files such as \code{aux} and \code{log} files. The files
+removed with this action can be customized with the key \ckey{clean\_files}.
+\end{clopt}
+
+\begin{clopt}{\sopt{C}, \lopt{clobber}}
+Removes all generated files including final PDFs. The files removed with this
+action can be customized with the key \ckey{clobber\_files}.
+\end{clopt}
+
+\begin{clopt}{%
+ \code{\sopt{d} \meta{category}}, \code{\lopt{debug}=\meta{category}},
+ \sopt{D}, \lopt{debug}}
+Activates the specified debug category; debugging messages related to the
+activated category will be shown. Herein, available debug categories are:
+|config|, |parser|, |run|, |fdb|, |programs|, and |all| to activate all of
+these. You can repeat this option more than once to activate multiple
+categories. If you specify |-D| or |--debug| without the argument
+\meta{category}, it activates all available debug categories.
+\end{clopt}
+
+\begin{clopt}{\sopt{h}, \lopt{help}}
+Shows a quick help message (namely a list of command-line options) and exit
+successfully. When this is specified, all other options and arguments are
+ignored.
+\end{clopt}
+
+\begin{clopt}{\sopt{q}, \lopt{quiet}}
+This suppress most of the messages from the program.
+\end{clopt}
+
+\begin{clopt}{\sopt{s}, \lopt{silent}}
+Silence messages from invoked programs. To be more specific, this redirects
+both standard output and standard error streams to the null device.
+\end{clopt}
+
+\begin{clopt}{\sopt{v}, \lopt{verbose}}
+Make \prog{llmk} to print additional information such as invoked commands
+with options and arguments by the program.
+\end{clopt}
+
+\begin{clopt}{\sopt{V}, \lopt{version}}
+Shows the current version of the program and exit successfully. When this is
+specified, all other options and arguments are ignored.
+\end{clopt}
+
+\subsection{Exit codes}
+
+You can grasp whether \prog{llmk} successfully executed or not by seeing its
+status code. Note that the exit codes of invoked programs are not directly
+transferred as the exit code of \prog{llmk}; instead, the statuses of external
+programs that failed, if any, are reported in the error messages.
+%
+\begin{description}[left=2em]
+\item[\code{0}]
+ Success.
+\item[\code{1}]
+ General error.
+\item[\code{2}]
+ Invoked program failed.
+\item[\code{3}]
+ Parser error.
+\item[\code{4}]
+ Type error.
+\end{description}
+
+\section{Writing workflows in TOML format}
+\label{sec:toml}
+
+The primary configuration format for \prog{llmk} is TOML\Dash Tom's Obvious
+Minimal Language~\cite{toml}. You can specify the workflows to process your
+{\LaTeX} documents in the format either in the special configuration file
+(\code{llmk.toml}) or in the TOML field (Section~\ref{sec:toml-where}). You
+have full access to the \prog{llmk} configuration with this primary format,
+while other supported magic comment formats (Section~\ref{sec:magic-comment})
+have only partial access. You can read the entire TOML specification at
+\href{https://toml.io/}{its website}.
+
+\subsection{TOML in \prog{llmk}}
+
+The configuration for \prog{llmk} written in the TOML format is read by our
+built-in parser. At this point, the built-in parser supports a subset of the
+TOML specification; only the data-types that necessary for the configuration
+keys (Section~\ref{sec:top-level-keys}~\&~\ref{sec:keys-in-programs}) are
+supported.
+
+\begin{center}
+\newcommand{\ok}{{\color{special}\checkmark}}
+\begin{tabular}{llc}
+\toprule
+Type & Example & Supported \\ \midrule
+Bare keys & \code{key} & \ok \\
+Quoted keys & \code{"key"} & \\
+Dotted keys & \code{tex.latex} & \ok \\ \midrule
+Basic strings & \code{"str"} & \ok \\
+Multi-line basic strings & & \\
+Literal strings & \code{'str'} & \ok \\
+Multi-line literal strings & & \\ \midrule
+Integer & \code{123} & \ok \\ \midrule
+Boolean & \code{true} & \ok \\ \midrule
+Float & \code{3.14} & \\ \midrule
+Date \& Time & \code{1979-05-27} & \\ \midrule
+Array & \code{[1, 2, 3]} & \ok \\ \midrule
+Table & \code{[table]} & \ok \\
+Inline table & & \\
+Array of tables & \code{[[fruit]]} & \\
+\bottomrule
+\end{tabular}
+\end{center}
+
+\subsection{Where to write}
+\label{sec:toml-where}
+
+You have two options to write the configuration for \prog{llmk} in TOML format:
+(1)~creating a special file \code{llmk.toml} and (2)~writing a TOML field in
+your {\LaTeX} source file. Either way, you have full access to the \prog{llmk}
+configuration and specify the same workflows in (almost) the same manner.
+
+\subsubsection*{Special file: \code{llmk.toml}}
+
+When the \code{llmk} command is executed without any argument, the special file
+\code{llmk.toml} is loaded automatically (Section~\ref{sec:command}). This
+filename is fixed and cannot be customized at this point. The entire content of
+the file must be a valid TOML; you can include supplemental information in the
+form of TOML comment that starts with the \code{\#} character. The file must
+be encoded in UTF-8 because it is required by the TOML
+specification~\cite{toml}. The \ckey{source} key is \emph{required} in this
+file.
+
+\subsubsection*{TOML field}
+
+The other way to pass the configuration in TOML format to \prog{llmk} is using
+\emph{TOML fields}\Dash special comment areas in {\LaTeX} source files that are
+given by comment lines containing only three or more consecutive \code{+}
+characters. The following is a simple example.
+%
+\begin{lstlisting}[style=latex]
+% +++
+% # This is a sample TOML field!
+% latex = "xelatex"
+% +++
+\documentclass{article}
+\end{lstlisting}
+
+The formal syntax of opening and closing for TOML fields is:
+%
+\begin{htcode}
+\meta{optional spaces}%\meta{optional spaces}+++\meta{optional pluses}\meta{optional spaces}
+\end{htcode}
+%
+where the definitions of \meta{optional spaces} and \meta{optional pluses} are
+given as follows (hereafter, whitespace \code{\textvisiblespace} denotes tab
+\texttt{0x09} or space \texttt{0x20}).
+%
+\begin{align*}
+&\text{\meta{optional spaces}}
+ \longrightarrow \text{\meta{empty}}
+ \mid\text{\code{\textvisiblespace}\meta{optional spaces}} \\
+&\text{\meta{optional pluses}}
+ \longrightarrow \text{\meta{empty}}
+ \mid\text{\code{+}\meta{optional pluses}}
+\end{align*}
+
+The line of opening and closing for TOML fields must include only the
+characters specified in the above. In a TOML filed, you can write TOML code for
+\prog{llmk} configuration in the form of {\LaTeX} comment lines.
+%
+\begin{htcode}
+\meta{optional spaces}%\meta{optional spaces}\meta{TOML line}\meta{optional spaces}
+\end{htcode}
+
+If one or more arguments are given for the \code{llmk} command, it first looks
+for a TOML field from the beginning of each file. Only the topmost field in a
+file is the valid TOML field, \ie you cannot have multiple TOML fields in a
+file. TOML fields have the highest priority for \prog{llmk} configuration; if a
+TOML field is found in a file, other supported magic comments described in
+Section~\ref{sec:magic-comment} are ignored.
+
+Though the author recommend you to always encode your {\LaTeX} source file in
+UTF-8, you can use other encodings. In any case, the TOML lines in the fields
+must be consist of valid UTF-8 encoded strings. Therefore, it is recommended to
+use only the characters in the range of ASCII code in your TOML field if you
+chose the other encodings for some reasons.
+
+\subsection{Available top-level keys}
+\label{sec:top-level-keys}
+
+Now we are going to look over all available TOML keys for \prog{llmk}
+configuration. This section includes the full list of available top-level keys,
+that are effective for an entire workflow. The detailed specification for each
+program in your workflow can be given by the keys in the \ckey{programs} table,
+which will be described in the next section. Only the keys shown in these two
+sections are effective for \prog{llmk}; if other key names are specified, they
+will be ignored. Each key requests a value of specified type; if a value of
+which is not the expected type, it will result in a type error.
+
+In the string values for some specific keys, a few \emph{format specifiers} are
+available. These specifiers will be replaced to appropriate strings before
+executing actions by \prog{llmk}:
+%
+\begin{itemize}
+\item |%S|
+ is replaced by the filename given to the \code{llmk} as a command-line
+ argument or as an element of the \ckey{source} array.
+\item |%T|
+ is replaced by the target for each program.
+\item |%B|
+ is replaced by the basename of |%S|.
+\end{itemize}
+
+Some keys have default values; the default configuration of \prog{llmk} should
+work well for typical and simple {\LaTeX} documents. Only the keys you
+explicitly specify in the TOML format override the default configuration. If
+you do not write a key in your configuration, the default value will be used.
+In other words, you only need to write the differences from the default
+configuration.
+
+\begin{confkey}{bibtex}{type: \type{string}}[default: \code{"bibtex"}]
+The command to use for the \progname{bibtex} program. Internally, this key is
+an alias for the \ckey{command} key in the \progname{bibtex} entry. If the
+\ckey{command} key is specified in the \ckey{programs} table, this alias is
+ineffective.
+\end{confkey}
+
+\begin{confkey}{clean\_files}{type: \type{array of strings}}
+ [default: see bellow]
+The files to be removed with the cleaning action (\lopt{clean}). The format
+specifiers are available for this key. The default value is:
+%
+\begin{htcode}
+[
+ "%B.aux", "%B.bbl", "%B.bcf", "%B-blx.bib", "%B.blg", "%B.fls",
+ "%B.idx", "%B.ilg", "%B.log", "%B.out", "%B.run.xml", "%B.toc"
+]
+\end{htcode}
+\end{confkey}
+
+\begin{confkey}{clobber\_files}{type: \type{array of strings}}
+ [default: see bellow]
+The files to be removed with the clobbering action (\lopt{clobber}). The format
+specifiers are available for this key. The default value is:
+%
+\begin{htcode}
+["%B.dvi", "%B.pdf", "%B.ps", "%B.synctex.gz"]
+\end{htcode}
+\end{confkey}
+
+\begin{confkey}{dvipdf}{type: \type{string}}[default: \code{"dvipdfmx"}]
+The command to use for the \progname{dvipdf} program. Internally, this key is
+an alias for the \ckey{command} key in the \progname{dvipdf} entry. If the
+\ckey{command} key is specified in the \ckey{programs} table, this alias is
+ineffective.
+\end{confkey}
+
+\begin{confkey}{dvips}{type: \type{string}}[default: \code{"dvips"}]
+The command to use for the \progname{dvips} program. Internally, this key is an
+alias for the \ckey{command} key in the \progname{dvips} entry. If the
+\ckey{command} key is specified in the \ckey{programs} table, this alias is
+ineffective.
+\end{confkey}
+
+\begin{confkey}{latex}{type: \type{string}}[default: \code{"lualatex"}]
+The command to use for the \progname{latex} program. Internally, this key is an
+alias for the \ckey{command} key in the \progname{latex} entry. If the
+\ckey{command} key is specified in the \ckey{programs} table, this alias is
+ineffective.
+\end{confkey}
+
+\begin{confkey}{llmk\_version}{type: \type{string}}
+You can declare the \prog{llmk} version to use with this key. This is
+especially useful in consideration of compatibility. In case breaking changes
+are made in the future updates and an incompatible version is declared with the
+key, \prog{llmk} will fallback to the previous behavior or at least show you a
+warning message. The versioning of \prog{llmk} will try to follow the semantic
+versioning~\cite{semvar} and you can specify one of the versions in the
+following syntax:
+%
+\begin{htcode}
+\meta{major}.\meta{minor}.\meta{patch}
+\end{htcode}
+%
+Optionally, you can ommit the tailing \code{.\meta{patch}} part.
+\end{confkey}
+
+\begin{confkey}{makeindex}{type: \type{string}}[default: \code{"makeindex"}]
+The command to use for the \progname{makeindex} program. Internally, this key
+is an alias for the \ckey{command} key in the \progname{makeindex} entry. If
+the \ckey{command} key is specified in the \ckey{programs} table, this alias is
+ineffective.
+\end{confkey}
+
+\begin{confkey}{max\_repeat}{type: \type{integer}}[default: \code{5}]
+You can specify the maximum number of execution repetitions for each command in
+your \ckey{sequence}. When processing your \ckey{sequence}, \prog{llmk} repeats
+a command until \ckey{aux\_file} becomes unchanged from the former execution if
+the key is specified and the corresponding auxiliary file exists. This key is to
+prevent the potential infinite loop of repetition.
+\end{confkey}
+
+\begin{confkey}{programs}{type: \type{table}}
+ [default: see Section~\ref{sec:default-programs}]
+The table that contains the detailed configuration for each program. See
+Section~\ref{sec:keys-in-programs} for the details.
+\end{confkey}
+
+\begin{confkey}{ps2pdf}{type: \type{string}}[default: \code{"ps2pdf"}]
+The command to use for the \progname{ps2pdf} program. Internally, this key is
+an alias for the \ckey{command} key in the \progname{ps2pdf} entry. If the
+\ckey{command} key is specified in the \ckey{programs} table, this alias is
+ineffective.
+\end{confkey}
+
+\begin{confkey}{sequence}{type: \type{array of strings}}
+ [default: see Section~\ref{sec:default-sequence}]
+The array that contains the names of programs that will be executed by
+\prog{llmk}. The programs specified in this array are processed in the given
+order with the setups specified in the \ckey{programs} table. Further
+information about the default behavior can be found in
+Section~\ref{sec:default-sequence}.
+\end{confkey}
+
+\begin{confkey}{source}{type: \type{string} or \type{array of strings}}
+You can specify a {\LaTeX} source file as a \type{string} value or one or more
+files as an \type{array of strings}. This key is only effective and
+\emph{required} in \code{llmk.toml}. Conversely, ineffective in TOML fields.
+The given filenames will be treated as well as those specified as command-line
+arguments.
+\end{confkey}
+
+\subsection{Available keys in \code{programs} table}
+\label{sec:keys-in-programs}
+
+As it is described, \prog{llmk} invokes each program whose name specified in
+the \ckey{sequence} array in the given order. You can control each program
+execution by specifying the detailed configuration in the \ckey{programs}
+table.
+
+The \ckey{programs} table is a table of tables; each of the entries (\aka
+elements) is a set of configuration consists of the keys in the following list.
+The \ckey{programs} table must have corresponding entries for all names in the
+\ckey{sequence} array, otherwise, it will result in an error.
+
+As well as the top-level keys, some available keys in the \ckey{programs} table
+have default values, and only the values for the keys you explicitly specified
+in your configuration override. In string values for some specific keys, the
+format specifiers described in Section~\ref{sec:top-level-keys} can be used in
+the same way.
+
+\begin{confkey}{args}{type: \type{string} or \type{array of strings}}
+ [default: \code{["\%T"]}]
+You can specify an argument to give the command as a \type{string} value or one
+or more arguments as an \type{array of strings}. Each argument will be
+surrounded by a pair of double quotations, \eg \code{"arg"}. The format
+specifiers are available for this key.
+\end{confkey}
+
+\begin{confkey}{aux\_file}{type: \type{string}}
+The auxiliary file to monitor so that to check whether rerunning for the
+program is necessary or not. If this key is set and the specified file that is
+non-empty (see \ckey{aux\_empty\_size}) exists, \prog{llmk} will repeat the
+program execution until no change is made to the auxiliary file. This key is
+originally for the auxiliary file of {\LaTeX}, but the monitoring feature
+should be applicable to other programs. The format specifiers are available
+for this key.
+\end{confkey}
+
+\begin{confkey}{aux\_empty\_size}{type: \type{integer}}
+The empty size in bytes with this key, The auxiliary files specified with the
+\ckey{aux\_file} which is smaller than the value of this key are recognized as
+\emph{empty} and will be ignored. For instance, the auxiliary files of {\LaTeX},
+which normally have \code{.aux} extensions, contain
+|\cs{relax}\textvisiblespace\meta{line break}| (9 bytes); thus the default
+value of this key for the \progname{latex} program is \code{9}.
+\end{confkey}
+
+\begin{confkey}{command}{type: \type{string}}
+The name of the command to invoke. This is the only \emph{required} key for
+each entry in the \ckey{programs} table.
+\end{confkey}
+
+\begin{confkey}{generated\_target}{type: \type{boolean}}
+This flag is to denote whether or not the \ckey{target} is a file that should
+be generated in the \ckey{sequence} execution. For instance, DVI files, PS files,
+and the input files for \prog{makeindex}, which have \code{.idx} extensions are
+applicable. Conversely, files that you directly edit are not generated files.
+When the value is \code{true}, \prog{llmk} will consider only the target files
+newer than the time that the sequence processing starts. In case the target
+file is older, it will be ignored and the program will not be called.
+\end{confkey}
+
+\begin{confkey}{opts}{type: \type{string} or \type{array of strings}}
+You can specify a command-line option to give the command as a \type{string}
+value or one or more options as an \type{array of strings}. The format
+specifiers are available for this key.
+\end{confkey}
+
+\begin{confkey}{postprocess}{type: \type{string}}
+The name of a program (in the \ckey{programs} table) to be executed as
+postprocess. The specified program will be called only when the current main
+program is executed.
+\end{confkey}
+
+\begin{confkey}{target}{type: \type{string}}[default: \code{"\%S"}]
+The target filename of the program. The existence of the target file is checked
+by \prog{llmk} right before trying to execute each program, and the programs
+are invoked only when it exists. This filename is also used for replacing the
+value for the format specifiers. When this key is not specified, the input
+filename that is given as a command-line argument, or the filename in the value
+for the \ckey{source} key is used as a target.
+\end{confkey}
+
+\subsection{Default \code{programs} and \code{sequence}}
+
+In this section, the default values of the two important data structures for
+advanced control for \prog{llmk}, \ie the default configuration for the
+\ckey{programs} table and the \ckey{sequence} array. As it is already described
+in Section~\ref{sec:top-level-keys}, \ckey{programs} is the table to contain
+detailed configuration for each program to execute by \prog{llmk}, and
+\ckey{sequence} is an array to contain the names of entries in the
+\ckey{programs} table in the order of execution for a workflow. The default
+values of these are designed to work well for typical {\LaTeX} documents.
+Therefore, you normally do not need to change the values, but you can override
+any of the values by writing new values in your TOML configuration.
+
+\subsubsection{The default \code{programs}}
+\label{sec:default-programs}
+
+The followings are the default values in the \ckey{programs} table for each
+entry, \ie program, expressed in the TOML format. The default \ckey{programs}
+table contains useful settings for popular tools in the ecosystem of {\LaTeX}%
+\footnote{Reuquests for new settings for other programs will be considered.}.
+Only some of them are used in the default \ckey{sequence} (see Section~%
+\ref{sec:default-sequence}), but other entries can be easily used just by
+overriding the \ckey{sequence} array.
+
+\Program{bibtex} The entry for the {\BibTeX} program and friends. The
+\progname{latex} program is set as \ckey{postprocess} so that to make sure
+rerunning {\LaTeX} command after this execution.
+%
+\begin{lstlisting}[style=toml]
+[programs.bibtex]
+command = "bibtex"
+target = "%B.bib"
+args = ["%B"]
+postprocess = "latex"
+\end{lstlisting}
+
+\Program{dvipdf} The entry for the \prog{dvipdf} program and friends.
+%
+\begin{lstlisting}[style=toml]
+[programs.dvipdf]
+command = "dvipdfmx"
+target = "%B.dvi"
+generated_target = true
+\end{lstlisting}
+
+\Program{dvips} The entry for the \prog{dvips} program and friends.
+%
+\begin{lstlisting}[style=toml]
+[programs.dvips]
+command = "dvips"
+target = "%B.dvi"
+generated_target = true
+\end{lstlisting}
+
+\Program{latex} The entry for the main {\LaTeX} programs. The default value for
+the \ckey{command} is \code{"lualatex"}; since \prog{llmk} runs on
+\code{texlua}, the installation of {\LuaTeX} is guaranteed. That is why the
+command is chosen for the default.
+%
+\begin{lstlisting}[style=toml]
+[programs.latex]
+command = "lualatex"
+opts = ["-interaction=nonstopmode", "-file-line-error", "-synctex=1"]
+aux_file = "%B.aux"
+aux_empty_size = 9
+\end{lstlisting}
+
+\Program{makeindex} The entry for the Makeindex program and friends. The
+\progname{latex} program is set as \ckey{postprocess} so that to make sure
+rerunning {\LaTeX} command after this execution.
+%
+\begin{lstlisting}[style=toml]
+[programs.makeindex]
+command = "makeindex"
+target = "%B.idx"
+generated_target = true
+postprocess = "latex"
+\end{lstlisting}
+
+\Program{ps2pdf} The entry for the \prog{ps2pdf} program and friends.
+%
+\begin{lstlisting}[style=toml]
+[programs.ps2pdf]
+command = "ps2pdf"
+target = "%B.ps"
+generated_target = true
+\end{lstlisting}
+
+\subsubsection{The default \code{sequence}}
+\label{sec:default-sequence}
+
+The following is the default value for the \ckey{sequence} array:
+%
+\begin{htcode}
+["latex", "bibtex", "makeindex", "dvipdf"]
+\end{htcode}
+
+With these default settings in the \ckey{programs} table the \ckey{sequence}
+array, the default behavior of \prog{llmk} can be summarized as follows.
+%
+\begin{enumerate}
+\item It runs the {\LaTeX} command, by default {\LuaLaTeX}, against your
+ {\LaTeX} source file. This execution may be repeated when the auxiliary file
+ exists until no change made for the file to resolve all cross-references and
+ so on.
+\item If the corresponding {\BibTeX} database file, whose name matches to
+ \code{\%B.bib}, exists, the {\BibTeX} program is executed. When the execution
+ occurs, the \progname{latex} program is executed again right after because
+ the program is set as \ckey{postprocess}.
+\item Identically, if the corresponding input file for Makeindex exists, the
+ program is executed. When the execution occurs, the \progname{latex} program
+ is executed again right after because the program is set as \ckey{postprocess}.
+\item In case the corresponding DVI file is generated in the previous steps,
+ though this will not happen with the default value of \ckey{latex}, \ie
+ \code{"lualatex"}, the \progname{dvipdf} program, by default \code{dvipdfmx},
+ is executed to produce the final PDF file.
+\end{enumerate}
+
+The entries that are not used within the default \ckey{sequence} are to make it
+easier to use other tools from the above. For instance, if you wan to use
+$\text{\progname{dvips}}+\text{\progname{ps2pdf}}$ combination instead of
+\progname{dvipdf}, you can just modify the value of \ckey{sequence} a bit:
+%
+\begin{lstlisting}[style=toml]
+sequence = ["latex", "bibtex", "makeindex", "dvips", "ps2pdf"]
+\end{lstlisting}
+
+\section{Other supported formats}
+\label{sec:magic-comment}
+
+In addition to the TOML format, \prog{llmk} also supports a few other magic
+comment formats that are supported in some existing tools. These features are
+for user convenience, but note that the aim of \prog{llmk} is not to behave
+perfectly compatible with other tools.
+
+For \prog{llmk}, in your {\LaTeX} file, configuration in TOML format has the
+highest priority: when a TOML field is found, all the other magic comments will
+be ignored. The precedence of magic comment formats is as follows. Remember
+that all of these will be ignored if \prog{llmk} uses the configuration in a
+special file \code{llmk.toml}.
+%
+\begin{enumerate}
+\item TOML field (Section~\ref{sec:toml})
+\item {\TeX}Shop directives (Section~\ref{sec:ts-directive})
+\item Shebang-like directive (Section~\ref{sec:shebang})
+\end{enumerate}
+
+\subsection{{\TeX}Shop directives}
+\label{sec:ts-directive}
+
+{\TeX}Shop~\cite{texshop}, a {\TeX}-oriented IDE, understands special
+directives, which typically start with \code{\%\textvisiblespace !TEX}, to
+specify a workflow for processing {\LaTeX} document, \eg which {\TeX} engine to
+use. Similar directives are also supported in a few other tools such as {\TeX}%
+works~\cite{texworks} and {\TeX}studio~\cite{texstudio}.
+
+Among several variation of the directives, \prog{llmk} supports two of them.
+One is the directive to specify a variant of {\TeX} engine. The formal syntax
+of the directive is:
+%
+\bgroup
+\newcommand{\OS}{\meta{optional spaces}}
+\newcommand{\VS}{\textvisiblespace}
+\begin{htcode}
+\meta{TS prefix}TEX\VS{\OS}program\meta{equals}\meta{command}\OS
+\meta{TS prefix}TEX\VS{\OS}TS-program\meta{equals}\meta{command}\OS
+\end{htcode}
+\egroup
+%
+where the definitions of \meta{TS prefix} and \meta{equals} are given as
+follows.
+%
+\bgroup
+\newcommand{\OS}{\meta{optional spaces}}
+\begin{align*}
+&\text{\meta{TS prefix}}
+ \longrightarrow \text{\code{\OS\%\OS!\OS}} \\
+&\text{\meta{equals}}
+ \longrightarrow \text{\code{\OS=\OS}}
+\end{align*}
+\egroup
+%
+The \meta{command} part will be passed to the \ckey{latex} key of \prog{llmk}.
+The other supported {\TeX}Shop directive is that for the {\BibTeX} program. The
+syntax is very similar to the first one:
+%
+\bgroup
+\newcommand{\OS}{\meta{optional spaces}}
+\newcommand{\VS}{\textvisiblespace}
+\begin{htcode}
+\meta{TS prefix}BIB\VS{\OS}program\meta{equals}\meta{command}\OS
+\meta{TS prefix}BIB\VS{\OS}TS-program\meta{equals}\meta{command}\OS
+\end{htcode}
+\egroup
+%
+The \meta{command} part will be passed to the \ckey{bibtex} key of \prog{llmk}.
+For both of the two directives, only the topmost ones are effective; the others
+will be ignored. For example, the following two configuration are equivalent:\\
+%
+\begin{minipage}[t]{.5\textwidth}
+\begin{lstlisting}[style=latex]
+% !TEX TS-program = xelatex
+% !BIB TS-program = biber
+\documentclass{article}
+\end{lstlisting}
+\end{minipage}
+\begin{minipage}[t]{.49\textwidth}
+\begin{lstlisting}[style=latex]
+% +++
+% latex = "xelatex"
+% bibtex = "biber"
+% +++
+\documentclass{article}
+\end{lstlisting}
+\end{minipage}
+
+\subsection{Shebang-like directive}
+\label{sec:shebang}
+
+A few existing tools, notably the YaTeX mode for Emacs~\cite{yatex}, support
+the so-called shebang-like directive. This is also supported by \prog{llmk}.
+The syntax is:
+%
+\begin{htcode}
+\meta{optional spaces}%#!\meta{optional spaces}\meta{command}\meta{optional spaces}
+\end{htcode}
+%
+The \meta{command} part will be passed to the \ckey{latex} key of \prog{llmk}.
+This directive is only effective strictly in the first line in your {\LaTeX}
+source file.
+
+For example, the following two configuration are equivalent:\\
+%
+\begin{minipage}[t]{.5\textwidth}
+\begin{lstlisting}[style=latex]
+%#!pdflatex
+\documentclass{article}
+\end{lstlisting}
+\end{minipage}
+\begin{minipage}[t]{.49\textwidth}
+\begin{lstlisting}[style=latex]
+% +++
+% latex = "pdflatex"
+% +++
+\documentclass{article}
+\end{lstlisting}
+\end{minipage}
+
+\section{Acknowledgements}
+
+This project has been supported by the {\TeX} Development Fund 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 \prog{llmk} project.
+
+\section{License}
+
+This software is released under the MIT license:
+%
+\begin{quotation}
+\parindent=0pt
+\parskip=\baselineskip
+\small\ttfamily
+\noindent
+The MIT License (MIT)
+
+Copyright 2018-2020 Takuto ASAKURA (wtsnjp)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+\end{quotation}
+
+\subsection*{Third-party software}
+
+\paragraph{toml.lua} Copyright 2017 Jonathan Stoler. Released under the MIT
+license:
+%
+\begin{quote}
+\url{https://github.com/jonstoler/lua-toml/blob/master/LICENSE}
+\end{quote}
+
+\begin{thebibliography}{9}
+\bibitem{asakura2020}
+ Takuto Asakura. \textit{The design concept for \prog{llmk}\Dash Light {\LaTeX}
+ Make}. TUGboat, Volume~41, No.~2. (2020)
+
+\bibitem{arara}
+ Paulo Cereda, et al. \textit{arara\Dash The cool {\TeX} automation
+ tool}. \url{https://ctan.org/pkg/arara}
+
+\bibitem{latexmk}
+ John Collins. \textit{latexmk\Dash generate {\LaTeX} document}.
+ \url{https://ctan.org/pkg/latexmk}
+
+\bibitem{yatex}
+ Yuuji Hirose. \textit{YaTeX\Dash Yet Another TeX mode for Emacs}.
+ \url{https://www.yatex.org/}
+
+\bibitem{texworks}
+ Jonathan Kew, Stefan L\"offler, and Charlie Sharpsteen.
+ \textit{{\TeX}works\Dash lowering the entry barrier to the {\TeX} world}.
+ \url{https://tug.org/texworks/}
+
+\bibitem{texshop}
+ Richard Koch, et al. \textit{{\TeX}Shop}.
+ \url{https://pages.uoregon.edu/koch/texshop/}
+
+\bibitem{semvar}
+ Tom Preston-Werner. \textit{Semantic Versioning 2.0.0}.
+ \url{https://semver.org/}
+
+\bibitem{toml}
+ Tom Preston-Werner. \textit{TOML: Tom's Obvious Minimal Language}.
+ \url{https://toml.io/}
+
+\bibitem{texstudio}
+ Benito van der Zander, et al.
+ \textit{{\TeX}studio\Dash {\LaTeX} made comfortable}.\\
+ \url{https://texstudio.org/}
+\end{thebibliography}
+
+\end{document}
+% vim: set spell: