summaryrefslogtreecommitdiff
path: root/support/latexindent/documentation/sec-indent-config-and-settings.tex
diff options
context:
space:
mode:
Diffstat (limited to 'support/latexindent/documentation/sec-indent-config-and-settings.tex')
-rw-r--r--support/latexindent/documentation/sec-indent-config-and-settings.tex132
1 files changed, 65 insertions, 67 deletions
diff --git a/support/latexindent/documentation/sec-indent-config-and-settings.tex b/support/latexindent/documentation/sec-indent-config-and-settings.tex
index ddce5c806b..f2084506cc 100644
--- a/support/latexindent/documentation/sec-indent-config-and-settings.tex
+++ b/support/latexindent/documentation/sec-indent-config-and-settings.tex
@@ -2,26 +2,26 @@
\section{indentconfig.yaml, local settings and the -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.
+ load \texttt{defaultSettings.yaml}, but there are a few ways that you can tell it to load
+ your own settings files.
\subsection{indentconfig.yaml and .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}
+ \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}
@@ -41,14 +41,14 @@ paths:
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.
+ 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
+ \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.
@@ -67,8 +67,8 @@ lookForAlignDelims:
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 recognise
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}.
+ has read your settings file \footnote{Windows users may find that they have to end
+ \texttt{.yaml} files with a blank line}.
\index{warning!editing YAML files}
\begin{warning}
@@ -82,23 +82,23 @@ lookForAlignDelims:
\end{warning}
If you find that%
- \announce*{2021-06-19}{encoding option for indentconfig.yaml}
- \texttt{latexindent.pl} does not read your YAML file, then it might be as a result of the
- default commandline encoding not being UTF-8; normally this will only occcur for Windows
- users. In this case, you might like to explore the \texttt{encoding} option for
- \texttt{indentconfig.yaml} as demonstrated in \cref{lst:indentconfig-encoding}.
+ \announce{2021-06-19}{encoding option for indentconfig.yaml} \texttt{latexindent.pl} does not read your YAML file, then it
+ might be as a result of the default commandline encoding not being UTF-8; normally this
+ will only occcur for Windows users. In this case, you might like to explore the
+ \texttt{encoding} option for \texttt{indentconfig.yaml} as demonstrated in
+ \cref{lst:indentconfig-encoding}.
- \cmhlistingsfromfile*{demonstrations/encoding.yaml}[yaml-TCB]{The \texttt{encoding} option for \texttt{indentconfig.yaml}}{lst:indentconfig-encoding}
+ \cmhlistingsfromfile{demonstrations/encoding.yaml}[yaml-TCB]{The \texttt{encoding} option for \texttt{indentconfig.yaml}}{lst:indentconfig-encoding}
- Thank you to \cite{qiancy98} for this contribution; please see
- \vref{app:encoding} and details within \cite{encoding} for further information.
+ Thank you to \cite{qiancy98} for this contribution; please see \vref{app:encoding} and
+ details within \cite{encoding} for further information.
\subsection{localSettings.yaml and friends}\label{sec:localsettings}
The \texttt{-l} switch tells \texttt{latexindent.pl} to look for
\texttt{localSettings.yaml} and/or friends in the \emph{same directory} as
- \texttt{myfile.tex}. For%
- \announce{2021-03-14}*{-l switch: localSettings and friends}
- example, if you use the following command
+ \texttt{myfile.tex}. For%
+ \announce{2021-03-14}*{-l
+ switch: localSettings and friends} example, if you use the following command
\index{switches!-l demonstration}
\begin{commandshell}
latexindent.pl -l myfile.tex
@@ -124,9 +124,9 @@ latexindent.pl -l myfile.tex
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}.
+ 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
@@ -141,44 +141,41 @@ verbatimEnvironments:
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.
+ 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 -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:
+ \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:
\index{verbatim!verbatimEnvironments demonstration (-y switch)}
\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:
+ Note the use of \texttt{;} to specify another field within \texttt{verbatimEnvironments}.
+ This is shorthand, and equivalent, to using the following command:
\index{switches!-y demonstration}
\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,
+ 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,
\index{switches!-l demonstration}
\index{switches!-y demonstration}
\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.
+ Any settings specified using the \texttt{-y} switch will be loaded \emph{after} any
+ specified using \texttt{indentconfig.yaml} and the \texttt{-l} switch.
If you wish to specify any regex-based settings using the \texttt{-y} switch,
- \index{regular expressions!using -y switch} it is important not to use quotes surrounding the regex; for
- example, with reference to the `one sentence per line' feature (\vref{sec:onesentenceperline})
- and the listings within \vref{lst:sentencesEndWith}, the following settings give the option
- to have sentences end with a semicolon
+ \index{regular expressions!using -y switch} it is important not to use quotes surrounding
+ the regex; for example, with reference to the `one sentence per line' feature
+ (\vref{sec:onesentenceperline}) and the listings within \vref{lst:sentencesEndWith}, the
+ following settings give the option to have sentences end with a semicolon
\index{switches!-y demonstration}
\begin{commandshell}
latexindent.pl -m --yaml='modifyLineBreaks:oneSentencePerLine:sentencesEndWith:other:\;'
@@ -191,15 +188,16 @@ latexindent.pl -m --yaml='modifyLineBreaks:oneSentencePerLine:sentencesEndWith:o
\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 \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.
+ \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}.