summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/support/latexindent/sec-indent-config-and-settings.tex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2018-08-14 22:01:47 +0000
committerKarl Berry <karl@freefriends.org>2018-08-14 22:01:47 +0000
commita54d196b0fc4715e3d2dbcfe62cfccea6aae57fe (patch)
tree40ebe5b6f9da50b68cd6ae2546a9e32124cb46ed /Master/texmf-dist/doc/support/latexindent/sec-indent-config-and-settings.tex
parent2feb602ca10b928ee4cba97b3ae95a8ef6b853d4 (diff)
latexindent (15aug18)
git-svn-id: svn://tug.org/texlive/trunk@48402 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/support/latexindent/sec-indent-config-and-settings.tex')
-rw-r--r--Master/texmf-dist/doc/support/latexindent/sec-indent-config-and-settings.tex139
1 files changed, 74 insertions, 65 deletions
diff --git a/Master/texmf-dist/doc/support/latexindent/sec-indent-config-and-settings.tex b/Master/texmf-dist/doc/support/latexindent/sec-indent-config-and-settings.tex
index db5f61621ee..f69fda83dee 100644
--- a/Master/texmf-dist/doc/support/latexindent/sec-indent-config-and-settings.tex
+++ b/Master/texmf-dist/doc/support/latexindent/sec-indent-config-and-settings.tex
@@ -1,28 +1,28 @@
% arara: pdflatex: {shell: yes, files: [latexindent]}
\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.
+ 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{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
+ 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.
+ 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
@@ -39,20 +39,19 @@ paths:
- 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.
+ 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.
+ \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
@@ -64,10 +63,10 @@ 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
+ 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}
@@ -81,26 +80,29 @@ lookForAlignDelims:
\end{warning}
\subsection{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
+ 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}.
+ 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,
+ 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}.
+ 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.
+ 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
@@ -110,43 +112,50 @@ 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:
+ 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:
+ 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,
+ 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.
+ 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.
+ \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}.