summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/support/latexindent/subsec-commands-and-their-options.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/subsec-commands-and-their-options.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/subsec-commands-and-their-options.tex')
-rw-r--r--Master/texmf-dist/doc/support/latexindent/subsec-commands-and-their-options.tex180
1 files changed, 106 insertions, 74 deletions
diff --git a/Master/texmf-dist/doc/support/latexindent/subsec-commands-and-their-options.tex b/Master/texmf-dist/doc/support/latexindent/subsec-commands-and-their-options.tex
index 2f4412faffd..a6caa007060 100644
--- a/Master/texmf-dist/doc/support/latexindent/subsec-commands-and-their-options.tex
+++ b/Master/texmf-dist/doc/support/latexindent/subsec-commands-and-their-options.tex
@@ -1,21 +1,23 @@
% arara: pdflatex: {shell: yes, files: [latexindent]}
\subsection{Commands and the strings between their arguments}\label{subsec:commands-string-between}
- The \texttt{command} code blocks will always look for optional (square bracketed) and
- mandatory (curly braced) arguments which can contain comments, line breaks and
- `beamer' commands \lstinline!<.*?>! between them. There are switches that can allow them to contain
- other strings, which we discuss next.
+ The \texttt{command} code blocks will always look for optional (square bracketed)
+ and mandatory (curly braced) arguments which can contain comments, line breaks and
+ `beamer' commands \lstinline!<.*?>! between them. There are switches that can allow
+ them to contain other strings, which we discuss next.
\yamltitle{commandCodeBlocks}*{fields}
- The \texttt{commandCodeBlocks} field%
- \announce*{2018-04-27}*{commandCodeBlocks} contains a few switches detailed in \cref{lst:commandCodeBlocks}.
+ The \texttt{commandCodeBlocks} field%%%%
+ \announce{2018-04-27}*{commandCodeBlocks}
+ contains a few switches detailed in \cref{lst:commandCodeBlocks}.
- \cmhlistingsfromfile*[style=commandCodeBlocks]*{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{commandCodeBlocks}}{lst:commandCodeBlocks}
+ \cmhlistingsfromfile[style=commandCodeBlocks]*{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{commandCodeBlocks}}{lst:commandCodeBlocks}
\yamltitle{roundParenthesesAllowed}{0|1}
- The need for this field was mostly motivated by commands found in code used to generate images in \texttt{PSTricks} and \texttt{tikz}; for example,
- let's consider the code given in \cref{lst:pstricks1}.
+ The need for this field was mostly motivated by commands found in code used to generate
+ images in \texttt{PSTricks} and \texttt{tikz}; for example, let's consider
+ the code given in \cref{lst:pstricks1}.
\begin{minipage}{.45\textwidth}
\cmhlistingsfromfile{demonstrations/pstricks1.tex}{\texttt{pstricks1.tex}}{lst:pstricks1}
@@ -28,12 +30,15 @@
Notice that the \lstinline!\defFunction! command has an optional argument, followed by a
mandatory argument, followed by a round-parenthesis argument, $(u,v)$.
- By default, because \texttt{roundParenthesesAllowed} is set to $1$ in \cref{lst:commandCodeBlocks}, then \texttt{latexindent.pl}
- will allow round parenthesis between optional and mandatory arguments. In the case of the code in \cref{lst:pstricks1},
- \texttt{latexindent.pl} finds \emph{all} the arguments of \lstinline!defFunction!, both before and after \lstinline!(u,v)!.
+ By default, because \texttt{roundParenthesesAllowed} is set to $1$ in
+ \cref{lst:commandCodeBlocks}, then \texttt{latexindent.pl} will allow round parenthesis between
+ optional and mandatory arguments. In the case of the code in \cref{lst:pstricks1},
+ \texttt{latexindent.pl} finds \emph{all} the arguments of
+ \lstinline!defFunction!, both before and after \lstinline!(u,v)!.
- The default output from running \texttt{latexindent.pl} on \cref{lst:pstricks1} actually leaves it unchanged (see \cref{lst:pstricks1-default});
- note in particular, this is because of \texttt{noAdditionalIndentGlobal} as discussed on \cpageref{page:command:noAddGlobal}.
+ The default output from running \texttt{latexindent.pl} on \cref{lst:pstricks1} actually
+ leaves it unchanged (see \cref{lst:pstricks1-default}); note in particular, this is because of
+ \texttt{noAdditionalIndentGlobal} as discussed on \cpageref{page:command:noAddGlobal}.
Upon using the YAML settings in \cref{lst:noRoundParentheses}, and running the command
\begin{commandshell}
@@ -49,10 +54,13 @@ latexindent.pl pstricks1.tex -l noRoundParentheses.yaml
\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/noRoundParentheses.yaml}[yaml-TCB]{\texttt{noRoundParentheses.yaml}}{lst:noRoundParentheses}
\end{minipage}
- Notice the difference between \cref{lst:pstricks1-default} and \cref{lst:pstricks1-nrp}; in particular, in \cref{lst:pstricks1-nrp}, because
- round parentheses are \emph{not} allowed, \texttt{latexindent.pl} finds that the \lstinline!\defFunction! command finishes at the first opening
- round parenthesis. As such, the remaining braced, mandatory, arguments are found to be \texttt{UnNamedGroupingBracesBrackets} (see \vref{tab:code-blocks})
- which, by default, assume indentation for their body, and hence the tabbed indentation in \cref{lst:pstricks1-nrp}.
+ Notice the difference between \cref{lst:pstricks1-default} and \cref{lst:pstricks1-nrp}; in
+ particular, in \cref{lst:pstricks1-nrp}, because round parentheses are
+ \emph{not} allowed, \texttt{latexindent.pl} finds that the
+ \lstinline!\defFunction! command finishes at the first opening round parenthesis. As such,
+ the remaining braced, mandatory, arguments are found to be \texttt{UnNamedGroupingBracesBrackets} (see \vref{tab:code-blocks}) which,
+ by default, assume indentation for their body, and hence the tabbed indentation in
+ \cref{lst:pstricks1-nrp}.
Let's explore this using the YAML given in \cref{lst:defFunction} and run the command
\begin{commandshell}
@@ -68,11 +76,14 @@ latexindent.pl pstricks1.tex -l defFunction.yaml
\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/defFunction.yaml}[yaml-TCB]{\texttt{defFunction.yaml}}{lst:defFunction}
\end{minipage}
- Notice in \cref{lst:pstricks1-indent-rules} that the \emph{body} of the \lstinline!defFunction! command i.e, the subsequent lines
- containing arguments after the command name, have received the single space of indentation specified by \cref{lst:defFunction}.
+ Notice in \cref{lst:pstricks1-indent-rules} that the \emph{body} of the
+ \lstinline!defFunction! command i.e, the subsequent lines containing arguments after the
+ command name, have received the single space of indentation specified by
+ \cref{lst:defFunction}.
\yamltitle{stringsAllowedBetweenArguments}*{fields}
- \texttt{tikz} users may well specify code such as that given in \cref{lst:tikz-node1}; processing this code using
+ \texttt{tikz} users may well specify code such as that given in
+ \cref{lst:tikz-node1}; processing this code using
\texttt{latexindent.pl} gives the default output in \cref{lst:tikz-node1-default}.
\begin{minipage}{.45\textwidth}
@@ -87,21 +98,24 @@ latexindent.pl pstricks1.tex -l defFunction.yaml
\begin{quote}
to, node, ++
\end{quote}
- are all allowed to appear between arguments; importantly, you are encouraged to add further names
- to this field as necessary. This means that when \texttt{latexindent.pl}
+ are all allowed to appear between arguments; importantly, you are encouraged to add
+ further names to this field as necessary. This means that when \texttt{latexindent.pl}
processes \cref{lst:tikz-node1}, it consumes:
\begin{itemize}
\item the optional argument \lstinline![thin]!
- \item the round-bracketed argument \lstinline!(c)! because \texttt{roundParenthesesAllowed} is $1$ by default
+ \item the round-bracketed argument \lstinline!(c)! because \texttt{roundParenthesesAllowed} is
+ $1$ by default
\item the string \lstinline!to! (specified in \texttt{stringsAllowedBetweenArguments})
\item the optional argument \lstinline![in=110,out=-90]!
\item the string \lstinline!++! (specified in \texttt{stringsAllowedBetweenArguments})
- \item the round-bracketed argument \lstinline!(0,-0.5cm)! because \texttt{roundParenthesesAllowed} is $1$ by default
+ \item the round-bracketed argument \lstinline!(0,-0.5cm)! because \texttt{roundParenthesesAllowed} is
+ $1$ by default
\item the string \lstinline!node! (specified in \texttt{stringsAllowedBetweenArguments})
\item the optional argument \lstinline![below,align=left,scale=0.5]!
\end{itemize}
- We can explore this further, for example using \cref{lst:draw} and running the command
+ We can explore this further, for example using \cref{lst:draw} and running the
+ command
\begin{commandshell}
latexindent.pl tikz-node1.tex -l draw.yaml
\end{commandshell}
@@ -115,10 +129,12 @@ latexindent.pl tikz-node1.tex -l draw.yaml
\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/draw.yaml}[yaml-TCB]{\texttt{draw.yaml}}{lst:draw}
\end{minipage}
- Notice that each line after the \lstinline!\draw! command (its `body') in \cref{lst:tikz-node1-draw} has been given the
- appropriate two-spaces worth of indentation specified in \cref{lst:draw}.
+ Notice that each line after the \lstinline!\draw! command (its `body') in
+ \cref{lst:tikz-node1-draw} has been given the appropriate two-spaces worth of indentation
+ specified in \cref{lst:draw}.
- Let's compare this with the output from using the YAML settings in \cref{lst:no-strings}, and running the command
+ Let's compare this with the output from using the YAML settings in
+ \cref{lst:no-strings}, and running the command
\begin{commandshell}
latexindent.pl tikz-node1.tex -l no-strings.yaml
\end{commandshell}
@@ -129,83 +145,96 @@ latexindent.pl tikz-node1.tex -l no-strings.yaml
\end{minipage}
\hfill
\begin{minipage}{.49\textwidth}
- \cmhlistingsfromfile*[style=yaml-LST]*{demonstrations/no-strings.yaml}[yaml-TCB]{\texttt{no-strings.yaml}}{lst:no-strings}
+ \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/no-strings.yaml}[yaml-TCB]{\texttt{no-strings.yaml}}{lst:no-strings}
\end{minipage}
In this case, \texttt{latexindent.pl} sees that:
\begin{itemize}
- \item the \lstinline!\draw! command finishes after the \lstinline!(c)!, as \texttt{stringsAllowedBetweenArguments} has been set to $0$
- so there are no strings allowed between arguments;
- \item it finds a \texttt{namedGroupingBracesBrackets} called \texttt{to} (see \vref{tab:code-blocks}) \emph{with} argument \lstinline![in=110,out=-90]!
- \item it finds another \texttt{namedGroupingBracesBrackets} but this time called \texttt{node} with argument \lstinline![below,align=left,scale=0.5]!
+ \item the \lstinline!\draw! command finishes after the \lstinline!(c)!, as
+ \texttt{stringsAllowedBetweenArguments} has been set to $0$ so there are no strings
+ allowed between arguments;
+ \item it finds a \texttt{namedGroupingBracesBrackets} called \texttt{to} (see \vref{tab:code-blocks}) \emph{with}
+ argument \lstinline![in=110,out=-90]!
+ \item it finds another \texttt{namedGroupingBracesBrackets} but this time called \texttt{node} with
+ argument \lstinline![below,align=left,scale=0.5]!
\end{itemize}
Referencing \vref{lst:commandCodeBlocks},%
- \announce*{2018-04-27}*{amalgamate feature in commandCodeBlocks}, we see that the first field in
- the \texttt{stringsAllowedBetweenArguments} is \texttt{amalgamate} and is set to \texttt{1} by default. This is for users who wish to
- specify their settings in multiple YAML files. For example, by using the settings in either \cref{lst:amalgamate-demo} or\cref{lst:amalgamate-demo1}
- is equivalent to using the settings in \cref{lst:amalgamate-demo2}.
+ \announce{2018-04-27}*{amalgamate feature in commandCodeBlocks}, we see that the first field in the \texttt{stringsAllowedBetweenArguments} is
+ \texttt{amalgamate} and is set to \texttt{1} by default. This is for
+ users who wish to specify their settings in multiple YAML files. For example, by using
+ the settings in either \cref{lst:amalgamate-demo} or\cref{lst:amalgamate-demo1} is equivalent to
+ using the settings in \cref{lst:amalgamate-demo2}.
\begin{adjustwidth}{-3.5cm}{-1.5cm}
\begin{minipage}{.32\linewidth}
- \cmhlistingsfromfile*[style=yaml-LST]*{demonstrations/amalgamate-demo.yaml}[yaml-TCB]{\texttt{amalgamate-demo.yaml}}{lst:amalgamate-demo}
+ \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/amalgamate-demo.yaml}[yaml-TCB]{\texttt{amalgamate-demo.yaml}}{lst:amalgamate-demo}
\end{minipage}%
\hfill
\begin{minipage}{.32\linewidth}
- \cmhlistingsfromfile*[style=yaml-LST]*{demonstrations/amalgamate-demo1.yaml}[yaml-TCB]{\texttt{amalgamate-demo1.yaml}}{lst:amalgamate-demo1}
+ \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/amalgamate-demo1.yaml}[yaml-TCB]{\texttt{amalgamate-demo1.yaml}}{lst:amalgamate-demo1}
\end{minipage}%
\hfill
\begin{minipage}{.32\linewidth}
- \cmhlistingsfromfile*[style=yaml-LST]*{demonstrations/amalgamate-demo2.yaml}[yaml-TCB]{\texttt{amalgamate-demo2.yaml}}{lst:amalgamate-demo2}
+ \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/amalgamate-demo2.yaml}[yaml-TCB]{\texttt{amalgamate-demo2.yaml}}{lst:amalgamate-demo2}
\end{minipage}
\end{adjustwidth}
- We specify \texttt{amalgamate} to be set to \texttt{0} and in which case any settings loaded prior
- to those specified, including the default, will be overwritten. For example, using the settings
- in \cref{lst:amalgamate-demo3} means that only the strings specified in that field will be used.
+ We specify \texttt{amalgamate} to be set to \texttt{0} and in which case
+ any settings loaded prior to those specified, including the default, will be overwritten.
+ For example, using the settings in \cref{lst:amalgamate-demo3} means that only the strings
+ specified in that field will be used.
- \cmhlistingsfromfile*[style=yaml-LST]*{demonstrations/amalgamate-demo3.yaml}[yaml-TCB]{\texttt{amalgamate-demo3.yaml}}{lst:amalgamate-demo3}
+ \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/amalgamate-demo3.yaml}[yaml-TCB]{\texttt{amalgamate-demo3.yaml}}{lst:amalgamate-demo3}
- It is important to note that the \texttt{amalgamate} field, if used, must be in the first field,
- and specified using the syntax given in \cref{lst:amalgamate-demo1,lst:amalgamate-demo2,lst:amalgamate-demo3}.
+ It is important to note that the \texttt{amalgamate} field, if used, must be in the
+ first field, and specified using the syntax given in \cref{lst:amalgamate-demo1,lst:amalgamate-demo2,lst:amalgamate-demo3}.
- We may explore this feature further with the code in \cref{lst:for-each}, whose default output is given in \cref{lst:for-each-default}.
+ We may explore this feature further with the code in \cref{lst:for-each}, whose
+ default output is given in \cref{lst:for-each-default}.
\begin{minipage}{.45\textwidth}
- \cmhlistingsfromfile*{demonstrations/for-each.tex}{\texttt{for-each.tex}}{lst:for-each}
+ \cmhlistingsfromfile{demonstrations/for-each.tex}{\texttt{for-each.tex}}{lst:for-each}
\end{minipage}
\hfill
\begin{minipage}{.45\textwidth}
- \cmhlistingsfromfile*{demonstrations/for-each-default.tex}{\texttt{for-each} default output}{lst:for-each-default}
+ \cmhlistingsfromfile{demonstrations/for-each-default.tex}{\texttt{for-each} default output}{lst:for-each-default}
\end{minipage}
- Let's compare this with the output from using the YAML settings in \cref{lst:foreach}, and running the command
+ Let's compare this with the output from using the YAML settings in
+ \cref{lst:foreach}, and running the command
\begin{commandshell}
latexindent.pl for-each.tex -l foreach.yaml
\end{commandshell}
given in \cref{lst:for-each-mod1}.
\begin{minipage}{.45\textwidth}
- \cmhlistingsfromfile*{demonstrations/for-each-mod1.tex}{\texttt{for-each.tex} using \cref{lst:foreach}}{lst:for-each-mod1}
+ \cmhlistingsfromfile{demonstrations/for-each-mod1.tex}{\texttt{for-each.tex} using \cref{lst:foreach}}{lst:for-each-mod1}
\end{minipage}
\hfill
\begin{minipage}{.49\textwidth}
- \cmhlistingsfromfile*[style=yaml-LST]*{demonstrations/foreach.yaml}[yaml-TCB]{\texttt{foreach.yaml}}{lst:foreach}
+ \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/foreach.yaml}[yaml-TCB]{\texttt{foreach.yaml}}{lst:foreach}
\end{minipage}
- You might like to compare the output given in \cref{lst:for-each-default} and \cref{lst:for-each-mod1}. Note,in particular, in
- \cref{lst:for-each-default} that the \texttt{foreach} command has not included any of the subsequent strings, and that the braces
- have been treated as a \texttt{namedGroupingBracesBrackets}. In \cref{lst:for-each-mod1} the \texttt{foreach} command has been allowed to have \lstinline!\x/\y! and \texttt{in} between
- arguments because of the settings given in \cref{lst:foreach}.
+ You might like to compare the output given in \cref{lst:for-each-default} and
+ \cref{lst:for-each-mod1}. Note,in particular, in \cref{lst:for-each-default} that the
+ \texttt{foreach} command has not included any of the subsequent strings, and that
+ the braces have been treated as a \texttt{namedGroupingBracesBrackets}. In \cref{lst:for-each-mod1} the
+ \texttt{foreach} command has been allowed to have \lstinline!\x/\y! and
+ \texttt{in} between arguments because of the settings given in
+ \cref{lst:foreach}.
\yamltitle{commandNameSpecial}*{fields}
There are some special command names%
- \announce*{2018-04-27}*{commandNameSpecial} that do not fit within the names recognized by \texttt{latexindent.pl},
- the first one of which is \lstinline!\@ifnextchar[!. From the perspective of \texttt{latexindent.pl}, the whole of the
- text \lstinline!\@ifnextchar[! is a command, because it is
- immediately followed by sets of mandatory arguments. However, without the \texttt{commandNameSpecial} field, \texttt{latexindent.pl}
- would not be able to label it as such, because the \lstinline![! is, necessarily, not matched by a closing \lstinline!]!.
+ \announce{2018-04-27}*{commandNameSpecial} that do not fit within the names recognized by
+ \texttt{latexindent.pl}, the first one of which is \lstinline!\@ifnextchar[!. From the
+ perspective of \texttt{latexindent.pl}, the whole of the text \lstinline!\@ifnextchar[! is
+ a command, because it is immediately followed by sets of mandatory arguments. However,
+ without the \texttt{commandNameSpecial} field, \texttt{latexindent.pl} would not be able to
+ label it as such, because the \lstinline![! is, necessarily, not matched by a
+ closing \lstinline!]!.
- For example, consider the sample file in \cref{lst:ifnextchar}, which has default output in \cref{lst:ifnextchar-default}.
+ For example, consider the sample file in \cref{lst:ifnextchar}, which has default
+ output in \cref{lst:ifnextchar-default}.
\begin{minipage}{.45\textwidth}
\cmhlistingsfromfile{demonstrations/ifnextchar.tex}{\texttt{ifnextchar.tex}}{lst:ifnextchar}
@@ -215,26 +244,29 @@ latexindent.pl for-each.tex -l foreach.yaml
\cmhlistingsfromfile{demonstrations/ifnextchar-default.tex}{\texttt{ifnextchar.tex} default output}{lst:ifnextchar-default}
\end{minipage}
- Notice that in \cref{lst:ifnextchar-default} the \texttt{parbox} command has been able to indent its body, because \texttt{latexindent.pl}
- has successfully found the command \lstinline!\@ifnextchar! first; the pattern-matching of \texttt{latexindent.pl} starts from
- \emph{the inner most <thing> and works outwards}, discussed in more detail on \cpageref{page:phases}.
+ Notice that in \cref{lst:ifnextchar-default} the \texttt{parbox} command has been able
+ to indent its body, because \texttt{latexindent.pl} has successfully found the command
+ \lstinline!\@ifnextchar! first; the pattern-matching of \texttt{latexindent.pl} starts
+ from \emph{the inner most <thing> and works outwards}, discussed in more detail on \cpageref{page:phases}.
- For demonstration, we can compare
- this output with that given in \cref{lst:ifnextchar-off} in which
- the settings from \cref{lst:no-ifnextchar} have dictated that no special command names, including the \lstinline!\@ifnextchar[! command, should not be searched for specially;
- as such, the \texttt{parbox} command has been \emph{unable} to indent its body successfully, because the \lstinline!\@ifnextchar[!
- command has not been found.
+ For demonstration, we can compare this output with that given in \cref{lst:ifnextchar-off}
+ in which the settings from \cref{lst:no-ifnextchar} have dictated that no special command
+ names, including the \lstinline!\@ifnextchar[! command, should not be searched for
+ specially; as such, the \texttt{parbox} command has been \emph{unable}
+ to indent its body successfully, because the \lstinline!\@ifnextchar[! command has not been
+ found.
\begin{minipage}{.45\textwidth}
\cmhlistingsfromfile{demonstrations/ifnextchar-off.tex}{\texttt{ifnextchar.tex} using \cref{lst:no-ifnextchar}}{lst:ifnextchar-off}
\end{minipage}
\hfill
\begin{minipage}{.45\textwidth}
- \cmhlistingsfromfile*[style=yaml-LST]*{demonstrations/no-ifnextchar.yaml}[yaml-TCB]{\texttt{no-ifnextchar.yaml}}{lst:no-ifnextchar}
+ \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/no-ifnextchar.yaml}[yaml-TCB]{\texttt{no-ifnextchar.yaml}}{lst:no-ifnextchar}
\end{minipage}
- The \texttt{amalgamate} field can be used for \texttt{commandNameSpecial}, just as for \texttt{stringsAllowedBetweenArguments}. The
- same condition holds as stated previously, which we state again here:
+ The \texttt{amalgamate} field can be used for \texttt{commandNameSpecial}, just as for
+ \texttt{stringsAllowedBetweenArguments}. The same condition holds as stated previously, which we state
+ again here:
\begin{warning}
It is important to note that the \texttt{amalgamate} field, if used, in either \texttt{commandNameSpecial} or \texttt{stringsAllowedBetweenArguments} must be in the first field,
and specified using the syntax given in \cref{lst:amalgamate-demo1,lst:amalgamate-demo2,lst:amalgamate-demo3}.