diff options
Diffstat (limited to 'Master/texmf-dist/doc/support/latexindent/documentation/latexindent.tex')
-rw-r--r-- | Master/texmf-dist/doc/support/latexindent/documentation/latexindent.tex | 1512 |
1 files changed, 1512 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/support/latexindent/documentation/latexindent.tex b/Master/texmf-dist/doc/support/latexindent/documentation/latexindent.tex new file mode 100644 index 00000000000..c39b89e627e --- /dev/null +++ b/Master/texmf-dist/doc/support/latexindent/documentation/latexindent.tex @@ -0,0 +1,1512 @@ +% arara: pdflatex +% arara: bibtex +% arara: pdflatex +% arara: pdflatex +% !arara: pdflatex +% !arara: indent: {overwrite: yes, trace: yes, localSettings: yes, silent: yes} +\documentclass[11pt]{article} +% This program is free software: you can redistribute it and/or modify +% it under the terms of the GNU General Public License as published by +% the Free Software Foundation, either version 3 of the License, or +% (at your option) any later version. +% +% This program is distributed in the hope that it will be useful, +% but WITHOUT ANY WARRANTY; without even the implied warranty of +% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +% GNU General Public License for more details. +% +% See <http://www.gnu.org/licenses/>. +\usepackage[left=4.5cm,right=2.5cm,showframe=false, +top=2cm,bottom=1.5cm]{geometry} % page setup +\usepackage{parskip} % paragraph skips +\usepackage{booktabs} % beautiful tables +\usepackage{listings} % nice verbatim environments +\usepackage{titlesec} % customize headings +\usepackage{changepage} % adjust width of page +\usepackage{fancyhdr} % headers & footers +\usepackage[sc,format=hang,font=small]{caption} % captions +\usepackage[backend=bibtex]{biblatex} % bibliography +\usepackage{tcolorbox} % framed environments +\usepackage[charter]{mathdesign} % changes font +\usepackage[expansion=false,kerning=true]{microtype} % better kerning +\usepackage{enumitem} % custom lists +% setup gitinfo2, as in the manual, details just above begin{document} +\usepackage[mark,grumpy]{gitinfo2} +\usepackage{examplep} +% tcolorbox libraries +\tcbuselibrary{breakable,skins,listings} +% tikz libraries +\usetikzlibrary{positioning} +\usetikzlibrary{decorations.pathmorphing} +\usetikzlibrary{decorations,shapes} +\usepackage{varioref} % clever referencing +\usepackage{hyperref} +\hypersetup{ + pdfauthor={Chris Hughes}, + pdftitle={latexindent.pl package}, + pdfkeywords={perl;beautify;indentation}, + bookmarksnumbered, + bookmarksopen, + linktocpage, + colorlinks=true, + linkcolor=blue, + citecolor=black, +} +\usepackage{cleveref} + +\addbibresource{latex-indent} +\addbibresource{contributors} + + +% http://tex.stackexchange.com/questions/122135/how-to-add-a-png-icon-on-the-right-side-of-a-tcolorbox-title +\newtcolorbox{warning}{parbox=false,breakable,enhanced,arc=0mm,colback=red!5,colframe=red,leftrule=12mm,% + overlay={\node[anchor=north west,outer sep=2pt] at (frame.north west) {\includegraphics[width=8mm]{warning}}; }} + +\makeatletter +\tcbset{ + addtolol/.style={list entry={\kvtcb@title},add to list={lol}{lstlisting}}, +} + +\newtcblisting[use counter=lstlisting]{cmhlistings}[3][]{% + width=\linewidth, + breakable, + colback=blue!5!white, + colframe=white!85!black, + top=0cm, + bottom=0cm, + left=6mm, + listing only, + listing options={#1}, + center title, + title={\color{black}{\scshape Listing \thetcbcounter}: ~#2},label={#3}, + addtolol, +} + +\lstset{% + basicstyle=\small\ttfamily,language={[LaTeX]TeX}, + % numbers=left, + numberstyle=\ttfamily%\small, + breaklines=true, + % frame=single,framexleftmargin=8mm, xleftmargin=8mm, + % prebreak = \raisebox{0ex}[0ex][0ex]{\ensuremath{\hookrightarrow}}, + % backgroundcolor=\color{green!5},frameround=fttt, + % rulecolor=\color{blue!70!black}, + keywordstyle=\color{blue}, % keywords + commentstyle=\color{purple}, % comments + tabsize=3, + %xleftmargin=1.5em, +}% +\lstdefinestyle{yaml}{% + numbers=left, + numberstyle=\color{black},} +\lstdefinestyle{demo}{ + numbers=none, + linewidth=1.25\textwidth, + columns=fullflexible, +} + +% stars around contributors +\pgfdeclaredecoration{stars}{initial}{ + \state{initial}[width=15pt] + { + \pgfmathparse{round(rnd*100)} + \pgfsetfillcolor{yellow!\pgfmathresult!orange} + \pgfsetstrokecolor{yellow!\pgfmathresult!red} + \pgfnode{star}{center}{}{}{\pgfusepath{stroke,fill}} + } + \state{final} + { + \pgfpathmoveto{\pgfpointdecoratedpathlast} + } +} + +\newtcolorbox{stars}{% + enhanced jigsaw, + breakable, % allow page breaks + left=0cm, + top=0cm, + before skip=0.2cm, + boxsep=0cm, + frame style={draw=none,fill=none}, % hide the default frame + colback=white, + overlay={ + \draw[inner sep=0,minimum size=rnd*15pt+2pt] + decorate[decoration={stars,segment length=2cm}] { + decorate[decoration={zigzag,segment length=2cm,amplitude=0.3cm}] { + ([xshift=-.5cm,yshift=0.1cm]frame.south west) -- ([xshift=-.5cm,yshift=0.4cm]frame.north west) + }}; + \draw[inner sep=0,minimum size=rnd*15pt+2pt] + decorate[decoration={stars,segment length=2cm}] { + decorate[decoration={zigzag,segment length=2cm,amplitude=0.3cm}] { + ([xshift=.75cm,yshift=0.1cm]frame.south east) -- ([xshift=.75cm,yshift=0.6cm]frame.north east) + }}; + }, + % paragraph skips obeyed within tcolorbox + parbox=false, +} + +% copied from /usr/local/texlive/2013/texmf-dist/tex/latex/biblatex/bbx/numeric.bbx +% the only modification is the \stars and \endstars +\defbibenvironment{specialbib} +{\stars\list + {\printtext[labelnumberwidth]{% + \printfield{prefixnumber}% + \printfield{labelnumber}}} + {\setlength{\labelwidth}{\labelnumberwidth}% + \setlength{\leftmargin}{\labelwidth}% + \setlength{\labelsep}{\biblabelsep}% + \addtolength{\leftmargin}{\labelsep}% + \setlength{\itemsep}{\bibitemsep}% + \setlength{\parsep}{\bibparsep}}% + \renewcommand*{\makelabel}[1]{\hss##1}} +{\endlist\endstars} +{\item} + +% see: http://tex.stackexchange.com/questions/2245/verbatim-description-list-item +\newcommand{\verbitem}[1]{\small\PVerb{#1}} +% stolen from arara.sty http://mirrors.med.harvard.edu/ctan/support/arara/doc/arara.sty +%\lstnewenvironment{yaml}[1][]{\lstset{% +% basicstyle=\ttfamily, +% numbers=left, +% xleftmargin=1.5em, +% breaklines=true, +% numberstyle=\ttfamily\small, +% columns=flexible, +% mathescape=false, +% #1, +%}} +%{} + +\newcommand{\fixthis}[1] +{% + \marginpar{\huge \color{red} \framebox{FIX}}% + \typeout{FIXTHIS: p\thepage : #1^^J}% +} +% custom section +\titleformat{\section} +{\normalfont\Large\bfseries} +{\llap{\thesection\hskip.5cm}} +{0pt} +{} +% custom subsection +\titleformat{\subsection} +{\normalfont\bfseries} +{\llap{\thesubsection\hskip.5cm}} +{0pt} +{} +% custom subsubsection +\titleformat{\subsubsection} +{\normalfont\bfseries} +{\llap{\thesubsubsection\hskip.5cm}} +{0pt} +{} + + +\titlespacing\section{0pt}{12pt plus 4pt minus 2pt}{-5pt plus 2pt minus 2pt} +\titlespacing\subsection{0pt}{12pt plus 4pt minus 2pt}{-6pt plus 2pt minus 2pt} +\titlespacing\subsubsection{0pt}{12pt plus 4pt minus 2pt}{-6pt plus 2pt minus 2pt} + + +% cleveref settings +\crefname{table}{Table}{Tables} +\Crefname{table}{Table}{Tables} +\crefname{figure}{Figure}{Figures} +\Crefname{figure}{Figure}{Figures} +\crefname{section}{Section}{Sections} +\Crefname{section}{Section}{Sections} +\crefname{listing}{Listing}{Listings} +\Crefname{listing}{Listing}{Listings} + +% headers and footers +\fancyhf{} % delete current header and footer +\fancyhead[R]{\bfseries\thepage} +\fancyheadoffset[L]{3cm} +\pagestyle{fancy} + +% renew plain style +\fancypagestyle{plain}{% +\fancyhf{} % clear all header and footer fields +\renewcommand{\headrulewidth}{0pt} +\renewcommand{\footrulewidth}{0pt}} + +% sidebyside environment +\newenvironment{sidebyside}{\begin{adjustwidth}{-3cm}{1cm}}{\end{adjustwidth}} + +% gitinfo2 settings +\renewcommand{\gitMark}{\gitBranch\,@\,\gitAbbrevHash{}\,\textbullet{}\,\gitAuthorDate } + +% setting up gitinfo2: +% copy the file post-xxx-sample.txt from https://www.ctan.org/tex-archive/macros/latex/contrib/gitinfo2 +% and put it in .git/hooks/post-checkout +% then +% cd .git/hooks +% chmod g+x post-checkout +% chmod +x post-checkout +% cp post-checkout post-commit +% cp post-checkout post-merge +% cd ../.. +% git checkout master +% git checkout develop +% ls .git +% and you should see gitHeadInfo.gin +\begin{document} +% \begin{noindent} + \title{\lstinline[basicstyle=\huge\ttfamily]!latexindent.pl!\\[1cm] + Version 2.2} +% \end{noindent} +\author{Chris Hughes \footnote{and contributors! (See \vref{sec:contributors}.)}} +\maketitle +\begin{abstract} + \lstinline!latexindent.pl! is a \lstinline!Perl! script that indents \lstinline!.tex! (and other) + files according to an indentation scheme that the user can modify to suit their + taste. Environments, including those with alignment delimiters (such as \lstinline!tabular!), + and commands, including those that can split braces and brackets across lines, + are \emph{usually} handled correctly by the script. Options for \lstinline!verbatim!-like + environments and indentation after headings (such as \lstinline!\chapter!, \lstinline!\section!, etc) + are also available. +\end{abstract} + +\tableofcontents +\lstlistoflistings + +\section{Before we begin} +\subsection{Thanks} +I first created \lstinline!latexindent.pl! to help me format chapter files +in a big project. After I blogged about it on the +\TeX{} stack exchange \cite{cmhblog} I received some positive feedback and +follow-up feature requests. A big thank you to Harish Kumar who has really +helped to drive the script forward and has put it through a number of challenging +tests--I look forward to more challenges in the future Harish! + +The \lstinline!yaml!-based interface of \lstinline!latexindent.pl! was inspired +by the wonderful \lstinline!arara! tool; any similarities are deliberate, and +I hope that it is perceived as the compliment that it is. Thank you to Paulo Cereda and the +team for releasing this awesome tool; I initially worried that I was going to +have to make a GUI for \lstinline!latexindent.pl!, but the release of \lstinline!arara! +has meant there is no need. Thank you to Paulo for all of your advice and +encouragement. + +There have been several contributors to the project so far (and hopefully more in +the future!); thank you very much to the people detailed in \vref{sec:contributors} +for their valued contributions. + +\subsection{License} +\lstinline!latexindent.pl! is free and open source, and it always will be. +Before you start using it on any important files, bear in mind that \lstinline!latexindent.pl! has the option to overwrite your \lstinline!.tex! files. +It will always make at least one backup (you can choose how many it makes, see \cpageref{page:onlyonebackup}) +but you should still be careful when using it. The script has been tested on many +files, but there are some known limitations (see \cref{sec:knownlimitations}). +You, the user, are responsible for ensuring that you maintain backups of your files +before running \lstinline!latexindent.pl! on them. I think it is important at this +stage to restate an important part of the license here: +\begin{quote}\itshape + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. +\end{quote} +There is certainly no malicious intent in releasing this script, and I do hope +that it works as you expect it to--if it does not, please first of all +make sure that you have the correct settings, and then feel free to let me know with a +complete minimum working example as I would like to improve the code as much as possible. + +\begin{warning} + Before you try the script on anything important (like your thesis), test it + out on the sample files that come with it in the \lstinline!success! directory. +\end{warning} + + +\section{Demonstration: before and after} +Let's give a demonstration of some before and after code--after all, you probably +won't want to try the script if you don't much like the results. You might also +like to watch the video demonstration I made on youtube \cite{cmh:videodemo} + +As you look at \crefrange{lst:filecontentsbefore}{lst:pstricksafter}, remember +that \lstinline!latexindent.pl! is just following its rules--there is nothing +particular about these code snippets. All of the rules can be modified +so that each user can personalize their indentation scheme. + +In each of the samples given in \crefrange{lst:filecontentsbefore}{lst:pstricksafter} +the `before' case is a `worst case scenario' with no effort to make indentation. The `after' +result would be the same, regardless of the leading white space at the beginning of +each line which is stripped by \lstinline!latexindent.pl! (unless a \lstinline!verbatim!-like +environment or \lstinline!noIndentBlock! is specified--more on this in \cref{sec:defuseloc}). + + \begin{sidebyside} + \noindent + \begin{minipage}{.6\textwidth} + \begin{cmhlistings}[style=demo]{\lstinline!filecontents! before}{lst:filecontentsbefore} +\begin{filecontents}{mybib.bib} +@online{strawberryperl, +title="Strawberry Perl", +url="http://strawberryperl.com/"} +@online{cmhblog, +title="A Perl script ... +url="... +\end{filecontents} + \end{cmhlistings} + \end{minipage}% + \noindent + \begin{minipage}{.6\textwidth} + \begin{cmhlistings}[style=demo]{\lstinline!filecontents! after}{lst:filecontentsafter} +\begin{filecontents}{mybib.bib} + @online{strawberryperl, + title="Strawberry Perl", + url="http://strawberryperl.com/"} + @online{cmhblog, + title="A Perl script for ... + url="... +\end{filecontents} + \end{cmhlistings} + \end{minipage} + \begin{minipage}{.6\textwidth} + \begin{cmhlistings}[style=demo]{\lstinline!tikzset! before}{lst:tikzsetbefore} +\tikzset{ +shrink inner sep/.code={ +\pgfkeysgetvalue... +\pgfkeysgetvalue... +} +} + \end{cmhlistings} + \end{minipage}% + \begin{minipage}{.6\textwidth} + \begin{cmhlistings}[style=demo]{\lstinline!tikzset! after}{lst:tikzsetafter} +\tikzset{ + shrink inner sep/.code={ + \pgfkeysgetvalue... + \pgfkeysgetvalue... + } +} + \end{cmhlistings} + \end{minipage} + \begin{minipage}{.6\textwidth} + \begin{cmhlistings}[style=demo]{\lstinline!pstricks! before}{lst:pstricksbefore} +\def\Picture#1{% +\def\stripH{#1}% +\begin{pspicture}[showgrid... +\psforeach{\row}{% +{{3,2.8,2.7,3,3.1}},% <=== Only this +{2.8,1,1.2,2,3},% +... +}{% +\expandafter... +} +\end{pspicture}} + \end{cmhlistings} + \end{minipage}% + \begin{minipage}{.6\textwidth} + \begin{cmhlistings}[style=demo]{\lstinline!pstricks! after}{lst:pstricksafter} +\def\Picture#1{% + \def\stripH{#1}% + \begin{pspicture}[showgrid... + \psforeach{\row}{% + {{3,2.8,2.7,3,3.1}},% <=== + {2.8,1,1.2,2,3},% + ... + }{% + \expandafter... + } + \end{pspicture}} + \end{cmhlistings} + \end{minipage} + \end{sidebyside} + +\section{How to use the script} +\lstinline!latexindent.pl! ships as part of the \TeX Live distribution for +Linux and Mac users; \lstinline!latexindent.exe! ships as part of the \TeX Live +and MiK\TeX distributions for Windows users. These files are also available +from github \cite{latexindent-home} should you wish to use them without +a \TeX{} distribution; in this case, you may like to read \vref{sec:updating-path} +which details how the \lstinline!path! variable can be updated. + +In what follows, we will always refer to \lstinline!latexindent.pl!, but depending on +your operating system and preference, you might substitute \lstinline!latexindent.exe! or +simply \lstinline!latexindent!. + +There are two ways to use \lstinline!latexindent.pl!: from the command line, +and using \lstinline!arara!; we discuss these in \cref{sec:commandline} and +\cref{sec:arara} respectively. We will discuss how to change the settings and +behaviour of the script in \vref{sec:defuseloc}. + +\lstinline!latexindent.pl! ships with \lstinline!latexindent.exe! for Windows +users, so that you can use the script with or without a Perl distribution. +If you plan to use \lstinline!latexindent.pl! (i.e, the original Perl script) then you will +need a few standard Perl modules--see \vref{sec:requiredmodules} for details. + +\subsection{From the command line}\label{sec:commandline} +\lstinline!latexindent.pl! has a number of different switches/flags/options, which +can be combined in any way that you like, either in short or long form as detailed below. +\lstinline!latexindent.pl! produces a \lstinline!.log! file, \lstinline!indent.log! every time it +is run. There is a base of information that is written to \lstinline!indent.log!, +but other additional information will be written depending +on which of the following options are used. + +\begin{itemize}[labelsep=.25cm] + \item[] \lstinline!latexindent.pl! + + This will output a welcome message to the terminal, including the version number + and available options. + \item[\verbitem{-h, --help}] \lstinline!latexindent.pl -h! + + As above this will output a welcome message to the terminal, including the version number + and available options. + \item[] \lstinline!latexindent.pl myfile.tex! + + This will operate on \lstinline!myfile.tex!, but will simply output to your terminal; \lstinline!myfile.tex! will not be changed in any way using this command. + \item[\verbitem{-w, --overwrite}] \lstinline!latexindent.pl -w myfile.tex! + + This \emph{will} overwrite \lstinline!myfile.tex!, but it will + make a copy of \lstinline!myfile.tex! first. You can control the name of + the extension (default is \lstinline!.bak!), and how many different backups are made-- + more on this in \cref{sec:defuseloc}; see \lstinline!backupExtension! and \lstinline!onlyOneBackUp!. + + Note that if \lstinline!latexindent.pl! can not create the backup, then it + will exit without touching your original file; an error message will be given + asking you to check the permissions of the backup file. + \item[\verbitem{-o,--outputfile}] \lstinline!latexindent.pl -o myfile.tex outputfile.tex! + + This will indent \lstinline!myfile.tex! and output it to \lstinline!outputfile.tex!, + overwriting it (\lstinline!outputfile.tex!) if it already exists. Note that if \lstinline!latexindent.pl! is called with both + the \lstinline!-w! and \lstinline!-o! switches, then \lstinline!-w! will + be ignored and \lstinline!-o! will take priority (this seems safer than the + other way round). + + Note that using \lstinline!-o! is equivalent to using \lstinline!latexindent.pl myfile.tex > outputfile.tex! + \item[\verbitem{-s, --silent}] \lstinline!latexindent.pl -s myfile.tex! + + Silent mode: no output will be given to the terminal. + \item[\verbitem{-t, --trace}] \lstinline!latexindent.pl -t myfile.tex! + + \label{page:traceswitch} + Tracing mode: verbose output will be given to \lstinline!indent.log!. This + is useful if \lstinline!latexindent.pl! has made a mistake and you're + trying to find out where and why. You might also be interested in learning + about \lstinline!latexindent.pl!'s thought process--if so, this + switch is for you. + \item[\verbitem{-tt, --ttrace}] \lstinline!latexindent.pl -tt myfile.tex! + + \emph{More detailed} tracing mode: this option gives more details to \lstinline!indent.log! + than the standard \lstinline!trace! option. + \item[\verbitem{-l, --local[=myyaml.yaml]}] \lstinline!latexindent.pl -l myfile.tex! + +\lstinline!latexindent.pl -l=myyaml.yaml myfile.tex! + +\lstinline!latexindent.pl -l myyaml.yaml myfile.tex! + + + \label{page:localswitch} + Local settings: you might like to read \cref{sec:defuseloc} before + using this switch. \lstinline!latexindent.pl! will always load \lstinline!defaultSettings.yaml! + and if it is called with the \lstinline!-l! switch and it finds \lstinline!localSettings.yaml! + in the same directory as \lstinline!myfile.tex! then these settings will be + added to the indentation scheme. Information will be given in \lstinline!indent.log! on + the success or failure of loading \lstinline!localSettings.yaml!. + +The \lstinline!-l! flag can take an \emph{optional} parameter which details the name of a \lstinline!yaml! file +that resides in the same directory as \lstinline!myfile.tex!; you can use this option if you would +like to load a settings file in the current working directory that is \emph{not} called \lstinline!localSettings.yaml!. + + \item[\verbitem{-d, --onlydefault}] \lstinline!latexindent.pl -d myfile.tex! + + Only \lstinline!defaultSettings.yaml!: you might like to read \cref{sec:defuseloc} before + using this switch. By default, \lstinline!latexindent.pl! will always search for + \lstinline!indentconfig.yaml! or \lstinline!.indentconfig.yaml! in your home directory. If you would prefer it not to do so + then (instead of deleting or renaming \lstinline!indentconfig.yaml!/\lstinline!.indentconfig.yaml!) you can simply + call the script with the \lstinline!-d! switch; note that this will also tell + the script to ignore \lstinline!localSettings.yaml! even if it has been called with the + \lstinline!-l! switch. + + \item[\verbitem{-c, --cruft=<directory>}]\lstinline!latexindent.pl -c=/path/to/directory/ myfile.tex! + + If you wish to have backup files and \lstinline!indent.log! written to a directory + other than the current working directory, then you can send these `cruft' files + to another directory. + % this switch was made as a result of http://tex.stackexchange.com/questions/142652/output-latexindent-auxiliary-files-to-a-different-directory +\end{itemize} + +\lstinline!latexindent.pl! can also be called on a file without the file extension, for +example \lstinline[breaklines=true,breakatwhitespace=true,]!latexindent.pl myfile! and in which case, you can specify +the order in which extensions are searched for; see \vref{lst:fileExtensionPreference} +for full details. + +\subsection{From \lstinline!arara!}\label{sec:arara} +Using \lstinline!latexindent.pl! from the command line is fine for some folks, but +others may find it easier to use from \lstinline!arara!. \lstinline!latexindent.pl! +ships with an \lstinline!arara! rule, \lstinline!indent.yaml!, which can be copied +to the directory of +your other \lstinline!arara! rules; otherwise you can add the directory in which \lstinline!latexindent.pl! +resides to your \lstinline!araraconfig.yaml! file. + +Once you have told \lstinline!arara! where to find your \lstinline!indent! rule, +you can use it any of the ways described in \cref{lst:arara} (or combinations thereof). +In fact, \lstinline!arara! allows yet greater flexibility--you can use \lstinline!yes/no!, \lstinline!true/false!, or \lstinline!on/off! to toggle the various options. + +\begin{cmhlistings}[style=demo,escapeinside={(*@}{@*)}]{\lstinline!arara! sample usage}{lst:arara} +%(*@@*) arara: indent +%(*@@*) arara: indent: {overwrite: yes} +%(*@@*) arara: indent: {output: myfile.tex} +%(*@@*) arara: indent: {silent: yes} +%(*@@*) arara: indent: {trace: yes} +%(*@@*) arara: indent: {localSettings: yes} +%(*@@*) arara: indent: {onlyDefault: on} +%(*@@*) arara: indent: { cruft: /home/cmhughes/Desktop } +\documentclass{article} +... +\end{cmhlistings} + +Hopefully the use of these rules is fairly self-explanatory, but for completeness +\cref{tab:orbsandswitches} shows the relationship between \lstinline!arara! directive arguments and the +switches given in \cref{sec:commandline}. + +\begin{table}[!ht] + \centering + \caption{\lstinline!arara! directive arguments and corresponding switches} + \label{tab:orbsandswitches} + \begin{tabular}{lc} + \toprule + \lstinline!arara! directive argument & switch \\ + \midrule + \lstinline!overwrite! & \lstinline!-w! \\ + \lstinline!output! & \lstinline!-o! \\ + \lstinline!silent! & \lstinline!-s! \\ + \lstinline!trace! & \lstinline!-t! \\ + \lstinline!localSettings! & \lstinline!-l! \\ + \lstinline!onlyDefault! & \lstinline!-d! \\ + \lstinline!cruft! & \lstinline!-c! \\ + \bottomrule + \end{tabular} +\end{table} + +The \lstinline!cruft! directive does not work well when used with +directories that contain spaces. + +\section{default, user, and local settings}\label{sec:defuseloc} +\lstinline!latexindent.pl! loads its settings from \lstinline!defaultSettings.yaml! +(rhymes with camel). The idea is to separate the behaviour of the script +from the internal working--this is very similar to the way that we separate content +from form when writing our documents in \LaTeX. + +\subsection{\lstinline!defaultSettings.yaml!} +If you look in \lstinline!defaultSettings.yaml! you'll find the switches +that govern the behaviour of \lstinline!latexindent.pl!. If you're not sure where +\lstinline!defaultSettings.yaml! resides on your computer, don't worry as \lstinline!indent.log! +will tell you where to find it. +\lstinline!defaultSettings.yaml! is commented, +but here is a description of what each switch is designed to do. The default +value is given in each case. + +You can certainly feel free to edit \lstinline!defaultSettings.yaml!, but +this is not ideal as it may be overwritten when you update your \TeX{} distribution -- +all of your hard work tweaking the script would be undone! Don't worry, +there's a solution, feel free to peek ahead to \cref{sec:indentconfig} if you like. +\begin{itemize} + \item[\verbitem{defaultIndent}] \lstinline!"\t"! + + This is the default indentation (\lstinline!\t! means a tab) used in the absence of other details + for the command or environment we are working with--see \lstinline!indentRules! + for more details (\cpageref{page:indentRules}). + + If you're interested in experimenting with \lstinline!latexindent.pl! then you + can \emph{remove} all indentation by setting \lstinline!defaultIndent: ""! + \item[\verbitem{backupExtension}] \lstinline!.bak! + + If you call \lstinline!latexindent.pl! with the \lstinline!-w! switch (to overwrite + \lstinline!myfile.tex!) then it will create a backup file before doing + any indentation: \lstinline!myfile.bak0! + + By default, every time you call \lstinline!latexindent.pl! after this with + the \lstinline!-w! switch it will create \lstinline!myfile.bak1!, \lstinline!myfile.bak2!, + etc. + \item[\verbitem{onlyOneBackUp}] \lstinline!0! + + \label{page:onlyonebackup} + If you don't want a backup for every time that you call \lstinline!latexindent.pl! (so + you don't want \lstinline!myfile.bak1!, \lstinline!myfile.bak2!, etc) and you simply + want \lstinline!myfile.bak! (or whatever you chose \lstinline!backupExtension! to be) + then change \lstinline!onlyOneBackUp! to \lstinline!1!. + + \item[\verbitem{maxNumberOfBackUps}]\lstinline!0! + + Some users may only want a finite number of backup files, + say at most $3$, in which case, they can change this switch. + The smallest value of \lstinline!maxNumberOfBackUps! is $0$ which will \emph{not} + prevent backup files being made--in this case, the behaviour will be dictated + entirely by \lstinline!onlyOneBackUp!. + %\footnote{This was a feature request made on \href{https://github.com/cmhughes/latexindent.plx}{github}} + \item[\verbitem{cycleThroughBackUps}]\lstinline!0! + + Some users may wish to cycle through backup files, by deleting the + oldest backup file and keeping only the most recent; for example, + with \lstinline!maxNumberOfBackUps: 4!, and \lstinline!cycleThroughBackUps! + set to \lstinline!1! then the \lstinline!copy! procedure given in \cref{lst:cycleThroughBackUps} + would be obeyed. + + \begin{cmhlistings}[language=Perl]{\lstinline!cycleThroughBackUps!}{lst:cycleThroughBackUps} +copy myfile.bak1 to myfile.bak0 +copy myfile.bak2 to myfile.bak1 +copy myfile.bak3 to myfile.bak2 +copy myfile.bak4 to myfile.bak3 + \end{cmhlistings} + + \item[\verbitem{indentPreamble}] \lstinline!0! + + The preamble of a document can sometimes contain some trickier code + for \lstinline!latexindent.pl! to work with. By default, \lstinline!latexindent.pl! + won't try to operate on the preamble, but if you'd like it to try then + change \lstinline!indentPreamble! to \lstinline!1!. + \item[\verbitem{alwaysLookforSplitBraces}] \lstinline!1! + + This switch tells \lstinline!latexindent.pl! to look for commands that + can split \emph{braces} across lines, such as \lstinline!parbox!, \lstinline!tikzset!, etc. In older + versions of \lstinline!latexindent.pl! you had to specify each one in \lstinline!checkunmatched!--this + clearly became tedious, hence the introduction of \lstinline!alwaysLookforSplitBraces!. + + \emph{As long as you leave this switch on (set to 1) you don't need to specify which + commands can split braces across lines--you can ignore the + fields \lstinline!checkunmatched! and \lstinline!checkunmatchedELSE! described + later on \cpageref{lst:checkunmatched}}. + \item[\verbitem{alwaysLookforSplitBrackets}] \lstinline!1! + + This switch tells \lstinline!latexindent.pl! to look for commands that + can split \emph{brackets} across lines, such as \lstinline!psSolid!, \lstinline!pgfplotstabletypeset!, + etc. In older versions of \lstinline!latexindent.pl! you had to specify each one in \lstinline!checkunmatchedbracket!-- + this clearly became tedious, hence the introduction of \lstinline!alwaysLookforSplitBraces!. + + \emph{As long as you leave this switch on (set to 1) you don't need to specify which + commands can split brackets across lines--you can ignore \lstinline!checkunmatchedbracket! described later on + \cpageref{lst:checkunmatched}}. + + \item[\verbitem{removeTrailingWhitespace}] \lstinline!0! + + By default \lstinline!latexindent.pl! indents every line (including empty lines) + which creates `trailing white space' feared by most version control systems. If + this option is set to \lstinline!1!, trailing white space is removed from all + lines, also non-empty ones. In general this should not create any problems, but + by precaution this option is turned off by default. Thanks to \cite{vosskuhle} for + providing this feature. + + \item[\verbitem{lookForAlignDelims}] This is the first example of a field + in \lstinline!defaultSettings.yaml! that has more than one line; \cref{lst:aligndelims:basic} + shows more details. In fact, the fields in \verbitem{lookForAlignDelims} can actually + take two different forms: the \emph{basic} version is shown in \cref{lst:aligndelims:basic} + and the \emph{advanced} version in \cref{lst:aligndelims:advanced}; we will discuss each in turn. + + \begin{cmhlistings}[style=yaml]{\lstinline!lookForAlignDelims! (basic)}{lst:aligndelims:basic} +lookForAlignDelims: + tabular: 1 + tabularx: 1 + longtable: 1 + array: 1 + matrix: 1 + bmatrix: 1 + pmatrix: 1 + align: 1 + align*: 1 + alignat: 1 + alignat*: 1 + aligned: 1 + cases: 1 + dcases: 1 + pmatrix: 1 + listabla: 1 + \end{cmhlistings} + + The environments specified in this field will be operated on in a special way by \lstinline!latexindent.pl!. In particular, it will try and align each column by its alignment + tabs. It does have some limitations (discussed further in \cref{sec:knownlimitations}), + but in many cases it will produce results such as those in \cref{lst:tabularbefore:basic,lst:tabularafter:basic}. + + \begin{minipage}{.5\textwidth} + \begin{cmhlistings}[style=demo,columns=fixed]{\lstinline!tabular! before}{lst:tabularbefore:basic} +\begin{tabular}{cccc} +1& 2 &3 &4\\ +5& &6 &\\ +\end{tabular} + \end{cmhlistings} + \end{minipage}% + \begin{minipage}{.5\textwidth} + \begin{cmhlistings}[style=demo,columns=fixed]{\lstinline!tabular! after (basic)}{lst:tabularafter:basic} +\begin{tabular}{cccc} + 1 & 2 & 3 & 4 \\ + 5 & & 6 & \\ +\end{tabular} + \end{cmhlistings} + \end{minipage} + + If you find that \lstinline!latexindent.pl! does not perform satisfactorily on such + environments then you can either remove them from \lstinline!lookForAlignDelims! altogether, or set the relevant key to \lstinline!0!, for example \lstinline!tabular: 0!, or if you just want to ignore \emph{specific} + instances of the environment, you could wrap them in something from \lstinline!noIndentBlock! (see \cref{lst:noIndentBlock}). + + If you wish to remove the alignment of the \lstinline!\\! within a delimiter-aligned block, then the + advanced form of \lstinline!lookForAlignDelims! shown in \cref{lst:aligndelims:advanced} is for you. + \begin{cmhlistings}[style=yaml]{\lstinline!lookForAlignDelims! (advanced)}{lst:aligndelims:advanced} +lookForAlignDelims: + tabular: + delims: 1 + alignDoubleBackSlash: 0 + spacesBeforeDoubleBackSlash: 0 + tabularx: + delims: 1 + longtable: 1 + \end{cmhlistings} + + Note that you can use a mixture of the basic and advanced form: in \cref{lst:aligndelims:advanced} \lstinline!tabular! and \lstinline!tabularx! + are advanced and \lstinline!longtable! is basic. When using the advanced form, each field should receive at least 1 sub-field, and \emph{can} (but does not have to) receive up to 3 fields: + \begin{itemize} + \item \lstinline!delims!: switch equivalent to simply specifying, for example, \lstinline!tabular: 1! in + the basic version shown in \cref{lst:aligndelims:basic} (default: 1); + \item \lstinline!alignDoubleBackSlash!: switch to determine if \lstinline!\\! should be aligned (default: 1); + \item \lstinline!spacesBeforeDoubleBackSlash!: optionally, specifies the number of spaces to be inserted + before (non-aligned) \lstinline!\\!. In order to use this field, \lstinline!alignDoubleBackSlash! needs + to be set to 0 (default: 0). + \end{itemize} + + With the settings shown in \cref{lst:aligndelims:advanced} we receive the before-and-after results shown in + \cref{lst:tabularbefore:advanced,lst:tabularafter:advanced}; note that the ampersands have been aligned, but + the \lstinline!\\! have not (compare the alignment of \lstinline!\\! in \cref{lst:tabularafter:basic,lst:tabularafter:advanced}). + + \begin{minipage}{.5\textwidth} + \begin{cmhlistings}[style=demo,columns=fixed]{\lstinline!tabular! before }{lst:tabularbefore:advanced} +\begin{tabular}{cccc} +1& 2 &3 &4\\ +5& &6 &\\ +\end{tabular} + \end{cmhlistings} + \end{minipage}% + \begin{minipage}{.5\textwidth} + \begin{cmhlistings}[style=demo,columns=fixed]{\lstinline!tabular! after (advanced)}{lst:tabularafter:advanced} +\begin{tabular}{cccc} + 1 & 2 & 3 & 4\\ + 5 & & 6 &\\ +\end{tabular} + \end{cmhlistings} + \end{minipage} + + Using \lstinline!spacesBeforeDoubleBackSlash: 3! gives \cref{lst:tabularbefore:spacing,lst:tabularafter:spacing}, + note the spacing before the \lstinline!\\! in \cref{lst:tabularafter:spacing}. + + \begin{minipage}{.5\textwidth} + \begin{cmhlistings}[style=demo,columns=fixed]{\lstinline!tabular! before}{lst:tabularbefore:spacing} +\begin{tabular}{cccc} +1& 2 &3 &4\\ +5& &6 &\\ +\end{tabular} + \end{cmhlistings} + \end{minipage}% + \begin{minipage}{.5\textwidth} + \begin{cmhlistings}[style=demo,columns=fixed]{\lstinline!tabular! after (spacing)}{lst:tabularafter:spacing} +\begin{tabular}{cccc} + 1 & 2 & 3 & 4 \\ + 5 & & 6 & \\ +\end{tabular} + \end{cmhlistings} + \end{minipage} + + + + + If you have blocks of code that you wish to align at the \& character that + are \emph{not} wrapped in, for example, \lstinline!\begin{tabular}...\end{tabular}!, then you use the mark up + illustrated in \cref{lst:alignmentmarkup}. Note that the \lstinline!%*! must be next to + each other, but that there can be any number of spaces (possibly none) between the + \lstinline!*! and \lstinline!\begin{tabular}!; note also that you may use any + environment name that you have specified in \lstinline!lookForAlignDelims!. + \begin{cmhlistings}[style=demo,columns=fixed]{Mark up for aligning delimiters outside of environments}{lst:alignmentmarkup} +\matrix{% +%* \begin{tabular} + 1 & 2 & 3 & 4 \\ + 5 & & 6 & \\ +%* \end{tabular} +} + \end{cmhlistings} + + \item[\verbitem{verbatimEnvironments}] A field that contains a list of environments + that you would like left completely alone--no indentation will be done + to environments that you have specified in this field--see \cref{lst:verbatimEnvironments}. + + + \begin{cmhlistings}[style=yaml]{\lstinline!verbatimEnvironments!}{lst:verbatimEnvironments} +verbatimEnvironments: + verbatim: 1 + lstlisting: 1 + \end{cmhlistings} + Note that if you put an environment in \lstinline!verbatimEnvironments! + and in other fields such as \lstinline!lookForAlignDelims! or \lstinline!noAdditionalIndent! + then \lstinline!latexindent.pl! will \emph{always} prioritize \lstinline!verbatimEnvironments!. + + \item[\verbitem{noIndentBlock}] If you have a block of code that you don't + want \lstinline!latexindent.pl! to touch (even if it is \emph{not} a verbatim-like + environment) then you can wrap it in an environment from \lstinline!noIndentBlock!; + you can use any name you like for this, provided you populate it as demonstrate in + \cref{lst:noIndentBlock}. + + \begin{cmhlistings}[style=yaml]{\lstinline!noIndentBlock!}{lst:noIndentBlock} +noIndentBlock: + noindent: 1 + cmhtest: 1 + \end{cmhlistings} + + Of course, you don't want to have to specify these as null environments + in your code, so you use them with a comment symbol, \lstinline!%!, followed + by as many spaces (possibly none) as you like; see \cref{lst:noIndentBlockdemo} for + example. + \begin{cmhlistings}[style=demo,escapeinside={(*@}{@*)}]{\lstinline!noIndentBlock! demonstration}{lst:noIndentBlockdemo} +%(*@@*) \begin{noindent} + this code + won't + be touched + by + latexindent.pl! +%(*@@*)\end{noindent} + \end{cmhlistings} + + \item[\verbitem{noAdditionalIndent}] If you would prefer some of your + environments or commands not to receive any additional indent, then + populate \lstinline!noAdditionalIndent!; see \cref{lst:noAdditionalIndent}. + Note that these environments will still receive the \emph{current} level + of indentation unless they belong to \lstinline!verbatimEnvironments!, or \lstinline!noIndentBlock!. + + \begin{cmhlistings}[style=yaml]{\lstinline!noAdditionalIndent!}{lst:noAdditionalIndent} +noAdditionalIndent: + document: 1 + myexample: 1 + mydefinition: 1 + problem: 1 + exercises: 1 + mysolution: 1 + foreach: 0 + widepage: 1 + comment: 1 + \[: 1 + \]: 1 + frame: 0 + \end{cmhlistings} + Note in particular from \cref{lst:noAdditionalIndent} that if you wish content within + \lstinline!\[! and \lstinline!\]! to receive no additional indentation then + you have to specify \emph{both} as \lstinline!1! (the default is \lstinline!0!). + If you do not specify both as the same value you may get some interesting results! + \item[\verbitem{indentRules}] If\label{page:indentRules} you would prefer to specify + individual rules for certain environments or commands, just + populate \lstinline!indentRules!; see \cref{lst:indentRules} + + \begin{cmhlistings}[style=yaml]{\lstinline!indentRules!}{lst:indentRules} +indentRules: + myenvironment: "\t\t" + anotherenvironment: "\t\t\t\t" + \[: "\t" + \end{cmhlistings} %%%%%\] just here to stop vim from colouring the rest of my code + Note that in contrast to \lstinline!noAdditionalIndent! you do \emph{not} + need to specify both \lstinline!\[! and \lstinline!\]! in this field. + + If you put an environment in both \lstinline!noAdditionalIndent! and in + \lstinline!indentRules! then \lstinline!latexindent.pl! will resolve the conflict + by ignoring \lstinline!indentRules! and prioritizing \lstinline!noAdditionalIndent!. + You will get a warning message in \lstinline!indent.log!; note that you will only + get one warning message per command or environment. Further discussion + is given in \cref{sec:fieldhierachy}. + + \item[\verbitem{indentAfterHeadings}] This field enables the user to specify + indentation rules that take effect after heading commands such as \lstinline!\part!, \lstinline!\chapter!, + \lstinline!\section!, \lstinline!\subsection*! etc. This field is slightly different from most + of the fields that we have considered previously, because each element is + itself a field which has two elements: \lstinline!indent! and \lstinline!level!. (Similar + in structure to the advanced form of \lstinline!lookForAlignDelims! in \cref{lst:aligndelims:advanced}.) + \begin{cmhlistings}[style=yaml]{\lstinline!indentAfterHeadings!}{lst:indentAfterHeadings} +indentAfterHeadings: + part: + indent: 0 + level: 1 + chapter: + indent: 0 + level: 2 + section: + indent: 0 + level: 3 + ... + \end{cmhlistings} + The default settings do \emph{not} place indentation after a heading--you + can easily switch them on by changing \lstinline!indent: 0! to \lstinline!indent: 1!. + The \lstinline!level! field tells \lstinline!latexindent.pl! the hierarchy of the heading + structure in your document. You might, for example, like to have both \lstinline!section! + and \lstinline!subsection! set with \lstinline!level: 3! because you do not want the indentation to go too deep. + + You can add any of your own custom heading commands to this field, specifying the \lstinline!level! + as appropriate. You can also specify your own indentation in \lstinline!indentRules!-- + you will find the default \lstinline!indentRules! contains \lstinline!chapter: " "! which + tells \lstinline!latexindent.pl! simply to use a space character after \lstinline!\chapter! headings + (once \lstinline!indent! is set to \lstinline!1! for \lstinline!chapter!). + + \item[\verbitem{indentAfterItems}] The environments specified in \lstinline!indentAfterItems! tell + \lstinline!latexindent.pl! to look for \lstinline!\item! commands; if these switches are set to \lstinline!1! + then indentation will be performed so as indent the code after each \lstinline!item!. + \begin{cmhlistings}{\lstinline!indentAfterItems!}{lst:indentafteritems} +indentAfterItems: + itemize: 1 + enumerate: 1 + \end{cmhlistings} + A demonstration is given in \cref{lst:itemsbefore,lst:itemsafter} + + \begin{minipage}{.5\textwidth} + \begin{cmhlistings}[style=demo,xleftmargin=-3mm,columns=fixed]{\lstinline!items! before}{lst:itemsbefore} +\begin{itemize} +\item some text here +some more text here +some more text here +\item another item +\end{itemize} + \end{cmhlistings} + \end{minipage}% + \begin{minipage}{.5\textwidth} + \begin{cmhlistings}[style=demo,xleftmargin=-3mm,columns=fixed]{\lstinline!items! after}{lst:itemsafter} +\begin{itemize} + \item some text here + some more text here + some more text here + \item another item +\end{itemize} + \end{cmhlistings} + \end{minipage} + + \item[\verbitem{itemNames}] If you have your own \lstinline!item! commands (perhaps you + prefer to use \lstinline!myitem!, for example) + then you can put populate them in \lstinline!itemNames!. + For example, users of the \lstinline!exam! document class might like to add + \lstinline!parts! to \lstinline!indentAfterItems! and \lstinline!part! to \lstinline!itemNames! + to their user settings--see \vref{sec:indentconfig} for details of how to configure user settings, + and \vref{lst:mysettings} in particular.\label{page:examsettings} + + \item[\verbitem{constructIfElseFi}] The commands specified in this field + will tell \lstinline!latexindent.pl! to look for constructs that + have the form \lstinline!\if...! \lstinline!\else...! \lstinline!\fi!, such as, + for example, \lstinline!\ifnum!; see \cref{lst:iffibefore,lst:iffiafter} for + a before-and-after demonstration. + + \begin{minipage}{.5\textwidth} + \begin{cmhlistings}[style=demo,xleftmargin=-3mm,columns=fixed]{\lstinline!if-else-fi! construct before}{lst:iffibefore} +\ifnum\radius>5 +\ifnum\radius<16 +\draw[decorate,... +\fi +\fi + \end{cmhlistings} + \end{minipage}% + \begin{minipage}{.5\textwidth} + \begin{cmhlistings}[style=demo,xleftmargin=-3mm,columns=fixed]{\lstinline!if-else-fi! construct after}{lst:iffiafter} +\ifnum\radius>5 + \ifnum\radius<16 + \draw[decorate,... + \fi +\fi + \end{cmhlistings} + \end{minipage} + + \item[\verbitem{fileExtensionPreference}] \lstinline!latexindent.pl! can be called to + act on a file without + specifying the file extension. For example we can call \lstinline!latexindent.pl myfile! + in which case the script will look for \lstinline!myfile! with the extensions + specified in \lstinline!fileExtensionPreference! in their numeric order. If + no match is found, the script will exit. As with all of the fields, you should + change and/or add to this as necessary. + \begin{cmhlistings}[style=yaml]{\lstinline!fileExtensionPreference!}{lst:fileExtensionPreference} +fileExtensionPreference: + .tex: 1 + .sty: 2 + .cls: 3 + .bib: 4 + \end{cmhlistings} + Calling \lstinline!latexindent.pl myfile! with the details specified in \cref{lst:fileExtensionPreference} + means that the script will first look for \lstinline!myfile.tex!, then \lstinline!myfile.sty!, \lstinline!myfile.cls!, + and finally \lstinline!myfile.bib! in order. +\item[\verbitem{logFilePreferences}] + \lstinline!latexindent.pl! writes information to \lstinline!indent.log!, some + of which can be customised by changing \lstinline!logFilePreferences!; see \cref{lst:logFilePreferences}. +\begin{cmhlistings}[style=yaml]{\lstinline!logFilePreferences!}{lst:logFilePreferences} +logFilePreferences: + showEveryYamlRead: 1 + showAlmagamatedSettings: 0 + endLogFileWith: '--------------' + traceModeIncreaseIndent: '>>' + traceModeAddCurrentIndent: '||' + traceModeDecreaseIndent: '<<' + traceModeBetweenLines: "\n" + \end{cmhlistings} +If you load your own user settings (see \vref{sec:indentconfig}) then \lstinline!latexindent.pl! will +detail them in \lstinline!indent.log!; you can choose not to have the details logged by switching +\lstinline!showEveryYamlRead! to \lstinline!0!. Once all of your settings have +been loaded, you can see the amalgamated settings by switching \lstinline!showAlmagamatedSettings! +to \lstinline!1!, if you wish. The log file will end with the characters +given in \lstinline!endLogFileWith!. + +When \lstinline!trace! mode is active (see \cpageref{page:traceswitch}) verbose information is written +to \lstinline!indent.log!. The decoration of this information can be customised through the remaining +fields given in \cref{lst:logFilePreferences}; note, in particular, the use of \lstinline!"\n"! for +escaped characters (using single quotes will not produce the same results). + +\item[\verbitem{fileContentsEnvironments}] + \lstinline!latexindent.pl! determines when the main document begins by looking for \lstinline!\begin{document}!; + it will not do so when inside any of the environments specified in \lstinline!fileContentsEnvironments!, see + \cref{lst:fileContentsEnvironments}. +\begin{cmhlistings}[style=yaml]{\lstinline!fileContentsEnvironments!}{lst:fileContentsEnvironments} +fileContentsEnvironments: + filecontents: 1 + filecontents*: 1 + \end{cmhlistings} + + \begin{warning} + \emph{The following fields are marked in red, as they are not necessary + unless you wish to micro-manage your indentation scheme. + Note that in each case, you should \emph{not} use the backslash.} + \end{warning} + + % to anyone reading the source code- I know the next line isn't the + % correct way to do it :) + \item[\color{red}\verbitem{checkunmatched}] Assuming you keep \lstinline!alwaysLookforSplitBraces! set to \lstinline!1! (which + is the default) then you don't need to worry about \lstinline!checkunmatched!. + + Should you wish to deactivate \lstinline!alwaysLookforSplitBraces! by setting it to \lstinline!0!, then + you can populate \lstinline!checkunmatched! with commands that can split braces across + lines--see \cref{lst:checkunmatched}. + + \begin{cmhlistings}[style=yaml]{\lstinline!checkunmatched!}{lst:checkunmatched} +checkunmatched: + parbox: 1 + vbox: 1 + \end{cmhlistings} + \item[\color{red}\verbitem{checkunmatchedELSE}] Similarly, assuming you keep \lstinline!alwaysLookforSplitBraces! set to \lstinline!1! (which + is the default) then you don't need to worry about \lstinline!checkunmatchedELSE!. + + As in \lstinline!checkunmatched!, should you wish to deactivate \lstinline!alwaysLookforSplitBraces! by setting it to \lstinline!0!, then + you can populate \lstinline!checkunmatchedELSE! with commands that can split braces across + lines \emph{and} have an `else' statement--see \cref{lst:checkunmatchedELSE}. + + \begin{cmhlistings}[style=yaml]{\lstinline!checkunmatchedELSE!}{lst:checkunmatchedELSE} +checkunmatchedELSE: + pgfkeysifdefined: 1 + DTLforeach: 1 + ifthenelse: 1 + \end{cmhlistings} + \item[\color{red}\verbitem{checkunmatchedbracket}] Assuming you keep \lstinline!alwaysLookforSplitBrackets! + set to \lstinline!1! (which is the default) then you don't need to worry about \lstinline!checkunmatchedbracket!. + + Should you wish to deactivate \lstinline!alwaysLookforSplitBrackets! by setting it + to \lstinline!0!, then you can populate \lstinline!checkunmatchedbracket! with commands that can + split \emph{brackets} across lines--see \cref{lst:checkunmatchedbracket}. + + \begin{cmhlistings}[style=yaml]{\lstinline!checkunmatchedbracket!}{lst:checkunmatchedbracket} +checkunmatchedbracket: + psSolid: 1 + pgfplotstablecreatecol: 1 + pgfplotstablesave: 1 + pgfplotstabletypeset: 1 + mycommand: 1 + \end{cmhlistings} +\end{itemize} + +\subsubsection{Hierarchy of fields}\label{sec:fieldhierachy} +After reading the previous section, it should sound reasonable that +\lstinline!noAdditionalIndent!, \lstinline!indentRules!, and +\lstinline!verbatim! all serve mutually exclusive tasks. Naturally, you may +well wonder what happens if you choose to ask \lstinline!latexindent.pl! to +prioritize one above the other. + +For example, let's say that (after reading \cref{sec:indentconfig}) you put the fields in \cref{lst:conflict} into +one of your settings files. +\begin{cmhlistings}[style=yaml]{Conflicting ideas}{lst:conflict} +indentRules: + myenvironment: "\t\t" +noAdditionalIndent: + myenvironment: 1 +\end{cmhlistings} + +Clearly these fields conflict: first of all +you are telling \lstinline!latexindent.pl! that \lstinline!myenvironment! should +receive two tabs of indentation, and then you are telling it +not to put any indentation in the environment. \lstinline!latexindent.pl! +will always make the decision to prioritize \lstinline!noAdditionalIndent! above +\lstinline!indentRules! regardless of the order that you load them in +your settings file. The first +time it encounters \lstinline!myenvironment! it will put a warning in \lstinline!indent.log! +and delete the offending key from \lstinline!indentRules! so that any future +conflicts will not have to be addressed. + +Let's consider another conflicting example in \cref{lst:bigconflict} +\begin{cmhlistings}[style=yaml]{More conflicting ideas}{lst:bigconflict} +lookForAlignDelims: + myenvironment: 1 +verbatimEnvironments: + myenvironment: 1 +\end{cmhlistings} +This is quite a significant conflict--we are first of all telling \lstinline!latexindent.pl! +to look for alignment delimiters in \lstinline!myenvironment! and then +telling it that actually we would like \lstinline!myenvironment! to be considered +as a \lstinline!verbatim!-like environment. Regardless of the order that we +state \cref{lst:bigconflict} the \lstinline!verbatim! instruction will always win. +As in \cref{lst:conflict} you will only receive a warning in \lstinline!indent.log! the +first time \lstinline!latexindent.pl! encounters \lstinline!myenvironment! as the +offending key is deleted from \lstinline!lookForAlignDelims!. + +To summarize, \lstinline!latexindent.pl! will prioritize the various fields in the +following order: +\begin{enumerate} + \item \lstinline!verbatimEnvironments! + \item \lstinline!noAdditionalIndent! + \item \lstinline!indentRules! +\end{enumerate} +\subsection{\lstinline!indentconfig.yaml! and \lstinline!.indentconfig.yaml! (for user settings)}\label{sec:indentconfig} +Editing \lstinline!defaultSettings.yaml! is not ideal as it may be overwritten when +updating your distribution--a better way to customize the settings to your liking +is to set up your own settings file, +\lstinline!mysettings.yaml! (or any name you like, provided it ends with \lstinline!.yaml!). +The only thing you have to do is tell \lstinline!latexindent.pl! where to find it. + +\lstinline!latexindent.pl! will always check your home directory for \lstinline!indentconfig.yaml! +and \lstinline!.indentconfig.yaml! (unless +it is called with the \lstinline!-d! switch), +which is a plain text file you can create that contains the \emph{absolute} +paths for any settings files that you wish \lstinline!latexindent.pl! to load. There is no difference +between \lstinline!indentconfig.yaml! and \lstinline!.indentconfig.yaml!, other than the +fact that \lstinline!.indentconfig.yaml! is a `hidden' file; thank you to \cite{jacobo-diaz-hidden-config} +for providing this feature. In what follows, we will use \lstinline!indentconfig.yaml!, but it +is understood that this equally represents \lstinline!.indentconfig.yaml! as well. If you +have both files in existence, \lstinline!indentconfig.yaml! takes priority. + +For Mac and Linux users, their home directory is \lstinline!~/username! while +Windows (Vista onwards) is \lstinline!C:\Users\username! \footnote{If you're not sure + where to put \lstinline!indentconfig.yaml!, don't + worry \lstinline!latexindent.pl! will tell you in the log file exactly where to +put it assuming it doesn't exist already.} +\Cref{lst:indentconfig} shows a sample \lstinline!indentconfig.yaml! file. + +\begin{cmhlistings}[style=yaml]{\lstinline!indentconfig.yaml! (sample)}{lst:indentconfig} +# Paths to user settings for latexindent.pl +# +# Note that the settings will be read in the order you +# specify here- each successive settings file will overwrite +# the variables that you specify + +paths: +- /home/cmhughes/Documents/yamlfiles/mysettings.yaml +- /home/cmhughes/folder/othersettings.yaml +- /some/other/folder/anynameyouwant.yaml +- C:\Users\chughes\Documents\mysettings.yaml +- C:\Users\chughes\Desktop\test spaces\more spaces.yaml +\end{cmhlistings} + +Note that the \lstinline!.yaml! files you specify in \lstinline!indentconfig.yaml! +will be loaded in the order that you write them in. Each file doesn't have +to have every switch from \lstinline!defaultSettings.yaml!; in fact, I recommend +that you only keep the switches that you want to \emph{change} in these +settings files. + +To get started with your own settings file, you might like to save a copy of +\lstinline!defaultSettings.yaml! in another directory and call it, for +example, \lstinline!mysettings.yaml!. Once you have added the path to \lstinline!indentconfig.yaml! +feel free to start changing the switches and adding more environments to it +as you see fit--have a look at \cref{lst:mysettings} for an example +that uses four tabs for the default indent, adds the \lstinline!tabbing! +environment to the list of environments that contains alignment delimiters, +and adds the changes we described on \cpageref{page:examsettings}. + +\begin{cmhlistings}[style=yaml]{\lstinline!mysettings.yaml! (example)}{lst:mysettings} +# Default value of indentation +defaultIndent: "\t\t\t\t" + +# environments that have tab delimiters, add more +# as needed +lookForAlignDelims: + tabbing: 1 + +# If you use the exam documentclass, you might +# like the following settings +# environments that have \item commands +indentAfterItems: + parts: 1 + +# commands to be treated like \item +itemNames: + part: 1 +\end{cmhlistings} + +You can make sure that your settings are loaded by checking \lstinline!indent.log! +for details--if you have specified a path that \lstinline!latexindent.pl! doesn't +recognize then you'll get a warning, otherwise you'll get confirmation that +\lstinline!latexindent.pl! has read your settings file \footnote{Windows users + may find that they have to end \lstinline!.yaml! files with a blank line}. + +\begin{warning} + When editing \lstinline!.yaml! files it is \emph{extremely} important + to remember how sensitive they are to spaces. I highly recommend copying + and pasting from \lstinline!defaultSettings.yaml! when you create your + first \lstinline!whatevernameyoulike.yaml! file. + + If \lstinline!latexindent.pl! can not read your \lstinline!.yaml! file it + will tell you so in \lstinline!indent.log!. +\end{warning} + +\subsection{\lstinline!localSettings.yaml!}\label{sec:localsettings} +You may remember on \cpageref{page:localswitch} we discussed the \lstinline!-l! switch +that tells \lstinline!latexindent.pl! to look for \lstinline!localSettings.yaml! in the +\emph{same directory} as \lstinline!myfile.tex!. This settings file will +be read \emph{after} \lstinline!defaultSettings.yaml! and, assuming they exist, +user settings. + +The \emph{local} settings file may be called \lstinline!localSettings.yaml!, and +it can contain any switches that you'd +like to change--a sample is shown in \cref{lst:localSettings}. + +\begin{cmhlistings}[style=yaml]{\lstinline!localSettings.yaml! (example)}{lst:localSettings} +# Default value of indentation +defaultIndent: " " + +# environments that have tab delimiters, add more +# as needed +lookForAlignDelims: + tabbing: 0 + +# verbatim environments- environments specified +# in this hash table will not be changed at all! +verbatimEnvironments: + cmhenvironment: 0 +\end{cmhlistings} + +You can make sure that your local settings are loaded by checking \lstinline!indent.log! +for details--if \lstinline!localSettings.yaml! can not be read then you will +get a warning, otherwise you'll get confirmation that +\lstinline!latexindent.pl! has read \lstinline!localSettings.yaml!. + +If you'd prefer to name your \lstinline!localSettings.yaml! file something different, (say, \lstinline!myyaml.yaml!) then +you can call \lstinline!latexindent.pl! using, for example, \lstinline[breaklines=true]!latexindent.pl -l=myyaml.yaml myfile.tex!. + +\subsection{Settings load order}\label{sec:loadorder} +\lstinline!latexindent.pl! loads the settings files in the following order: +\begin{enumerate} + \item \lstinline!defaultSettings.yaml! is always loaded, and can not be renamed; + \item \lstinline!anyUserSettings.yaml! and any other arbitrarily-named files specified in \lstinline!indentconfig.yaml!; + \item \lstinline!localSettings.yaml! but only if found in the same directory as \lstinline!myfile.tex! and called + with \lstinline!-l! switch; this file can be renamed, provided that the call to \lstinline!latexindent.pl! is adjusted + accordingly (see \cref{sec:localsettings}). +\end{enumerate} +A visual representation of this is given in \cref{fig:loadorder}. + +\begin{figure} + \centering + \begin{tikzpicture}[ + needed/.style={very thick, draw=blue,fill=blue!20, + text centered, minimum height=2.5em,rounded corners=1ex}, + optional/.style={draw=black, very thick,scale=0.8, + text centered, minimum height=2.5em,rounded corners=1ex}, + optionalfill/.style={fill=black!10}, + connections/.style={draw=black!30,dotted,line width=3pt,text=red}, + ] + % Draw diagram elements + \node (latexindent) [needed,circle] {\lstinline!latexindent.pl!}; + \node (default) [needed,above right=.5cm of latexindent] {\lstinline!defaultSettings.yaml!}; + \node (indentconfig) [optional,right=of latexindent] {\lstinline!indentconfig.yaml!}; + \node (any) [optional,optionalfill,above right=of indentconfig] {\lstinline!any.yaml!}; + \node (name) [optional,optionalfill,right=of indentconfig] {\lstinline!name.yaml!}; + \node (you) [optional,optionalfill,below right=of indentconfig] {\lstinline!you.yaml!}; + \node (want) [optional,optionalfill,below=of indentconfig] {\lstinline!want.yaml!}; + \node (local) [optional,below=of latexindent] {\lstinline!localSettings.yaml!}; + % Draw arrows between elements + \draw[connections,solid] (latexindent) to[in=-90]node[pos=0.5,anchor=north]{1} (default.south) ; + \draw[connections,optional] (latexindent) -- node[pos=0.5,anchor=north]{2} (indentconfig) ; + \draw[connections,optional] (indentconfig) to[in=-90] (any.south) ; + \draw[connections,optional] (indentconfig) -- (name) ; + \draw[connections,optional] (indentconfig) to[out=-45,in=90] (you) ; + \draw[connections,optional] (indentconfig) -- (want) ; + \draw[connections,optional] (latexindent) -- node[pos=0.5,anchor=west]{3} (local) ; + \end{tikzpicture} + \caption{Schematic of the load order described in \cref{sec:loadorder}; solid lines represent + mandatory files, dotted lines represent optional files. \lstinline!indentconfig.yaml! can + contain as many files as you like--the files will be loaded in order; if you specify + settings for the same field in more than one file, the most recent takes priority. } + \label{fig:loadorder} +\end{figure} + +\subsection{An important example} +I was working on a document that had the text shown in \cref{lst:casestudy}. +\begin{cmhlistings}[style=demo,escapeinside={(*@}{@*)}]{When to set \lstinline!alwaysLookforSplitBrackets=0!}{lst:casestudy} +Hence determine how many zeros the function $h(x)=f(x)-g(x)$ +has on the interval $[0,9)$.(*@\label{line:interval1}@*) +\begin{shortsolution} + The function $h$ has $10$ zeros on the interval $[0,9)$.(*@\label{line:interval2}@*) +\end{shortsolution} +\end{cmhlistings} +I had allowed \lstinline!alwaysLookforSplitBrackets=1!, which is the default setting. +Unfortunately, this caused undesired results, as \lstinline!latexindent.pl! thought that the opening +\lstinline![! in the interval notation (\cref{line:interval1,line:interval2}) +was an opening brace that needed to be closed (with a corresponding \lstinline!]!). Clearly +this was inappropriate, but also expected since \lstinline!latexindent.pl! was simply +following its matching rules. + +In this particular instance, I set up \lstinline!localSettings.yaml! +to contain \lstinline!alwaysLookforSplitBrackets: 0! and then specified the commands +that could split brackets across lines (such as \lstinline!begin{axis}!) individually +in \lstinline!checkunmatchedbracket!. Another option would have been to wrap the +the line in an environment from \lstinline!noIndentBlock! which treats its contents +as a verbatim environment. + + +\section{Known limitations}\label{sec:knownlimitations} +There are a number of known limitations of the script, and almost certainly quite a +few that are \emph{unknown}! + +The main limitation is to do with the alignment routine of environments that contain +delimiters--in other words, environments that are entered in \lstinline!lookForAlignDelims!. +Indeed, this is the only part of the script that can \emph{potentially} remove +lines from \lstinline!myfile.tex!. Note that \lstinline!indent.log! will always +finish with a comparison of line counts before and after. + +The routine works well for `standard' blocks of code that have the same number of \lstinline!&! +per line, but it will not do anything for lines that do not--such examples +include \lstinline!tabular! environments that use \lstinline!\multicolumn! or +perhaps spread cell contents across multiple lines. For each alignment block (\lstinline!tabular!, +\lstinline!align!, etc) \lstinline!latexindent.pl! first of all makes a record +of the maximum number of \lstinline!&!; if each row does not have that +number of \lstinline!&! then it will not try to format that row. Details +will be given in \lstinline!indent.log! assuming that \lstinline!trace! mode +is active. + +If you have a \lstinline!verbatim!-like environment inside a \lstinline!tabular!-like +environment, the \lstinline!verbatim! environment \emph{will} be formatted, which +is probably not what you want. I hope to address this in future versions, but for the +moment wrap it in a \lstinline!noIndentBlock! (see \cpageref{lst:noIndentBlockdemo}). + +You can run \lstinline!latexindent! on \lstinline!.sty!, \lstinline!.cls! and any filetypes +that you specify in \lstinline[breaklines=true]!fileExtensionPreference! (see \vref{lst:fileExtensionPreference}); +if you find a case in which the script struggles, please feel free +to report it at \cite{latexindent-home}, and +in the meantime, consider using a \lstinline!noIndentBlock! (see \cpageref{lst:noIndentBlockdemo}). + +I hope that this script is useful to some; if you find an example where the +script does not behave as you think it should, the best way to contact me is to +report an issue on \cite{latexindent-home}; otherwise, feel free to find me on +the \url{http://tex.stackexchange.com} site; I'm often around +and in the chat room. + +\nocite{*} +\section{References} +\printbibliography[heading=subbibnumbered,title={External links},notkeyword=contributor] +\printbibliography[env=specialbib,heading=subbibnumbered,title={Contributors\label{sec:contributors}},keyword=contributor] + +\appendix +\section{Required \lstinline!Perl! modules}\label{sec:requiredmodules} +If you intend to use \lstinline!latexindent.pl! and \emph{not} one of the supplied standalone executable files, then you will need a few standard Perl modules--if you can run the +minimum code in \cref{lst:helloworld} (\lstinline!perl helloworld.pl!) then you will be able to run \lstinline!latexindent.pl!, otherwise you may +need to install the missing modules. + +\begin{cmhlistings}[language=Perl]{\lstinline!helloworld.pl!}{lst:helloworld} +#!/usr/bin/perl + +use strict; +use warnings; +use FindBin; +use YAML::Tiny; +use File::Copy; +use File::Basename; +use Getopt::Long; +use File::HomeDir; + +print "hello world"; +exit; +\end{cmhlistings} +My default installation on Ubuntu 12.04 did \emph{not} come +with all of these modules as standard, but Strawberry Perl for Windows \cite{strawberryperl} +did. + +Installing the modules given in \cref{lst:helloworld} will vary depending on your +operating system and \lstinline!Perl! distribution. For example, Ubuntu users +might visit the software center, or else run +\begin{lstlisting}[numbers=none] +sudo perl -MCPAN -e 'install "File::HomeDir"' +\end{lstlisting} + +Linux users may be interested in exploring Perlbrew \cite{perlbrew}; possible installation and setup +options follow for Ubuntu (other distributions will need slightly different commands). +\begin{lstlisting}[numbers=none] +sudo apt-get install perlbrew +perlbrew install perl-5.20.1 +perlbrew switch perl-5.20.1 +sudo apt-get install curl +curl -L http://cpanmin.us | perl - App::cpanminus +cpanm YAML::Tiny +cpanm File::HomeDir +\end{lstlisting} + +Strawberry Perl users on Windows might use +\lstinline!CPAN client!. All of the modules are readily available on CPAN \cite{cpan}. + +As of Version 2.1, \lstinline!indent.log! will contain details of the location +of the Perl modules on your system. \lstinline!latexindent.exe! is a standalone +executable for Windows (and therefore does not require a Perl distribution) and caches copies of the Perl modules onto your system; if you +wish to see where they are cached, use the \lstinline!trace! option, e.g \lstinline!latexindent.exe -t myfile.tex!. + +\section{The \lstinline!arara! rule} +The \lstinline!arara! rule (\lstinline!indent.yaml!) contains lines such as those +given in \cref{lst:arararule}. With this setup, the user \emph{always} has +to specify whether or not they want (in this example) to use the \lstinline!trace! +identifier. +\begin{cmhlistings}[style=yaml,numbers=none]{The \lstinline!arara! rule}{lst:arararule} +... +arguments: +- identifier: trace + flag: <arara> @{ isTrue( parameters.trace, "-t" ) } +... +\end{cmhlistings} + +If you would like to have the \lstinline!trace! option on by default every time you +call \lstinline!latexindent.pl! from \lstinline!arara! (without having to write \lstinline!% arara: indent: {trace: yes}!), then simply +amend \cref{lst:arararule} so that it looks like \cref{lst:arararulemod}. +\begin{cmhlistings}[style=yaml,numbers=none]{The \lstinline!arara! rule (modified)}{lst:arararulemod} +... +arguments: +- identifier: trace + flag: <arara> @{ isTrue( parameters.trace, "-t" ) } + default: "-t" +... +\end{cmhlistings} + +With this modification in place, you now simply to write \lstinline!% arara: indent! and +\lstinline!trace! mode will be activated by default. If you wish to turn off \lstinline!trace! +mode then you can write \lstinline!% arara: indent: {trace: off}!. + +Of course, you can apply these types of modifications to \emph{any} of the identifiers, +but proceed with caution if you intend to do this for \lstinline!overwrite!. + +\section{Updating the \lstinline!path! variable}\label{sec:updating-path} +\lstinline!latexindent.pl! ships with a few scripts that can update the \lstinline!path! variables +\footnote{Thanks to \cite{jasjuang} for this feature!}. If you're +on a Linux or Mac machine, then you'll want \lstinline!CMakeLists.txt! from \cite{latexindent-home}. +\subsection{Add to path for Linux} +To add \lstinline!latexindent.pl! to the path for Linux, follow these steps: +\begin{enumerate} + \item download \lstinline!latexindent.pl!, \lstinline!defaultSettings.yaml!, to your + chosen directory from \cite{latexindent-home} ; + \item within your directory, create a directory called \lstinline!path-helper-files! and + download \lstinline!CMakeLists.txt! and \lstinline!cmake_uninstall.cmake.in! + from \cite{latexindent-home}/path-helper-files to this directory; + \item run \lstinline!ls /usr/local/bin! to see what is \emph{currently} in there; + \item run the commands given in \cref{linux-add-to-path}; + \item run \lstinline!ls /usr/local/bin! again to check that \lstinline!latexindent.pl! and \lstinline!defaultSettings.yaml! + have been added. +\end{enumerate} +\begin{cmhlistings}[style=yaml,numbers=none]{Add to path from a Linux terminal}{linux-add-to-path} +sudo apt-get install cmake +sudo apt-get update && sudo apt-get install build-essential +mkdir build && cd build +cmake ../path-helper-files +sudo make install +\end{cmhlistings} +To \emph{remove} the files, run \lstinline!sudo make uninstall!. +\subsection{Add to path for Windows} +To add \lstinline!latexindent.exe! to the path for Windows, follow these steps: +\begin{enumerate} + \item download \lstinline!latexindent.exe!, \lstinline!defaultSettings.yaml!, \lstinline!add-to-path.bat! + from \cite{latexindent-home} to your chosen directory; + \item open a command prompt and run \lstinline!echo %path%! to see what is \emph{currently} in your \lstinline!%path%! variable; + \item right click on \lstinline!add-to-path.bat! and \emph{Run as administrator}; + \item log out, and log back in; + \item open a command prompt and run \lstinline!echo %path%! to check that the appropriate directory has been added to your + \lstinline!%path%!. +\end{enumerate} +To \emph{remove} the directory from your \lstinline!%path%!, run \lstinline!remove-from-path.bat! as administrator. +\end{document} |