From 0fe7398600cc177e0daad519a135544e9ca250e3 Mon Sep 17 00:00:00 2001
From: Karl Berry <karl@freefriends.org>
Date: Mon, 4 Apr 2022 20:57:57 +0000
Subject: latexindent (4apr22)

git-svn-id: svn://tug.org/texlive/trunk@62906 c570f23f-e606-0410-a88d-b1316a301751
---
 .../latexindent/sec-indent-config-and-settings.tex | 286 ++++++++++-----------
 1 file changed, 143 insertions(+), 143 deletions(-)

(limited to 'Master/texmf-dist/doc/support/latexindent/sec-indent-config-and-settings.tex')

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 b25cc70b7bc..600d24bb4fc 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
@@ -6,25 +6,25 @@
  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}
-	shows a sample \texttt{indentconfig.yaml} file.
-
-	\begin{yaml}{\texttt{indentconfig.yaml} (sample)}{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}
 # Paths to user settings for latexindent.pl
 #
 # Note that the settings will be read in the order you
@@ -39,22 +39,22 @@ 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.
-
-	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. \index{indentation!defaultIndent using YAML
-	file}
-
-	\begin{yaml}{\texttt{mysettings.yaml} (example)}{lst:mysettings}
+ 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. \index{indentation!defaultIndent using YAML
+ file}
+
+ \begin{yaml}{\texttt{mysettings.yaml} (example)}{lst:mysettings}
 # Default value of indentation
 defaultIndent: "\t\t\t\t"
 
@@ -64,73 +64,73 @@ 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 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}. \index{warning!editing YAML files}
+ 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}. \index{warning!editing YAML files}
 
-	\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.
+ \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}
+  If \texttt{latexindent.pl} can not read your \texttt{.yaml} file it will tell you so in
+  \texttt{indent.log}.
+ \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}.%
+ 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}.%
 
-	\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
-	\index{switches!-l demonstration}
-	\begin{commandshell}
+ 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
+ \index{switches!-l demonstration}
+ \begin{commandshell}
 latexindent.pl -l myfile.tex
 \end{commandshell}
-	then \texttt{latexindent.pl} will search for and then, assuming they exist, load each of
-	the following files in the following order:
-	\begin{enumerate}
-		\item localSettings.yaml
-		\item latexindent.yaml
-		\item .localSettings.yaml
-		\item .latexindent.yaml
-	\end{enumerate}
-	These files will be assumed to be in the same directory as \texttt{myfile.tex}, or
-	otherwise in the current working directory. You do not need to have all of the above
-	files, usually just one will be sufficient. In what follows, whenever we refer to
-	\texttt{localSettings.yaml} it is assumed that it can mean any of the four named options
-	listed above.
-
-	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}
+ then \texttt{latexindent.pl} will search for and then, assuming they exist, load each of
+ the following files in the following order:
+ \begin{enumerate}
+  \item localSettings.yaml
+  \item latexindent.yaml
+  \item .localSettings.yaml
+  \item .latexindent.yaml
+ \end{enumerate}
+ These files will be assumed to be in the same directory as \texttt{myfile.tex}, or
+ otherwise in the current working directory. You do not need to have all of the above
+ files, usually just one will be sufficient. In what follows, whenever we refer to
+ \texttt{localSettings.yaml} it is assumed that it can mean any of the four named options
+ listed above.
+
+ 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. \index{verbatim!verbatimEnvironments demonstration (-l switch)}
+ 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. \index{verbatim!verbatimEnvironments demonstration (-l switch)}
 
-	\begin{yaml}{\texttt{localSettings.yaml} (example)}{lst:localSettings}
+ \begin{yaml}{\texttt{localSettings.yaml} (example)}{lst:localSettings}
 #  verbatim environments - environments specified
 #  here will not be changed at all!
 verbatimEnvironments:
@@ -138,70 +138,70 @@ 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:
-	\index{verbatim!verbatimEnvironments demonstration (-y switch)}
-	\begin{commandshell}
+ 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:
+ \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: \index{switches!-y
-	demonstration}
-	\begin{commandshell}
+ 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, \index{switches!-l
-	demonstration} \index{switches!-y demonstration}
-	\begin{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, \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.
-
-	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{switches!-y demonstration}
-	\begin{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.
+
+ 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{switches!-y demonstration}
+ \begin{commandshell}
 latexindent.pl -m --yaml='modifyLineBreaks:oneSentencePerLine:sentencesEndWith:other:\;'
 \end{commandshell}
 
 \subsection{Settings load order}\label{sec:loadorder}
-	\texttt{latexindent.pl} loads the settings files in the following order:
-	\index{switches!-l in relation to other settings}
-	\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
-		\input{figure-schematic}
-		\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}
+ \texttt{latexindent.pl} loads the settings files in the following order:
+ \index{switches!-l in relation to other settings}
+ \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
+  \input{figure-schematic}
+  \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}
-- 
cgit v1.2.3

