summaryrefslogtreecommitdiff
path: root/support/latexindent/documentation/subsec-remove-para-line-breaks.tex
blob: f5531cbba486bb817b7d8f240c5c60975b67da4f (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
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}