summaryrefslogtreecommitdiff
path: root/support/cluttex/doc/cluttex.tex
blob: ae3bc01b67358a342c26795d44f0d9e97cadfdf7 (plain)
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
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
\documentclass[a4paper]{report}
\usepackage[unicode]{hyperref}
\usepackage{amsmath}
\newcommand\ClutTeX{Clut\TeX}
\providecommand\BibTeX{\textsc{Bib}\TeX}
\newcommand\texcmd[1]{\texttt{\textbackslash #1}}
\newcommand\texenv[1]{\texttt{#1}}
\newcommand\texpkg[1]{\texttt{#1}}
\newcommand\metavar[1]{\textnormal{\textsf{#1}}}

\title{\ClutTeX\ manual\\(Version 0.5.1)}
\author{ARATA Mizuki}
\date{2021-11-04}

\begin{document}
\maketitle
\tableofcontents

\chapter{About \ClutTeX}
\ClutTeX\ is an automation tool for \LaTeX\ document processing.
Basic features are,
\begin{itemize}
\item Does not clutter your working directory with ``extra'' files, like \texttt{.aux} or \texttt{.log}.
\item If multiple runs are required to generate correct document, do so.
\item Watch input files, and re-process documents if changes are detected\footnote{needs an external program if you are on a Unix system}.
\item Run MakeIndex, \BibTeX, Biber, if requested.
\item Produces a PDF, even if the engine (e.g.\ p\TeX) does not suport direct PDF generation.
  If you want a DVI file, use \texttt{--output-format=dvi} option.
\end{itemize}

The unique feature of this program is that, auxiliary files such as \texttt{.aux} or \texttt{.toc} are created in an isolated location, so you will not be annoyed with these extra files.

% A competitor: \href{http://www.personal.psu.edu/jcc8/latexmk/}{Latexmk}

\chapter{How to use \ClutTeX}
\section{Installation}
If you are using the latest \TeX\ Live, you should have \ClutTeX\ installed.
If not, upgrade your copy of \TeX\ Live with \texttt{tlmgr update --all}.

If you want to install \ClutTeX\ manually, fetch an archive from GitHub\footnote{\url{https://github.com/minoki/cluttex}}, extract it, and copy \texttt{bin/cluttex} or \texttt{bin/cluttex.bat} to somewhere in your \texttt{PATH}.

\section{Command-line usage}
Usage:
\begin{center}
  \texttt{cluttex -e \metavar{ENGINE} \metavar{OPTIONs} [--] \metavar{INPUT}.tex}
\end{center}

Basic options:
\begin{description}
\item[\texttt{-e}, \texttt{--engine=\metavar{ENGINE}}]
  Set which \TeX\ engine/format to use.
  \metavar{ENGINE} is one of the following:
  \texttt{pdflatex}, \texttt{pdftex},
  \texttt{lualatex}, \texttt{luatex}, \texttt{luajittex},
  \texttt{xelatex}, \texttt{xetex},
  \texttt{latex}, \texttt{etex}, \texttt{tex},
  \texttt{platex}, \texttt{eptex}, \texttt{ptex},
  \texttt{uplatex}, \texttt{euptex}, or \texttt{uptex}.
  Required.
\item[\texttt{-o}, \texttt{--output=\metavar{FILE}}]
  Set output file name.
  Default: \texttt{\metavar{JOBNAME}.\metavar{FORMAT}}
\item[\texttt{--fresh}]
  Clean auxiliary files before run.
  Cannot be used in conjunction with \texttt{--output-directory}.
\item[\texttt{--max-iterations=\metavar{N}}]
  Set maximum number of run, for resolving cross-references and etc.
  Default: 3
\item[\texttt{--watch}]
  Watch input files for change.
  May need an external program to be available.
  See \autoref{sec:watch-mode} for details.
\item[\texttt{--color[=\metavar{WHEN}]}]
  Colorize messages.
  \metavar{WHEN} is one of \texttt{always}, \texttt{auto}, or \texttt{never}.
  If \texttt{--color} option is omitted, \texttt{auto} is used.
  If \metavar{WHEN} is omitted, \texttt{always} is used.
\item[\texttt{--includeonly=\metavar{NAMEs}}]
  Insert \texttt{\texcmd{includeonly}\{\metavar{NAMEs}\}}.
\item[\texttt{--make-depends=\metavar{FILE}}]
  Write Makefile-style dependencies information to \metavar{FILE}.
\item[\texttt{--engine-executable=\metavar{COMMAND}}]
  The actual \TeX\ command to use.
\item[\texttt{--tex-option=\metavar{OPTION}}, \texttt{--tex-options=\metavar{OPTIONs}}]
  Pass extra options to \TeX.
\item[\texttt{--dvipdfmx-option=\metavar{OPTION}}, \texttt{--dvipdfmx-options=\metavar{OPTIONs}}]
  Pass extra options to \texttt{dvipdfmx}.
\item[\texttt{--[no-]change-directory}]
  Change to the output directory when run.
  May be useful with shell-escaping packages.
\item[\texttt{-h}, \texttt{--help}]
\item[\texttt{-v}, \texttt{--version}]
\item[\texttt{-V}, \texttt{--verbose}]
\item[\texttt{--print-output-directory}]
  Print the output directory and exit.
\item[\texttt{--package-support=PKG1[,PKG2,...,PKGn]}]
  Enable special support for shell-escaping packages.
  Currently supported packages are `\texttt{minted}` and `\texttt{epstopdf}`.
\item[\texttt{--check-driver=DRIVER}]
  Check that the correct driver file is loaded for certain packages.
  \metavar{DRIVER} is one of \texttt{dvipdfmx}, \texttt{dvips}, or \texttt{dvisvgm}.
  Can only be used with \texttt{--output-format=dvi}.
\end{description}

Options for running auxiliary programs:
\begin{description}
\item[\texttt{--makeindex=\metavar{COMMAND}}]
  Run MakeIndex.
\item[\texttt{--bibtex=\metavar{COMMAND}}]
  Run \BibTeX.
\item[\texttt{--biber[=\metavar{COMMAND}]}]
  Run Biber. Default value for \metavar{COMMAND}: \texttt{biber}
\item[\texttt{--makeglossaries[=\metavar{COMMAND}]}]
  Run makeglossaries. Experimental.
\end{description}

\TeX-compatible options:
\begin{description}
\item[\texttt{--[no-]shell-escape}]
\item[\texttt{--shell-restricted}]
\item[\texttt{--synctex=\metavar{NUMBER}}]
  Generate Sync\TeX\ file.
  Note that \texttt{.synctex.gz} is created alongside the final \texttt{.pdf}.
  See \autoref{sec:synctex} for details.
\item[\texttt{--[no-]file-line-error}]
  Default: Yes
\item[\texttt{--[no-]halt-on-error}]
  Default: Yes
\item[\texttt{--interaction=\metavar{STRING}}]
  \metavar{STRING} is one of \texttt{batchmode}, \texttt{nonstopmode}, \texttt{scrollmode}, or \texttt{errorstopmode}.
  Default: \texttt{nonstopmode}
\item[\texttt{--jobname=\metavar{STRING}}]
\item[\texttt{--fmt=\metavar{FORMAT}}]
\item[\texttt{--output-directory=\metavar{DIR}}]
  Set output directory for \TeX\ engine.
  Auxiliary files are produced in this directory.
  Default: somewhere in the temporary directory.
\item[\texttt{--output-format=\metavar{FORMAT}}]
  Set output format.
  Possible values are \texttt{pdf} or \texttt{dvi}.
  Default: \texttt{pdf}
\end{description}

Long options, except \TeX-compatible ones, need two hyphens (e.g. \texttt{-synctex=1} is accepted, but not \texttt{--color}).
Combining multiple short options, like \texttt{-Ve pdflatex}, is not supported.

\section{Sync\TeX}\label{sec:synctex}
You can generate Sync\TeX\ data with \texttt{--synctex=1} option.

Although \ClutTeX\ has ``Don't clutter your working directory'' as its motto, the \texttt{.synctex.gz} file is always produced alongside the PDF file.
This is because Sync\TeX\ cannot find its data file if it's not in the same directory as the PDF.

\section{Watch mode}\label{sec:watch-mode}
If \texttt{--watch} option is given, \ClutTeX\ enters \emph{watch mode} after processing the document.

On Windows, a built-in filesystem watcher is implemented.
On other platforms, an auxiliary program \texttt{fswatch}\footnote{\url{http://emcrisostomo.github.io/fswatch/}} or \texttt{inotifywait} needs to be installed.

\section{MakeIndex and \BibTeX}
If you want to generate index or bibliography, using MakeIndex or \BibTeX, set \texttt{--makeindex}, \texttt{--bibtex}, or \texttt{--biber} option.
You need to explicitly specify the command name as an argument (e.g. \texttt{--makeindex=makeindex}, \texttt{--bibtex=bibtex}).

If you want to use Biber to process bibliography, the option to use is \texttt{--biber}, not \texttt{--bibtex=biber}.

\section{For writing a large document}
When writing a large document with \LaTeX, you usually split the \TeX\ files with \texcmd{include} command.
When doing so, \texcmd{includeonly} can be used to eliminate processing time.
But writing \texcmd{includeonly} in the \TeX\ source file is somewhat inconvenient.
After all, \texcmd{includeonly} is about \emph{how} to process the document, not about its content.

Therefore, \ClutTeX\ provides an command-line option to use \texcmd{includeonly}.
See \autoref{sec:makefile-example} for example.

Tips: When using \texttt{includeonly}, avoid using \texttt{--makeindex} or \texttt{--biber}.

Another technique for eliminating time is, setting \texttt{--max-iterations=1}.
It stops \ClutTeX\ from processing the document multiple times, which may take several extra minutes.

\section{Using Makefile}\label{sec:makefile-example}
You can create Makefile to avoid writing \ClutTeX\ options each time.
Example:
\begin{verbatim}
main.pdf: main.tex chap1.tex chap2.tex
    cluttex -e lualatex -o $@ --makeindex=mendex $<

main-preview.pdf: main.tex chap1.tex chap2.tex
    cluttex -e lualatex -o $@ --makeindex=mendex --max-iterations=1 $<

chap1-preview.pdf: main.tex chap1.tex
    cluttex -e lualatex -o $@ --max-iterations=1 --includeonly=chap1 $<

chap2-preview.pdf: main.tex chap2.tex
    cluttex -e lualatex -o $@ --max-iterations=1 --includeonly=chap2 $<
\end{verbatim}

With \texttt{--make-depends} option, you can let \ClutTeX\ infer sub-files and omit them from Makefile.
Example:

\begin{verbatim}
main.pdf: main.tex
    cluttex -e lualatex -o $@ --make-depends=main.pdf.dep $<

-include main.pdf.dep
\end{verbatim}

After initial \texttt{make} run, \texttt{main.pdf.dep} will contain something like this:
\begin{verbatim}
main.pdf: ... main.tex ... chap1.tex chap2.tex
\end{verbatim}

Note that \texttt{--make-depends} option is still experimental, and may not work well with other options like \texttt{--makeindex}.

\section{Default output directory}
The auxiliary files like \texttt{.aux} are generated somewhere in the temporary directory, by default.
The directory name depends on the following three parameters:
\begin{itemize}
\item The absolute path of the input file
\item \texttt{--jobname} option
\item \texttt{--engine} option
\end{itemize}
On the other hand, the following parameters doesn't affect the directory name:
\begin{itemize}
\item \texttt{--includeonly}
\item \texttt{--makeindex}, \texttt{--bibtex}, \texttt{--biber}, \texttt{--makeglossaries}
\end{itemize}

If you need to know the exact location of the automatically-generated output directory, you can invoke \ClutTeX\ with \texttt{--print-output-directory}.
For example, \texttt{clean} target of your Makefile could be written as:
\begin{verbatim}
clean:
    -rm -rf $(shell cluttex -e pdflatex --print-output-directory main.tex)
\end{verbatim}

\ClutTeX\ itself doesn't erase the auxiliary files, unless \texttt{--fresh} option is set.
Note that, the use of a temporary directory means, the auxiliary files may be cleared when the computer is rebooted.

\section{Aliases}
Some Unix commands change its behavior when it is called under a different name.
There are several examples in \TeX\ Live:
\begin{itemize}
\item \texttt{extractbb} and \texttt{dvipdfmx} are aliases for \texttt{xdvipdfmx}.
\item \texttt{repstopdf} is an alias for \texttt{epstopdf}.
\end{itemize}

If \ClutTeX\ is called as \texttt{cl}\(\langle\text{\metavar{ENGINE}}\rangle\), the \texttt{--engine} option is set accordingly.
For example, \texttt{cllualatex} is an alias for \texttt{cluttex --engine lualatex} and \texttt{clxelatex} for \texttt{cluttex --engine xelatex}.

% The aliases provided by \TeX\ Live are, \texttt{cllualatex} and \texttt{clxelatex}.

\section{Support for \texpkg{minted} and \texpkg{epstopdf}}
In general, packages that execute external commands (shell-escape) don't work well with \texttt{-output-directory}.
Therefore, they don't work well with \ClutTeX.

However, some packages provide a package option to let them know the location of \texttt{-output-directory}.
For example, \texpkg{minted} provides \texttt{outputdir}, and \texpkg{epstopdf} provides \texttt{outdir}.

\ClutTeX\ can supply them the appropriate options, but only if it knows that the package is going to be used.
To let \ClutTeX\ what packages are going to be used, use \texttt{--package-support} option.

For example, if you want to typeset a document that uses \texpkg{minted}, run the following:
\begin{verbatim}
cluttex -e pdflatex --shell-escape --package-support=minted document.tex
\end{verbatim}

\section{Check for driver file}

\ClutTeX\ can check that the correct driver file is loaded when certain packages are loaded.
Currently, the list of supported packages are \texpkg{graphics}, \texpkg{color}, \texpkg{expl3}, \texpkg{hyperref}, and \texpkg{xy}.

The check is always done with PDF mode.
To check the driver with DVI mode, use \texttt{--check-driver} option.

\end{document}