diff options
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.tex | 132 |
1 files changed, 65 insertions, 67 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 ddce5c806bf..f2084506ccb 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 @@ -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}. |