summaryrefslogtreecommitdiff
path: root/support/latexindent/documentation/subsec-remove-para-line-breaks.tex
diff options
context:
space:
mode:
Diffstat (limited to 'support/latexindent/documentation/subsec-remove-para-line-breaks.tex')
-rw-r--r--support/latexindent/documentation/subsec-remove-para-line-breaks.tex217
1 files changed, 217 insertions, 0 deletions
diff --git a/support/latexindent/documentation/subsec-remove-para-line-breaks.tex b/support/latexindent/documentation/subsec-remove-para-line-breaks.tex
new file mode 100644
index 0000000000..f5531cbba4
--- /dev/null
+++ b/support/latexindent/documentation/subsec-remove-para-line-breaks.tex
@@ -0,0 +1,217 @@
+% arara: pdflatex: {shell: yes, files: [latexindent]}
+\subsection{removeParagraphLineBreaks: modifying line breaks for paragraphs}\label{subsec:removeparagraphlinebreaks} When the \texttt{-m} switch is active
+ \texttt{latexindent.pl} has the ability to remove line
+ breaks%
+ \announce{2017-05-27}{removeParagraphLineBreaks}
+ 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.
+\yamltitle{removeParagraphLineBreaks}*{fields}
+ This feature is considered complimentary to the \texttt{oneSentencePerLine} feature
+ described in \vref{sec:onesentenceperline}.
+ \index{specialBeginEnd!removeParagraphLineBreaks}
+
+ \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{cmhtcbraster}
+ \cmhlistingsfromfile[showspaces=true]{demonstrations/shortlines.tex}{\texttt{shortlines.tex}}{lst:shortlines}
+ \cmhlistingsfromfile{demonstrations/remove-para1.yaml}[MLB-TCB]{\texttt{remove-para1.yaml}}{lst:remove-para1-yaml}
+ \end{cmhtcbraster}
+
+ Upon running the command
+ \index{switches!-l demonstration}
+ \index{switches!-m demonstration}
+ \index{switches!-o demonstration}
+ \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[showspaces=true]{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,
+ \index{switches!-l demonstration}
+ \index{switches!-m demonstration}
+ \index{switches!-o demonstration}
+ \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[showspaces=true]{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{cmhtcbraster}
+ \cmhlistingsfromfile{demonstrations/shortlines-mand.tex}{\texttt{shortlines-mand.tex}}{lst:shortlines-mand}
+ \cmhlistingsfromfile{demonstrations/shortlines-opt.tex}{\texttt{shortlines-opt.tex}}{lst:shortlines-opt}
+ \end{cmhtcbraster}
+
+ Upon running the commands
+ \index{switches!-l demonstration}
+ \index{switches!-m demonstration}
+ \index{switches!-o demonstration}
+ \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
+ \index{switches!-l demonstration}
+ \index{switches!-m demonstration}
+ \index{switches!-o demonstration}
+ \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 customised 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{cmhtcbraster}
+ \cmhlistingsfromfile{demonstrations/shortlines-md.tex}{\texttt{shortlines-md.tex}}{lst:shortlines-md}
+ \cmhlistingsfromfile{demonstrations/remove-para4.yaml}[MLB-TCB]{\texttt{remove-para4.yaml}}{lst:remove-para4-yaml}
+ \end{cmhtcbraster}
+
+ Upon running the following command
+ \index{switches!-l demonstration}
+ \index{switches!-m demonstration}
+ \index{switches!-o demonstration}
+ \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}
+
+ Note%
+ \announce{2018-08-13}*{updates to all in removeParagraphLineBreaks} that the \texttt{all} field can take the same exceptions
+ detailed in \crefrange{lst:textwrap6-yaml}{lst:textwrap8-yaml}.
+
+\yamltitle{paragraphsStopAt}*{fields}
+ The paragraph line break routine considers blank lines and the
+ \lstinline|\par| command to be the end of a paragraph;
+ \announce{2017-05-27}{paragraphsStopAt} you can fine tune the behaviour of the routine
+ further by using the \texttt{paragraphsStopAt} fields, shown in
+ \cref{lst:paragraphsStopAt}.
+ \index{specialBeginEnd!paragraphsStopAt}
+ \index{verbatim!in relation to 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
+ or verbatim code block 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
+ \index{switches!-l demonstration}
+ \index{switches!-m demonstration}
+ \index{switches!-o demonstration}
+ \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}
+