summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/support/cluttex/doc/manual.tex
blob: 4ec0464cc67960085875f87bf2e1ab8372e0557c (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
\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}
\author{ARATA Mizuki}
\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}.
\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.
\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.
  Requires \texttt{fswatch} command 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{--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}]
\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.
An auxiliary program \texttt{fswatch}\footnote{\url{http://emcrisostomo.github.io/fswatch/}} needs to be installed for this mode.

A future version of \ClutTeX\ may implement a built-in filesystem watcher.

\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}

\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}.

\end{document}