\documentclass{article} \usepackage{multicol} \usepackage{float} \usepackage[a4paper,margin=1.2in]{geometry} \title{The latex-formatter CTAN package \\ v0.5.7} \author{William G.\ Underwood} \begin{document} \maketitle \section{Overview} The latex-formatter CTAN package provides the tex-fmt command line tool for formatting LaTeX source files. Main features include: \begin{itemize} \item Extremely fast run-time performance \item Minimal configuration required \item Command line interface \item Handles LaTeX file types \texttt{.tex}, \texttt{.bib}, \texttt{.cls}, and \texttt{.sty} \item Written entirely in safe Rust \end{itemize} \renewcommand{\arraystretch}{1.8} \begin{table}[H] \begin{center} \begin{tabular}{|c|c|} \hline {\large Before \texttt{tex-fmt file.tex}} & {\large After \texttt{tex-fmt file.tex}} \\ \hline \begin{minipage}{5cm} \vspace*{2mm} \begin{verbatim} \documentclass{article} \begin{document} \begin{itemize} \item Lists with items over multiple lines \end{itemize} \begin{equation} E = m c^2 \end{equation} \end{document} \end{verbatim} \end{minipage} & \begin{minipage}{5cm} \vspace*{2mm} \begin{verbatim} \documentclass{article} \begin{document} \begin{itemize} \item Lists with items over multiple lines \end{itemize} \begin{equation} E = m c^2 \end{equation} \end{document} \end{verbatim} \end{minipage} \\ \hline \end{tabular} \end{center} \end{table} \pagebreak \section{Usage} The most commonly used options are given below. For a full list, see Section~\ref{sec:options}. \begin{verbatim} tex-fmt file.tex # format file.tex and overwrite tex-fmt --check file.tex # check if file.tex is correctly formatted tex-fmt --print file.tex # format file.tex and print to stdout tex-fmt --recursive # recursively format files in # current directory tex-fmt --recursive dir/ # recursively format files in dir tex-fmt --fail-on-change file.tex # format file.tex and return exit-code 1 # if overwritten tex-fmt --nowrap file.tex # do not wrap long lines tex-fmt --format-tables file.tex # format tables (align ampersands) tex-fmt --stdin # read from stdin and print to stdout tex-fmt --help # view help information \end{verbatim} \subsection{Configuration} Options can also be set using a configuration file, which will be read from the following locations, in order of decreasing priority. \begin{itemize} \item A named config file passed as \texttt{tex-fmt --config } \item A file named \texttt{tex-fmt.toml} in the current working directory \item A file named \texttt{tex-fmt.toml} in the root directory of the current git repository \item A file named \texttt{tex-fmt.toml} in a subdirectory titled \texttt{tex-fmt/} in the user's configuration directory at % \begin{itemize} \item Linux: \texttt{\textasciitilde/.config/tex-fmt/tex-fmt.toml} \item macOS: \texttt{/Users//Library/Application Support/tex-fmt/tex-fmt.toml} \item Windows: \texttt{C:\symbol{92}Users\symbol{92}\symbol{92}% AppData\symbol{92}Roaming\symbol{92}tex-fmt\symbol{92}tex-fmt.toml} \end{itemize} \end{itemize} Arguments passed on the command line will always override those specified in configuration files. To ignore all config files, use the \texttt{--noconfig} flag. An example configuration file is as follows. \begin{verbatim} # tex-fmt.toml check = false print = false wrap = true wraplen = 80 tabsize = 2 tabchar = "space" stdin = false verbosity = "warn" lists = [] no-indent-envs = [] \end{verbatim} \pagebreak \subsection{Disabling the formatter} Ending a source line with \texttt{\% tex-fmt: skip} disables formatting for that line. To disable the formatter for a block, use \texttt{\% tex-fmt: off} and \texttt{\% tex-fmt: on}. Verbatim environments including \texttt{verbatim}, \texttt{Verbatim}, \texttt{lstlisting} and \texttt{minted} are automatically skipped. \begin{verbatim} \documentclass{article} \begin{document} This line is skipped % tex-fmt: skip % tex-fmt: off These lines are also not formatted or wrapped % tex-fmt: on \end{document} \end{verbatim} \subsection{Ignoring files in recursive mode} Recursive searches with \texttt{--recursive} or \texttt{-r} will ignore patterns in \texttt{.gitignore} and \texttt{.ignore} files, following git conventions. \subsection{Shell completion} Shell completion scripts can be generated at run-time using the \texttt{--completion } flag. \subsection{Man page} A man page can be generated at run-time using the \texttt{--man} flag. \section{Limitations} \begin{itemize} \item Semantic parsing of LaTeX code not conducted \item No linting or correction of syntax errors \item Compliance with existing formatting guidelines not guaranteed \item No spelling or grammar checking \end{itemize} \pagebreak \section{Options} \label{sec:options} \subsection{Command line options} The following arguments can be passed on the command line. \renewcommand{\arraystretch}{1.2} \begin{table}[H] \begin{center} \begin{tabular}{|l|l|l|l|} \hline \multicolumn{1}{|c|}{Option} & \multicolumn{1}{|c|}{Alias} & \multicolumn{1}{|c|}{Default} & \multicolumn{1}{|c|}{Description} \\ \hline \texttt{--check} & \texttt{-c} & & Check formatting, do not modify files \\ \texttt{--print} & \texttt{-p} & & Print to stdout, do not modify files \\ \texttt{--fail-on-change} & \texttt{-f} & & Fail if files are modified \\ \texttt{--recursive} & \texttt{-r} & & Recursively search for files to format \\ \texttt{--nowrap} & \texttt{-n} & & Do not wrap long lines \\ \texttt{--wraplen } & \texttt{-l} & \texttt{80} & Line length for wrapping \\ \texttt{--tabsize } & \texttt{-t} & \texttt{2} & Number of characters to use as tab size \\ \texttt{--usetabs} & & & Use tabs instead of spaces for indentation \\ \texttt{--format-tables} & & & Format tables \\ \texttt{--stdin} & \texttt{-s} & & Process stdin as a single file, output to stdout \\ \texttt{--config } & & & Path to config file \\ \texttt{--noconfig} & & & Do not read any config file \\ \texttt{--verbose} & \texttt{-v} & & Show info messages \\ \texttt{--quiet} & \texttt{-q} & & Hide warning messages \\ \texttt{--trace} & & & Show trace messages \\ \texttt{--completion } & & & Generate a shell completion script \\ \texttt{--man} & & & Generate a man page \\ \texttt{--args} & & & View arguments passed to tex-fmt \\ \texttt{--help} & \texttt{-h} & & Print help \\ \texttt{--version} & \texttt{-V} & & Print version \\ \hline \end{tabular} \end{center} \end{table} \subsection{Configuration file options} The following arguments can be provided in \texttt{tex-fmt.toml}. The first example in each row is the default value. \begin{table}[H] \begin{center} \begin{tabular}{|l|l|l|l|} \hline \multicolumn{1}{|c|}{Option} & \multicolumn{1}{|c|}{Type} & \multicolumn{1}{|c|}{Examples} & \multicolumn{1}{|c|}{Description} \\ \hline \texttt{check} & bool & \texttt{false} & Check formatting, do not modify files \\ \texttt{print} & bool & \texttt{false} & Print to stdout, do not modify files \\ \texttt{fail-on-change} & bool & \texttt{false} & Fail if files are modified \\ \texttt{wrap} & bool & \texttt{true} & Wrap long lines \\ \texttt{wraplen} & int & \texttt{80}, \texttt{100} & Line length for wrapping \\ \texttt{wrapmin} & int & \texttt{70}, \texttt{90} & Target minimum length for line wrapping \\ \texttt{tabsize} & int & \texttt{2}, \texttt{4} & Number of characters to use as tab size \\ \texttt{tabchar} & str & \texttt{"space"}, \texttt{"tab"} & Character to use for indentation \\ \texttt{format-tables} & bool & \texttt{false} & Format tables \\ \texttt{stdin} & bool & \texttt{false} & Process stdin as a single file, \\ & & & output to stdout \\ \texttt{lists} & arr[str] & \texttt{[]}, \texttt{["myitemize"]} & Extra list environments \\ & & & to be formatted as \texttt{itemize} \\ \texttt{verbatims} & arr[str] & \texttt{[]}, \texttt{["myverbatim"]} & Extra verbatim environments \\ \texttt{no-indent-envs} & arr[str] & \texttt{[]}, \texttt{["mydocument"]} & Environments which are not indented \\ \texttt{wrap-chars} & arr[str] & \texttt{[]}, \texttt{[","]} & Characters after which lines \\ & & & may be wrapped \\ \texttt{verbosity} & str & \texttt{"warn"}, \texttt{"error"} & Verbosity level for terminal logging \\ \hline \end{tabular} \end{center} \end{table} \end{document}