diff options
author | Karl Berry <karl@freefriends.org> | 2018-08-14 22:01:47 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2018-08-14 22:01:47 +0000 |
commit | a54d196b0fc4715e3d2dbcfe62cfccea6aae57fe (patch) | |
tree | 40ebe5b6f9da50b68cd6ae2546a9e32124cb46ed /Master/texmf-dist/doc/support/latexindent/sec-indent-config-and-settings.tex | |
parent | 2feb602ca10b928ee4cba97b3ae95a8ef6b853d4 (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.tex | 139 |
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}. |