diff options
author | Karl Berry <karl@freefriends.org> | 2017-08-22 21:26:11 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2017-08-22 21:26:11 +0000 |
commit | e231f2be95092edeb9fdef8644d3703c56656433 (patch) | |
tree | 35170ff1259e003c847a2953bbd4a316ef36f8de /Master/texmf-dist/doc/support/latexindent/sec-indent-config-and-settings.tex | |
parent | 5b86a262bc6cd64f5fb9f93028dc3e2762361822 (diff) |
latexindent (22aug17)
git-svn-id: svn://tug.org/texlive/trunk@45098 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 | 186 |
1 files changed, 110 insertions, 76 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 a3cffa0921a..988b3a68abd 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,60 +1,60 @@ % arara: pdflatex: {shell: yes, files: [latexindent]} -\section{User, local settings, \texttt{indentconfig.yaml} and \texttt{.indentconfig.yaml}}\label{sec:indentconfig} - Editing \texttt{defaultSettings.yaml} is not ideal as it may be overwritten when - updating your distribution--a better way to customize the settings to your liking - is to set up your own settings file, - \texttt{mysettings.yaml} (or any name you like, provided it ends with \texttt{.yaml}). - The only thing you have to do is tell \texttt{latexindent.pl} where to find it. - - \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 equally represents \texttt{.indentconfig.yaml} as well. If you - have both files in existence, \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 - # specify here- each successive settings file will overwrite - # the variables that you specify - - paths: - - /home/cmhughes/Documents/yamlfiles/mysettings.yaml - - /home/cmhughes/folder/othersettings.yaml - - /some/other/folder/anynameyouwant.yaml - - C:\Users\chughes\Documents\mysettings.yaml - - C:\Users\chughes\Desktop\test spaces\more spaces.yaml +\section{\texttt{indentconfig.yaml}, local settings and the \texttt{-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. + +\subsection{\texttt{indentconfig.yaml} and \texttt{{.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} +# Paths to user settings for latexindent.pl +# +# Note that the settings will be read in the order you +# specify here- each successive settings file will overwrite +# the variables that you specify + +paths: +- /home/cmhughes/Documents/yamlfiles/mysettings.yaml +- /home/cmhughes/folder/othersettings.yaml +- /some/other/folder/anynameyouwant.yaml +- C:\Users\chughes\Documents\mysettings.yaml +- 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 that you write them in. 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. - - \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. + + \begin{yaml}{\texttt{mysettings.yaml} (example)}{lst:mysettings} # Default value of indentation defaultIndent: "\t\t\t\t" @@ -64,48 +64,77 @@ 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 - may find that they have to end \texttt{.yaml} files with a blank line}. + 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} - 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} \subsection{\texttt{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}. If you'd prefer to name your \texttt{localSettings.yaml} file something - different, (say, \texttt{myyaml.yaml}) then + \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}. + + 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=myyaml.yaml 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, - user settings from \texttt{indentconfig.yaml}. + 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. \begin{yaml}{\texttt{localSettings.yaml} (example)}{lst:localSettings} -# verbatim environments- environments specified -# in this hash table will not be changed at all! +# verbatim environments - environments specified +# here will not be changed at all! verbatimEnvironments: cmhenvironment: 0 + 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. +\subsection{The \texttt{-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: + \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: + \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, + \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. + \subsection{Settings load order}\label{sec:loadorder} \texttt{latexindent.pl} loads the settings files in the following order: \begin{enumerate} @@ -113,12 +142,15 @@ verbatimEnvironments: \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 relative paths to other - YAML files using the \texttt{-l} switch, separating multiple files using commas. + 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} + \begin{figure}[!htb] \centering \begin{tikzpicture}[ needed/.style={very thick, draw=blue,fill=blue!20, @@ -137,6 +169,7 @@ verbatimEnvironments: \node (you) [optional,optionalfill,below right=of indentconfig] {\texttt{you.yaml}}; \node (want) [optional,optionalfill,below=of indentconfig] {\texttt{want.yaml}}; \node (local) [optional,below=of latexindent] {\texttt{localSettings.yaml}}; + \node (yamlswitch) [optional,left=of latexindent] {\texttt{-y switch}}; % Draw arrows between elements \draw[connections,solid] (latexindent) to[in=-90]node[pos=0.5,anchor=north]{1} (default.south) ; \draw[connections,optional] (latexindent) -- node[pos=0.5,anchor=north]{2} (indentconfig) ; @@ -145,6 +178,7 @@ verbatimEnvironments: \draw[connections,optional] (indentconfig) to[out=-45,in=90] (you) ; \draw[connections,optional] (indentconfig) -- (want) ; \draw[connections,optional] (latexindent) -- node[pos=0.5,anchor=west]{3} (local) ; + \draw[connections,optional] (latexindent) -- node[pos=0.5,anchor=north]{4} (yamlswitch) ; \end{tikzpicture} \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 |