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