diff options
Diffstat (limited to 'Master/texmf-dist/doc/support/latexindent/sec-the-m-switch.tex')
-rw-r--r-- | Master/texmf-dist/doc/support/latexindent/sec-the-m-switch.tex | 280 |
1 files changed, 272 insertions, 8 deletions
diff --git a/Master/texmf-dist/doc/support/latexindent/sec-the-m-switch.tex b/Master/texmf-dist/doc/support/latexindent/sec-the-m-switch.tex index 541a66572d2..7e8ddcd50fd 100644 --- a/Master/texmf-dist/doc/support/latexindent/sec-the-m-switch.tex +++ b/Master/texmf-dist/doc/support/latexindent/sec-the-m-switch.tex @@ -1,8 +1,4 @@ % arara: pdflatex: {shell: yes, files: [latexindent]} -% the -m switch -% the -m switch -% the -m switch - \fancyhead[R]{\bfseries\thepage% \tikz[remember picture,overlay] { \node at (1,0){\includegraphics{logo}}; @@ -13,12 +9,12 @@ \yamltitle{modifylinebreaks}*{fields} \begin{wrapfigure}[7]{r}[0pt]{8cm} - \cmhlistingsfromfile[firstnumber=356,linerange={356-358},style=yaml-LST,numbers=left,]{../defaultSettings.yaml}[MLB-TCB,width=.85\linewidth,before=\centering]{\texttt{modifyLineBreaks}}{lst:modifylinebreaks} + \cmhlistingsfromfile[style=modifylinebreaks]{../defaultSettings.yaml}[MLB-TCB,width=.85\linewidth,before=\centering]{\texttt{modifyLineBreaks}}{lst:modifylinebreaks} \end{wrapfigure} \makebox[0pt][r]{% \raisebox{-\totalheight}[0pt][0pt]{% \tikz\node[opacity=1] at (0,0) {\includegraphics[width=4cm]{logo}};}}% - One of the most exciting features of Version 3.0 is the \texttt{-m} switch, which + As of Version 3.0, \texttt{latexindent.pl} has the \texttt{-m} switch, which permits \texttt{latexindent.pl} to modify line breaks, according to the specifications in the \texttt{modifyLineBreaks} field. \emph{The settings in this field will only be considered if the \texttt{-m} switch has been used}. @@ -60,6 +56,275 @@ latexindent.pl myfile.tex -m \cmhlistingsfromfile{demonstrations/mlb1-out.tex}{\texttt{mlb1.tex} out output}{lst:mlb-bl-out} \end{minipage} +\yamltitle{textWrapOptions}*{fields} + When the \texttt{-m} switch is active \texttt{latexindent.pl} has the ability to wrap text using the options + specified in the \texttt{textWrapOptions} field, see \cref{lst:textWrapOptions}. The value of + \texttt{columns} specifies the column at which the text should be wrapped. + By default, the value of \texttt{columns} is \texttt{0}, so \texttt{latexindent.pl} + will \emph{not} wrap text; if you change it to a value of \texttt{2} or more, then + text will be wrapped after the character in the specified column. + + \cmhlistingsfromfile[style=textWrapOptions]{../defaultSettings.yaml}[MLB-TCB,width=.85\linewidth,before=\centering]{\texttt{textWrapOptions}}{lst:textWrapOptions} + + For example, consider the file give in \cref{lst:textwrap1}. + + \begin{widepage} + \cmhlistingsfromfile{demonstrations/textwrap1.tex}{\texttt{textwrap1.tex}}{lst:textwrap1} + \end{widepage} + + Using the file \texttt{textwrap1.yaml} in \cref{lst:textwrap1-yaml}, and running the command + \begin{commandshell} +latexindent.pl -m textwrap1.tex -o textwrap1-mod1.tex -l textwrap1.yaml +\end{commandshell} + we obtain the output in \cref{lst:textwrap1-mod1}. + + \begin{minipage}{.45\linewidth} + \cmhlistingsfromfile{demonstrations/textwrap1-mod1.tex}{\texttt{textwrap1-mod1.tex}}{lst:textwrap1-mod1} + \end{minipage} + \hfill + \begin{minipage}{.45\linewidth} + \cmhlistingsfromfile{demonstrations/textwrap1.yaml}[MLB-TCB]{\texttt{textwrap1.yaml}}{lst:textwrap1-yaml} + \end{minipage} + + The text wrapping routine is performed \emph{after} verbatim environments have been stored, so verbatim + environments and verbatim commands are exempt from the routine. For example, using the file in + \cref{lst:textwrap2}, + \begin{widepage} + \cmhlistingsfromfile{demonstrations/textwrap2.tex}{\texttt{textwrap2.tex}}{lst:textwrap2} + \end{widepage} + and running the following command and continuing to use \texttt{textwrap1.yaml} from \cref{lst:textwrap1-yaml}, + \begin{commandshell} +latexindent.pl -m textwrap2.tex -o textwrap2-mod1.tex -l textwrap1.yaml +\end{commandshell} + then the output is as in \cref{lst:textwrap2-mod1}. + \begin{widepage} + \cmhlistingsfromfile{demonstrations/textwrap2-mod1.tex}{\texttt{textwrap2-mod1.tex}}{lst:textwrap2-mod1} + \end{widepage} + Furthermore, the text wrapping routine is performed after the trailing comments have been + stored, and they are also exempt from text wrapping. For example, using the file in \cref{lst:textwrap3} + \begin{widepage} + \cmhlistingsfromfile{demonstrations/textwrap3.tex}{\texttt{textwrap3.tex}}{lst:textwrap3} + \end{widepage} + and running the following command and continuing to use \texttt{textwrap1.yaml} from \cref{lst:textwrap1-yaml}, + \begin{commandshell} +latexindent.pl -m textwrap3.tex -o textwrap3-mod1.tex -l textwrap1.yaml +\end{commandshell} + then the output is as in \cref{lst:textwrap3-mod1}. + + \cmhlistingsfromfile{demonstrations/textwrap3-mod1.tex}{\texttt{textwrap3-mod1.tex}}{lst:textwrap3-mod1} + + \begin{wrapfigure}[6]{r}[0pt]{8cm} + \cmhlistingsfromfile[style=textWrapOptionsAll]{../defaultSettings.yaml}[MLB-TCB,width=.85\linewidth,before=\centering]{\texttt{textWrapOptions}}{lst:textWrapOptionsAll} + \end{wrapfigure} + The text wrapping routine of \texttt{latexindent.pl} is performed by the \texttt{Text::Wrap} module, which provides a + \texttt{separator} feature to separate lines with characters other than a new line (see \cite{textwrap}). By default, + the separator is empty (see \cref{lst:textWrapOptionsAll}) which means that a new line token will be used, but you can change it as you see fit. + + For example starting with the file in \cref{lst:textwrap4} + + \cmhlistingsfromfile{demonstrations/textwrap4.tex}{\texttt{textwrap4.tex}}{lst:textwrap4} + and using \texttt{textwrap2.yaml} from \cref{lst:textwrap2-yaml} with the following command + \begin{commandshell} +latexindent.pl -m textwrap4.tex -o textwrap4-mod2.tex -l textwrap2.yaml +\end{commandshell} + then we obtain the output in \cref{lst:textwrap4-mod2}. + + \begin{minipage}{.45\linewidth} + \cmhlistingsfromfile{demonstrations/textwrap4-mod2.tex}{\texttt{textwrap4-mod2.tex}}{lst:textwrap4-mod2} + \end{minipage} + \hfill + \begin{minipage}{.45\linewidth} + \cmhlistingsfromfile{demonstrations/textwrap2.yaml}[MLB-TCB]{\texttt{textwrap2.yaml}}{lst:textwrap2-yaml} + \end{minipage} + + \paragraph{Summary of text wrapping} + It is important to note the following: + \begin{itemize} + \item Verbatim environments (\vref{lst:verbatimEnvironments}) and verbatim commands (\vref{lst:verbatimCommands}) will \emph{not} be affected by the text wrapping routine (see \vref{lst:textwrap2-mod1}); + \item comments will \emph{not} be affected by the text wrapping routine (see \vref{lst:textwrap3-mod1}); + \item indentation is performed \emph{after} the text wrapping routine; as such, indented code + will likely exceed any maximum value set in the \texttt{columns} field. + \end{itemize} + +\yamltitle{removeParagraphLineBreaks}*{fields} + When the \texttt{-m} switch is active \texttt{latexindent.pl} has the ability to remove line breaks + from within paragraphs; the behaviour is controlled by the \texttt{removeParagraphLineBreaks} field, detailed in + \cref{lst:removeParagraphLineBreaks}. Thank you to \cite{jowens} for shaping and assisting with the testing of this feature. + + \cmhlistingsfromfile[style=removeParagraphLineBreaks]{../defaultSettings.yaml}[MLB-TCB,width=.85\linewidth,before=\centering]{\texttt{removeParagraphLineBreaks}}{lst:removeParagraphLineBreaks} + + This routine can be turned on \emph{globally} for \emph{every} code block type known to \texttt{latexindent.pl} + (see \vref{tab:code-blocks}) by using the \texttt{all} switch; by default, this switch is \emph{off}. Assuming + that the \texttt{all} switch is off, then the routine can be controlled on a per-code-block-type basis, and + within that, on a per-name basis. We will consider examples of each of these in turn, but + before we do, let's specify what \texttt{latexindent.pl} considers as a paragraph: + \begin{itemize} + \item it must begin on its own line with either an alphabetic or numeric character, and not with any of the + code-block types detailed in \vref{tab:code-blocks}; + \item it can include line breaks, but finishes when it meets either a blank line, a \lstinline!\par! + command, or any of the user-specified settings in the \texttt{paragraphsStopAt} field, + detailed in \vref{lst:paragraphsStopAt}. + \end{itemize} + + Let's start with the \texttt{.tex} file in \cref{lst:shortlines}, together with the YAML settings in + \cref{lst:remove-para1-yaml}. + + \begin{minipage}{.45\linewidth} + \cmhlistingsfromfile{demonstrations/shortlines.tex}{\texttt{shortlines.tex}}{lst:shortlines} + \end{minipage} + \hfill + \begin{minipage}{.49\linewidth} + \cmhlistingsfromfile{demonstrations/remove-para1.yaml}[MLB-TCB]{\texttt{remove-para1.yaml}}{lst:remove-para1-yaml} + \end{minipage} + + Upon running the command + \begin{commandshell} +latexindent.pl -m shortlines.tex -o shortlines1.tex -l remove-para1.yaml +\end{commandshell} + then we obtain the output given in \cref{lst:shortlines1}. + + \cmhlistingsfromfile{demonstrations/shortlines1.tex}{\texttt{shortlines1.tex}}{lst:shortlines1} + + Keen readers may notice that some trailing white space must be present in the file in \cref{lst:shortlines} which + has crept in to the output in \cref{lst:shortlines1}. This can be fixed using the YAML file in + \vref{lst:removeTWS-before} and running, for example, + \begin{commandshell} +latexindent.pl -m shortlines.tex -o shortlines1-tws.tex -l remove-para1.yaml,removeTWS-before.yaml + \end{commandshell} + in which case the output is as in \cref{lst:shortlines1-tws}; notice that the double spaces present in \cref{lst:shortlines1} + have been addressed. + + \cmhlistingsfromfile{demonstrations/shortlines1-tws.tex}{\texttt{shortlines1-tws.tex}}{lst:shortlines1-tws} + + Keeping with the settings in \cref{lst:remove-para1-yaml}, we note that the \texttt{all} switch applies + to \emph{all} code block types. So, for example, let's consider the files in \cref{lst:shortlines-mand,lst:shortlines-opt} + + \begin{minipage}{.45\linewidth} + \cmhlistingsfromfile{demonstrations/shortlines-mand.tex}{\texttt{shortlines-mand.tex}}{lst:shortlines-mand} + \end{minipage} + \hfill + \begin{minipage}{.45\linewidth} + \cmhlistingsfromfile{demonstrations/shortlines-opt.tex}{\texttt{shortlines-opt.tex}}{lst:shortlines-opt} + \end{minipage} + + Upon running the commands + \begin{widepage} + \begin{commandshell} +latexindent.pl -m shortlines-mand.tex -o shortlines-mand1.tex -l remove-para1.yaml +latexindent.pl -m shortlines-opt.tex -o shortlines-opt1.tex -l remove-para1.yaml +\end{commandshell} + \end{widepage} + + then we obtain the respective output given in \cref{lst:shortlines-mand1,lst:shortlines-opt1}. + + \cmhlistingsfromfile{demonstrations/shortlines-mand1.tex}{\texttt{shortlines-mand1.tex}}{lst:shortlines-mand1} + \cmhlistingsfromfile{demonstrations/shortlines-opt1.tex}{\texttt{shortlines-opt1.tex}}{lst:shortlines-opt1} + + Assuming that we turn \emph{off} the \texttt{all} switch (by setting it to \texttt{0}), then + we can control the behaviour of \texttt{removeParagraphLineBreaks} either on a per-code-block-type basis, + or on a per-name basis. + + For example, let's use the code in \cref{lst:shortlines-envs}, and consider the settings in \cref{lst:remove-para2-yaml,lst:remove-para3-yaml}; + note that in \cref{lst:remove-para2-yaml} we specify that \emph{every} environment should receive + treatment from the routine, while in \cref{lst:remove-para3-yaml} we specify that \emph{only} the + \texttt{one} environment should receive the treatment. + + \begin{minipage}{.45\linewidth} + \cmhlistingsfromfile{demonstrations/shortlines-envs.tex}{\texttt{shortlines-envs.tex}}{lst:shortlines-envs} + \end{minipage} + \hfill + \begin{minipage}{.49\linewidth} + \cmhlistingsfromfile{demonstrations/remove-para2.yaml}[MLB-TCB]{\texttt{remove-para2.yaml}}{lst:remove-para2-yaml} + \cmhlistingsfromfile{demonstrations/remove-para3.yaml}[MLB-TCB]{\texttt{remove-para3.yaml}}{lst:remove-para3-yaml} + \end{minipage} + + Upon running the commands + \begin{widepage} + \begin{commandshell} +latexindent.pl -m shortlines-envs.tex -o shortlines-envs2.tex -l remove-para2.yaml +latexindent.pl -m shortlines-envs.tex -o shortlines-envs3.tex -l remove-para3.yaml +\end{commandshell} + \end{widepage} + then we obtain the respective output given in \cref{lst:shortlines-envs2,lst:shortlines-envs3}. + + \cmhlistingsfromfile{demonstrations/shortlines-envs2.tex}{\texttt{shortlines-envs2.tex}}{lst:shortlines-envs2} + \cmhlistingsfromfile{demonstrations/shortlines-envs3.tex}{\texttt{shortlines-envs3.tex}}{lst:shortlines-envs3} + + The remaining code-block types can be customized in analogous ways, although note that \texttt{commands}, + \texttt{keyEqualsValuesBracesBrackets}, \texttt{namedGroupingBracesBrackets}, \texttt{UnNamedGroupingBracesBrackets} + are controlled by the \texttt{optionalArguments} and the \texttt{mandatoryArguments}. + + The only special case is the \texttt{masterDocument} field; this is designed for `chapter'-type files that + may contain paragraphs that are not within any other code-blocks. For example, consider the file in + \cref{lst:shortlines-md}, with the YAML settings in \cref{lst:remove-para4-yaml}. + + \begin{minipage}{.45\linewidth} + \cmhlistingsfromfile{demonstrations/shortlines-md.tex}{\texttt{shortlines-md.tex}}{lst:shortlines-md} + \end{minipage} + \hfill + \begin{minipage}{.49\linewidth} + \cmhlistingsfromfile{demonstrations/remove-para4.yaml}[MLB-TCB]{\texttt{remove-para4.yaml}}{lst:remove-para4-yaml} + \end{minipage} + + Upon running the following command + \begin{widepage} + \begin{commandshell} +latexindent.pl -m shortlines-md.tex -o shortlines-md4.tex -l remove-para4.yaml +\end{commandshell} + \end{widepage} + then we obtain the output in \cref{lst:shortlines-md4}. + \cmhlistingsfromfile{demonstrations/shortlines-md4.tex}{\texttt{shortlines-md4.tex}}{lst:shortlines-md4} + +\yamltitle{paragraphsStopAt}*{fields} + The paragraph line break routine considers blank lines and the \lstinline|\par| command to be the end of a paragraph; + you can fine tune the behaviour of the routine further by using the \texttt{paragraphsStopAt} fields, shown in \cref{lst:paragraphsStopAt}. + + \cmhlistingsfromfile[style=paragraphsStopAt]{../defaultSettings.yaml}[MLB-TCB,width=.85\linewidth,before=\centering]{\texttt{paragraphsStopAt}}{lst:paragraphsStopAt} + + The fields specified in \texttt{paragraphsStopAt} tell \texttt{latexindent.pl} to stop the current paragraph + when it reaches a line that \emph{begins} with any of the code-block types specified as \texttt{1} in \cref{lst:paragraphsStopAt}. + By default, you'll see that the paragraph line break routine will stop when it reaches an environment at the + beginning of a line. It is \emph{not} possible to specify these fields on a per-name basis. + + Let's use the \texttt{.tex} file in \cref{lst:sl-stop}; we will, in turn, consider the settings in + \cref{lst:stop-command-yaml,lst:stop-comment-yaml}. + + \begin{minipage}{.45\linewidth} + \cmhlistingsfromfile{demonstrations/sl-stop.tex}{\texttt{sl-stop.tex}}{lst:sl-stop} + \end{minipage} + \hfill + \begin{minipage}{.49\linewidth} + \cmhlistingsfromfile{demonstrations/stop-command.yaml}[MLB-TCB]{\texttt{stop-command.yaml}}{lst:stop-command-yaml} + + \cmhlistingsfromfile{demonstrations/stop-comment.yaml}[MLB-TCB]{\texttt{stop-comment.yaml}}{lst:stop-comment-yaml} + \end{minipage} + + Upon using the settings from \vref{lst:remove-para4-yaml} and running the commands + \begin{widepage} + \begin{commandshell} +latexindent.pl -m sl-stop.tex -o sl-stop4.tex -l remove-para4.yaml +latexindent.pl -m sl-stop.tex -o sl-stop4-command.tex -l=remove-para4.yaml,stop-command.yaml +latexindent.pl -m sl-stop.tex -o sl-stop4-comment.tex -l=remove-para4.yaml,stop-comment.yaml + \end{commandshell} + \end{widepage} + we obtain the respective outputs in \crefrange{lst:sl-stop4}{lst:sl-stop4-comment}; notice in particular that: + \begin{itemize} + \item in \cref{lst:sl-stop4} the paragraph line break routine has included commands and comments; + \item in \cref{lst:sl-stop4-command} the paragraph line break routine has \emph{stopped} at the + \texttt{emph} command, because in \cref{lst:stop-command-yaml} we have specified \texttt{commands} + to be \texttt{1}, and \texttt{emph} is at the beginning of a line; + \item in \cref{lst:sl-stop4-comment} the paragraph line break routine has \emph{stopped} + at the comments, because in \cref{lst:stop-comment-yaml} we have specified \texttt{comments} + to be \texttt{1}, and the comment is at the beginning of a line. + \end{itemize} + In all outputs in \crefrange{lst:sl-stop4}{lst:sl-stop4-comment} we notice that the paragraph line break + routine has stopped at \lstinline!\begin{myenv}! because, by default, \texttt{environments} + is set to \texttt{1} in \vref{lst:paragraphsStopAt}. + + \cmhlistingsfromfile{demonstrations/sl-stop4.tex}{\texttt{sl-stop4.tex}}{lst:sl-stop4} + \cmhlistingsfromfile{demonstrations/sl-stop4-command.tex}{\texttt{sl-stop4-command.tex}}{lst:sl-stop4-command} + \cmhlistingsfromfile{demonstrations/sl-stop4-comment.tex}{\texttt{sl-stop4-comment.tex}}{lst:sl-stop4-comment} + \subsection{Poly-switches} Every other field in the \texttt{modifyLineBreaks} field uses poly-switches, and can take one of four integer values\footnote{You might like to associate one of the four circles in the logo with one of the four given values}: @@ -78,7 +343,7 @@ latexindent.pl myfile.tex -m after the \texttt{environments} field) and that \emph{per-name} settings are also allowed -- in the case of \cref{lst:environments-mlb}, settings for \texttt{equation*} have been specified. Note that all poly-switches are \emph{off} by default. - \cmhlistingsfromfile[firstnumber=359,linerange={359-368},style=yaml-LST,numbers=left,]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,MLB-TCB]{\texttt{environments}}{lst:environments-mlb} + \cmhlistingsfromfile[style=modifylinebreaksEnv]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,MLB-TCB]{\texttt{environments}}{lst:environments-mlb} \subsubsection{Adding line breaks (poly-switches set to $1$ or $2$)} Let's begin with the simple example given in \cref{lst:env-mlb1-tex}; note that we have annotated key parts of the file using $\BeginStartsOnOwnLine$, @@ -351,7 +616,6 @@ latexindent.pl -m env-mlb5.tex -l env-mlb9.yaml,env-mlb10.yaml,env-mlb11.yaml,en \cmhlistingsfromfile{demonstrations/env-mlb5-modAll-remove-WS.tex}{\texttt{env-mlb5.tex} using \crefrange{lst:env-mlb4-mod9}{lst:env-mlb4-mod12} \emph{and} \cref{lst:removeTWS-before}}{lst:env-mlb5-modAll-remove-WS} \end{widepage} - \paragraph{Blank lines} Now let's consider the file in \cref{lst:mlb6}, which contains blank lines. |