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
|
% arara: pdflatex: {shell: yes, files: [latexindent]}
\section{\texttt{indentconfig.yaml}, local settings and the \texttt{-y} switch }\label{sec:indentconfig}
The behaviour of \texttt{latexindent.pl} is controlled from the settings specified
in any of the YAML files that you tell it to load. By default, \texttt{latexindent.pl}
will only load \texttt{defaultSettings.yaml}, but there are a few ways that you can
tell it to load your own settings files.
\subsection{\texttt{indentconfig.yaml} and \texttt{{.indentconfig.yaml}}}
\texttt{latexindent.pl} will always check your home directory for \texttt{indentconfig.yaml}
and \texttt{.indentconfig.yaml} (unless
it is called with the \texttt{-d} switch),
which is a plain text file you can create that contains the \emph{absolute}
paths for any settings files that you wish \texttt{latexindent.pl} to load. There is no difference
between \texttt{indentconfig.yaml} and \texttt{.indentconfig.yaml}, other than the
fact that \texttt{.indentconfig.yaml} is a `hidden' file; thank you to \cite{jacobo-diaz-hidden-config}
for providing this feature. In what follows, we will use \texttt{indentconfig.yaml}, but it
is understood that this could equally represent \texttt{.indentconfig.yaml}. If you
have both files in existence then \texttt{indentconfig.yaml} takes priority.
For Mac and Linux users, their home directory is \texttt{~/username} while
Windows (Vista onwards) is \lstinline!C:\Users\username!\footnote{If you're not sure
where to put \texttt{indentconfig.yaml}, don't
worry \texttt{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 \texttt{indentconfig.yaml} file.
\begin{yaml}{\texttt{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{yaml}
Note that the \texttt{.yaml} files you specify in \texttt{indentconfig.yaml}
will be loaded in the order in which you write them. Each file doesn't have
to have every switch from \texttt{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
\texttt{defaultSettings.yaml} in another directory and call it, for
example, \texttt{mysettings.yaml}. Once you have added the path to \texttt{indentconfig.yaml}
you can change the switches and add more code-block names 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 \texttt{tabbing}
environment/command to the list of environments that contains alignment delimiters; you might also like to
refer to the many YAML files detailed throughout the rest of this documentation.
\begin{yaml}{\texttt{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
\end{yaml}
You can make sure that your settings are loaded by checking \texttt{indent.log}
for details -- if you have specified a path that \texttt{latexindent.pl} doesn't
recognize then you'll get a warning, otherwise you'll get confirmation that
\texttt{latexindent.pl} has read your settings file \footnote{Windows users
may find that they have to end \texttt{.yaml} files with a blank line}.
\begin{warning}
When editing \texttt{.yaml} files it is \emph{extremely} important
to remember how sensitive they are to spaces. I highly recommend copying
and pasting from \texttt{defaultSettings.yaml} when you create your
first \texttt{whatevernameyoulike.yaml} file.
If \texttt{latexindent.pl} can not read your \texttt{.yaml} file it
will tell you so in \texttt{indent.log}.
\end{warning}
\subsection{\texttt{localSettings.yaml}}\label{sec:localsettings}
The \texttt{-l} switch tells \texttt{latexindent.pl} to look for \texttt{localSettings.yaml} in the
\emph{same directory} as \texttt{myfile.tex}. For example, if you use the following command
\begin{commandshell}
latexindent.pl -l myfile.tex
\end{commandshell}
then \texttt{latexindent.pl} will (assuming it exists) load \texttt{localSettings.yaml} from the same directory
as \texttt{myfile.tex}.
If you'd prefer to name your \texttt{localSettings.yaml} file something
different, (say, \texttt{mysettings.yaml} as in \cref{lst:mysettings}) then
you can call \texttt{latexindent.pl} using, for example,
\begin{commandshell}
latexindent.pl -l=mysettings.yaml myfile.tex
\end{commandshell}
Any settings file(s) specified using the \texttt{-l} switch will be read \emph{after} \texttt{defaultSettings.yaml} and, assuming they exist,
any user setting files specified in \texttt{indentconfig.yaml}.
Your settings file can contain any switches that you'd
like to change; a sample is shown in \cref{lst:localSettings}, and you'll find plenty of further examples throughout this manual.
\begin{yaml}{\texttt{localSettings.yaml} (example)}{lst:localSettings}
# verbatim environments - environments specified
# here will not be changed at all!
verbatimEnvironments:
cmhenvironment: 0
myenv: 1
\end{yaml}
You can make sure that your settings file has been loaded by checking \texttt{indent.log}
for details; if it can not be read then you receive a warning, otherwise you'll get confirmation that
\texttt{latexindent.pl} has read your settings file.
\subsection{The \texttt{-y|yaml} switch}\label{sec:yamlswitch}
You%
\announce*{2017-08-21}{demonstration of the -y switch} may use the \texttt{-y} switch to load
your settings; for example, if you wished to specify the settings from \cref{lst:localSettings}
using the \texttt{-y} switch, then you could use the following command:
\begin{commandshell}
latexindent.pl -y="verbatimEnvironments:cmhenvironment:0;myenv:1" myfile.tex
\end{commandshell}
Note the use of \texttt{;} to specify another field within \texttt{verbatimEnvironments}. This is
shorthand, and equivalent, to using the following command:
\begin{commandshell}
latexindent.pl -y="verbatimEnvironments:cmhenvironment:0,verbatimEnvironments:myenv:1" myfile.tex
\end{commandshell}
You may, of course, specify settings using the \texttt{-y} switch as well as, for example,
settings loaded using the \texttt{-l} switch; for example,
\begin{commandshell}
latexindent.pl -l=mysettings.yaml -y="verbatimEnvironments:cmhenvironment:0;myenv:1" myfile.tex
\end{commandshell}
Any settings specified using the \texttt{-y} switch will be loaded \emph{after} any specified
using \texttt{indentconfig.yaml} and the \texttt{-l} switch.
\subsection{Settings load order}\label{sec:loadorder}
\texttt{latexindent.pl} loads the settings files in the following order:
\begin{enumerate}
\item \texttt{defaultSettings.yaml} is always loaded, and can not be renamed;
\item \texttt{anyUserSettings.yaml} and any other arbitrarily-named files specified in \texttt{indentconfig.yaml};
\item \texttt{localSettings.yaml} but only if found in the same directory as \texttt{myfile.tex} and called
with \texttt{-l} switch; this file can be renamed, provided that the call to \texttt{latexindent.pl} is adjusted
accordingly (see \cref{sec:localsettings}). You may specify both relative and absolute%
\announce*{2017-08-21}*{-l absolute paths} paths to other
YAML files using the \texttt{-l} switch, separating multiple files using commas;
\item any settings%
\announce*{2017-08-21}{-y switch load order} specified in the \texttt{-y} switch.
\end{enumerate}
A visual representation of this is given in \cref{fig:loadorder}.
\begin{figure}[!htb]
\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] {\texttt{latexindent.pl}};
\node (default) [needed,above right=.5cm of latexindent] {\texttt{defaultSettings.yaml}};
\node (indentconfig) [optional,right=of latexindent] {\texttt{indentconfig.yaml}};
\node (any) [optional,optionalfill,above right=of indentconfig] {\texttt{any.yaml}};
\node (name) [optional,optionalfill,right=of indentconfig] {\texttt{name.yaml}};
\node (you) [optional,optionalfill,below right=of indentconfig] {\texttt{you.yaml}};
\node (want) [optional,optionalfill,below=of indentconfig] {\texttt{want.yaml}};
\node (local) [optional,below=of latexindent] {\texttt{localSettings.yaml}};
\node (yamlswitch) [optional,left=of latexindent] {\texttt{-y switch}};
% 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) ;
\draw[connections,optional] (latexindent) -- node[pos=0.5,anchor=north]{4} (yamlswitch) ;
\end{tikzpicture}
\caption{Schematic of the load order described in \cref{sec:loadorder}; solid lines represent
mandatory files, dotted lines represent optional files. \texttt{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}
|
