texlive[48402] trunk: latexindent (15aug18)
commits+karl at tug.org
commits+karl at tug.org
Wed Aug 15 00:01:48 CEST 2018
Revision: 48402
http://tug.org/svn/texlive?view=revision&revision=48402
Author: karl
Date: 2018-08-15 00:01:47 +0200 (Wed, 15 Aug 2018)
Log Message:
-----------
latexindent (15aug18)
Modified Paths:
--------------
trunk/Build/source/texk/texlive/linked_scripts/latexindent/latexindent.pl
trunk/Master/bin/win32/latexindent.exe
trunk/Master/texmf-dist/doc/support/latexindent/README
trunk/Master/texmf-dist/doc/support/latexindent/appendices.tex
trunk/Master/texmf-dist/doc/support/latexindent/latexindent-module-installer.pl
trunk/Master/texmf-dist/doc/support/latexindent/latexindent.pdf
trunk/Master/texmf-dist/doc/support/latexindent/latexindent.tex
trunk/Master/texmf-dist/doc/support/latexindent/sec-conclusions-know-limitations.tex
trunk/Master/texmf-dist/doc/support/latexindent/sec-default-user-local.tex
trunk/Master/texmf-dist/doc/support/latexindent/sec-demonstration.tex
trunk/Master/texmf-dist/doc/support/latexindent/sec-how-to-use.tex
trunk/Master/texmf-dist/doc/support/latexindent/sec-indent-config-and-settings.tex
trunk/Master/texmf-dist/doc/support/latexindent/sec-introduction.tex
trunk/Master/texmf-dist/doc/support/latexindent/sec-the-m-switch.tex
trunk/Master/texmf-dist/doc/support/latexindent/subsec-commands-and-their-options.tex
trunk/Master/texmf-dist/doc/support/latexindent/subsec-conflicting-poly-switches.tex
trunk/Master/texmf-dist/doc/support/latexindent/subsec-noAdditionalIndent-indentRules.tex
trunk/Master/texmf-dist/doc/support/latexindent/subsec-partnering-poly-switches.tex
trunk/Master/texmf-dist/doc/support/latexindent/subsubsec-commands-with-arguments.tex
trunk/Master/texmf-dist/doc/support/latexindent/subsubsec-environments-and-their-arguments.tex
trunk/Master/texmf-dist/doc/support/latexindent/subsubsec-environments-with-items.tex
trunk/Master/texmf-dist/doc/support/latexindent/subsubsec-headings.tex
trunk/Master/texmf-dist/doc/support/latexindent/subsubsec-ifelsefi.tex
trunk/Master/texmf-dist/doc/support/latexindent/subsubsec-no-add-remaining-code-blocks.tex
trunk/Master/texmf-dist/doc/support/latexindent/subsubsec-special.tex
trunk/Master/texmf-dist/doc/support/latexindent/title.tex
trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/AlignmentAtAmpersand.pm
trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/Arguments.pm
trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/BlankLines.pm
trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/Document.pm
trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/Else.pm
trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/Environment.pm
trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/FileContents.pm
trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/GetYamlSettings.pm
trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/Heading.pm
trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/HiddenChildren.pm
trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/Indent.pm
trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/LogFile.pm
trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/MandatoryArgument.pm
trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/ModifyLineBreaks.pm
trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/OptionalArgument.pm
trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/Preamble.pm
trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/RoundBrackets.pm
trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/Special.pm
trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/TrailingComments.pm
trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/Verbatim.pm
trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/Version.pm
trunk/Master/texmf-dist/scripts/latexindent/defaultSettings.yaml
trunk/Master/texmf-dist/scripts/latexindent/latexindent.pl
Modified: trunk/Build/source/texk/texlive/linked_scripts/latexindent/latexindent.pl
===================================================================
(Binary files differ)
Modified: trunk/Master/bin/win32/latexindent.exe
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/doc/support/latexindent/README
===================================================================
--- trunk/Master/texmf-dist/doc/support/latexindent/README 2018-08-14 22:01:02 UTC (rev 48401)
+++ trunk/Master/texmf-dist/doc/support/latexindent/README 2018-08-14 22:01:47 UTC (rev 48402)
@@ -1,5 +1,5 @@
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
- latexindent.pl, version 3.4.3, 2018-06-08
+ latexindent.pl, version 3.5, 2018-08-13
PERL script to indent code within environments, and align delimited
environments in .tex files.
Modified: trunk/Master/texmf-dist/doc/support/latexindent/appendices.tex
===================================================================
--- trunk/Master/texmf-dist/doc/support/latexindent/appendices.tex 2018-08-14 22:01:02 UTC (rev 48401)
+++ trunk/Master/texmf-dist/doc/support/latexindent/appendices.tex 2018-08-14 22:01:47 UTC (rev 48402)
@@ -1,9 +1,11 @@
% arara: pdflatex: {shell: yes, files: [latexindent]}
\appendix
\section{Required Perl modules}\label{sec:requiredmodules}
- If you intend to use \texttt{latexindent.pl} and \emph{not} one of the supplied standalone executable files, then you will need a few standard Perl modules -- if you can run the
- minimum code in \cref{lst:helloworld} (\texttt{perl helloworld.pl}) then you will be able to run \texttt{latexindent.pl}, otherwise you may
- need to install the missing modules -- see \cref{sec:module-installer,sec:manual-module-instal}.
+ If you intend to use \texttt{latexindent.pl} and \emph{not} one of the
+ supplied standalone executable files, then you will need a few standard Perl modules --
+ if you can run the minimum code in \cref{lst:helloworld} (\texttt{perl helloworld.pl}) then you will be able to run
+ \texttt{latexindent.pl}, otherwise you may need to install the missing modules -- see
+ \cref{sec:module-installer,sec:manual-module-instal}.
\begin{cmhlistings}[style=tcblatex,language=Perl]{\texttt{helloworld.pl}}{lst:helloworld}
#!/usr/bin/perl
@@ -31,8 +33,8 @@
\end{cmhlistings}
\subsection{Module installer script}\label{sec:module-installer}
- \announce{2018-01-13}{perl module helper script} \texttt{latexindent.pl} ships with a helper script that will install any missing \texttt{perl} modules
- on your system; if you run
+ \announce{2018-01-13}{perl module helper script} \texttt{latexindent.pl} ships with a helper script that will
+ install any missing \texttt{perl} modules on your system; if you run
\begin{commandshell}
perl latexindent-module-installer.pl
\end{commandshell}
@@ -40,18 +42,20 @@
\begin{dosprompt}
perl latexindent-module-installer.pl
\end{dosprompt}
- then, once you have answered \texttt{Y}, the appropriate modules will be installed onto your distribution.
+ then, once you have answered \texttt{Y}, the appropriate modules will be
+ installed onto your distribution.
\subsection{Manually installed modules}\label{sec:manual-module-instal}
- Manually installing the modules given in \cref{lst:helloworld} will vary depending on your
- operating system and \texttt{Perl} distribution. For example, Ubuntu users
+ Manually installing the modules given in \cref{lst:helloworld} will vary depending on
+ your operating system and \texttt{Perl} distribution. For example, Ubuntu users
might visit the software center, or else run
\begin{commandshell}
sudo perl -MCPAN -e 'install "File::HomeDir"'
\end{commandshell}
- Linux users may be interested in exploring Perlbrew \cite{perlbrew}; possible installation and setup
- options follow for Ubuntu (other distributions will need slightly different commands).
+ Linux users may be interested in exploring Perlbrew \cite{perlbrew}; possible
+ installation and setup options follow for Ubuntu (other distributions will need slightly
+ different commands).
\begin{commandshell}
sudo apt-get install perlbrew
perlbrew install perl-5.22.1
@@ -65,29 +69,31 @@
cpanm Log::Dispatch
\end{commandshell}
- Strawberry Perl users on Windows might use
- \texttt{CPAN client}. All of the modules are readily available on CPAN \cite{cpan}.
+ Strawberry Perl users on Windows might use \texttt{CPAN client}. All of the modules are
+ readily available on CPAN \cite{cpan}.
\texttt{indent.log} will contain details of the location
- of the Perl modules on your system. \texttt{latexindent.exe} is a standalone
- executable for Windows (and therefore does not require a Perl distribution) and caches copies of the Perl modules onto your system; if you
- wish to see where they are cached, use the \texttt{trace} option, e.g
+ of the Perl modules on your system. \texttt{latexindent.exe} is a standalone executable
+ for Windows (and therefore does not require a Perl distribution) and caches copies of the
+ Perl modules onto your system; if you wish to see where they are cached, use the
+ \texttt{trace} option, e.g
\begin{dosprompt}
latexindent.exe -t myfile.tex
\end{dosprompt}
\section{Updating the path variable}\label{sec:updating-path}
- \texttt{latexindent.pl} has a few scripts (available at \cite{latexindent-home}) that can update the \texttt{path} variables.
- Thank you to \cite{jasjuang} for this feature. If you're
- on a Linux or Mac machine, then you'll want \texttt{CMakeLists.txt} from \cite{latexindent-home}.
+ \texttt{latexindent.pl} has a few scripts (available at \cite{latexindent-home}) that can
+ update the \texttt{path} variables. Thank you to \cite{jasjuang} for this
+ feature. If you're on a Linux or Mac machine, then you'll want \texttt{CMakeLists.txt}
+ from \cite{latexindent-home}.
\subsection{Add to path for Linux}
To add \texttt{latexindent.pl} to the path for Linux, follow these steps:
\begin{enumerate}
- \item download \texttt{latexindent.pl} and its associated modules, \texttt{defaultSettings.yaml},
- to your chosen directory from \cite{latexindent-home} ;
- \item within your directory, create a directory called \texttt{path-helper-files} and
- download \texttt{CMakeLists.txt} and \lstinline!cmake_uninstall.cmake.in!
- from \cite{latexindent-home}/path-helper-files to this directory;
+ \item download \texttt{latexindent.pl} and its associated modules, \texttt{defaultSettings.yaml}, to
+ your chosen directory from \cite{latexindent-home} ;
+ \item within your directory, create a directory called \texttt{path-helper-files} and download
+ \texttt{CMakeLists.txt} and \lstinline!cmake_uninstall.cmake.in! from
+ \cite{latexindent-home}/path-helper-files to this directory;
\item run
\begin{commandshell}
ls /usr/local/bin
@@ -105,7 +111,8 @@
\begin{commandshell}
ls /usr/local/bin
\end{commandshell}
- again to check that \texttt{latexindent.pl}, its modules and \texttt{defaultSettings.yaml} have been added.
+ again to check that \texttt{latexindent.pl}, its modules and \texttt{defaultSettings.yaml} have
+ been added.
\end{enumerate}
To \emph{remove} the files, run
\begin{commandshell}
@@ -114,9 +121,10 @@
\subsection{Add to path for Windows}
To add \texttt{latexindent.exe} to the path for Windows, follow these steps:
\begin{enumerate}
- \item download \texttt{latexindent.exe}, \texttt{defaultSettings.yaml}, \texttt{add-to-path.bat}
- from \cite{latexindent-home} to your chosen directory;
- \item open a command prompt and run the following command to see what is \emph{currently} in your \lstinline!%path%! variable;
+ \item download \texttt{latexindent.exe}, \texttt{defaultSettings.yaml}, \texttt{add-to-path.bat} from
+ \cite{latexindent-home} to your chosen directory;
+ \item open a command prompt and run the following command to see what is \emph{currently}
+ in your \lstinline!%path%! variable;
\begin{dosprompt}
echo %path%
\end{dosprompt}
@@ -128,12 +136,14 @@
\end{dosprompt}
to check that the appropriate directory has been added to your \lstinline!%path%!.
\end{enumerate}
- To \emph{remove} the directory from your \lstinline!%path%!, run \texttt{remove-from-path.bat} as administrator.
+ To \emph{remove} the directory from your \lstinline!%path%!, run
+ \texttt{remove-from-path.bat} as administrator.
\section{logFilePreferences}\label{app:logfile-demo}
\Vref{lst:logFilePreferences} describes the options for customising the information given
- to the log file, and we provide a few demonstrations here. Let's say that we start with the code
- given in \cref{lst:simple}, and the settings specified in \cref{lst:logfile-prefs1-yaml}.
+ to the log file, and we provide a few demonstrations here. Let's say that we start with
+ the code given in \cref{lst:simple}, and the settings specified in
+ \cref{lst:logfile-prefs1-yaml}.
\begin{minipage}{.35\linewidth}
\cmhlistingsfromfile{demonstrations/simple.tex}{\texttt{simple.tex}}{lst:simple}
@@ -147,7 +157,8 @@
\begin{commandshell}
latexindent.pl -t -l=logfile-prefs1.yaml simple.tex
\end{commandshell}
- then on inspection of \texttt{indent.log} we will find the snippet given in \cref{lst:indentlog}.
+ then on inspection of \texttt{indent.log} we will find the snippet given in
+ \cref{lst:indentlog}.
\begin{cmhlistings}[style=tcblatex,morekeywords={TRACE}]{\texttt{indent.log}}{lst:indentlog}
+++++
TRACE: environment found: myenv
@@ -164,11 +175,12 @@
... no arguments found
-----
\end{cmhlistings}
- Notice that the information given about \texttt{myenv} is `framed' using \texttt{+++++} and \lstinline!-----! respectively.
+ Notice that the information given about \texttt{myenv} is `framed' using
+ \texttt{+++++} and \lstinline!-----! respectively.
\section{Differences from Version 2.2 to 3.0}\label{app:differences}
- There are a few (small) changes to the interface when comparing Version 2.2 to Version 3.0.
- Explicitly, in previous versions you might have run, for example,
+ There are a few (small) changes to the interface when comparing Version 2.2 to Version
+ 3.0. Explicitly, in previous versions you might have run, for example,
\begin{commandshell}
latexindent.pl -o myfile.tex outputfile.tex
\end{commandshell}
@@ -181,14 +193,15 @@
latexindent.pl myfile.tex -outputfile=outputfile.tex
latexindent.pl myfile.tex -outputfile outputfile.tex
\end{commandshell}
- noting that the \emph{output} file is given \emph{next to} the \texttt{-o} switch.
+ noting that the \emph{output} file is given \emph{next to} the
+ \texttt{-o} switch.
The fields given in \cref{lst:obsoleteYaml} are \emph{obsolete} from Version 3.0
- onwards.
- \cmhlistingsfromfile{demonstrations/obsolete.yaml}[yaml-obsolete]{Obsolete YAML fields from Version 3.0}{lst:obsoleteYaml}
+ onwards. \cmhlistingsfromfile{demonstrations/obsolete.yaml}[yaml-obsolete]{Obsolete YAML fields from Version 3.0}{lst:obsoleteYaml}
- There is a slight difference when specifying indentation after headings; specifically,
- we now write \texttt{indentAfterThisHeading} instead of \texttt{indent}. See \cref{lst:indentAfterThisHeadingOld,lst:indentAfterThisHeadingNew}
+ There is a slight difference when specifying indentation after headings; specifically, we
+ now write \texttt{indentAfterThisHeading} instead of \texttt{indent}. See
+ \cref{lst:indentAfterThisHeadingOld,lst:indentAfterThisHeadingNew}
\begin{minipage}{.45\textwidth}
\cmhlistingsfromfile{demonstrations/indentAfterThisHeadingOld.yaml}[yaml-TCB]{\texttt{indentAfterThisHeading} in Version 2.2}{lst:indentAfterThisHeadingOld}
@@ -198,9 +211,10 @@
\cmhlistingsfromfile{demonstrations/indentAfterThisHeadingNew.yaml}[yaml-TCB]{\texttt{indentAfterThisHeading} in Version 3.0}{lst:indentAfterThisHeadingNew}
\end{minipage}%
- To specify \texttt{noAdditionalIndent} for display-math environments in Version 2.2, you would write YAML
- as in \cref{lst:noAdditionalIndentOld}; as of Version 3.0, you would write YAML as in \cref{lst:indentAfterThisHeadingNew1}
- or, if you're using \texttt{-m} switch, \cref{lst:indentAfterThisHeadingNew2}.
+ To specify \texttt{noAdditionalIndent} for display-math environments in Version 2.2, you would
+ write YAML as in \cref{lst:noAdditionalIndentOld}; as of Version 3.0, you would write YAML as in
+ \cref{lst:indentAfterThisHeadingNew1} or, if you're using \texttt{-m} switch,
+ \cref{lst:indentAfterThisHeadingNew2}.
\begin{minipage}{.45\textwidth}
\cmhlistingsfromfile{demonstrations/noAddtionalIndentOld.yaml}[yaml-TCB]{\texttt{noAdditionalIndent} in Version 2.2}{lst:noAdditionalIndentOld}
@@ -212,7 +226,7 @@
\cmhlistingsfromfile{demonstrations/noAddtionalIndentNew1.yaml}[yaml-TCB]{\texttt{noAdditionalIndent} for \texttt{displayMath} in Version 3.0}{lst:indentAfterThisHeadingNew2}
\end{minipage}%
- \mbox{}\hfill \begin{minipage}{.25\textwidth}
+ \mbox{}\hfill \begin{minipage}{.25\textwidth}
\hrule
\hfill\itshape End\\\mbox{}\hfill\mbox{}\rlap{\hfill\includegraphics{logo}}
Modified: trunk/Master/texmf-dist/doc/support/latexindent/latexindent-module-installer.pl
===================================================================
--- trunk/Master/texmf-dist/doc/support/latexindent/latexindent-module-installer.pl 2018-08-14 22:01:02 UTC (rev 48401)
+++ trunk/Master/texmf-dist/doc/support/latexindent/latexindent-module-installer.pl 2018-08-14 22:01:47 UTC (rev 48402)
@@ -1,6 +1,4 @@
#!/usr/bin/env perl
-# latexindent.pl, version 3.3, 2017-08-21
-#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
Modified: trunk/Master/texmf-dist/doc/support/latexindent/latexindent.pdf
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/doc/support/latexindent/latexindent.tex
===================================================================
--- trunk/Master/texmf-dist/doc/support/latexindent/latexindent.tex 2018-08-14 22:01:02 UTC (rev 48401)
+++ trunk/Master/texmf-dist/doc/support/latexindent/latexindent.tex 2018-08-14 22:01:47 UTC (rev 48402)
@@ -406,55 +406,55 @@
\lstdefinestyle{textWrapOptions}{
style=yaml-LST,
- firstnumber=397,linerange={397-398},
+ firstnumber=421,linerange={421-422},
numbers=left,
}
\lstdefinestyle{textWrapOptionsAll}{
style=yaml-LST,
- firstnumber=397,linerange={397-399},
+ firstnumber=421,linerange={421-437},
numbers=left,
}
\lstdefinestyle{removeParagraphLineBreaks}{
style=yaml-LST,
- firstnumber=422,linerange={422-434},
+ firstnumber=438,linerange={438-452},
numbers=left,
}
\lstdefinestyle{paragraphsStopAt}{
style=yaml-LST,
- firstnumber=435,linerange={435-443},
+ firstnumber=453,linerange={453-462},
numbers=left,
}
\lstdefinestyle{oneSentencePerLine}{
style=yaml-LST,
- firstnumber=400,linerange={400-421},
+ firstnumber=397,linerange={397-420},
numbers=left,
}
\lstdefinestyle{sentencesFollow}{
style=yaml-LST,
- firstnumber=403,linerange={403-411},
+ firstnumber=402,linerange={402-410},
numbers=left,
}
\lstdefinestyle{sentencesBeginWith}{
style=yaml-LST,
- firstnumber=412,linerange={412-415},
+ firstnumber=411,linerange={411-414},
numbers=left,
}
\lstdefinestyle{sentencesEndWith}{
style=yaml-LST,
- firstnumber=416,linerange={416-421},
+ firstnumber=415,linerange={415-420},
numbers=left,
}
\lstdefinestyle{modifylinebreaksEnv}{
style=yaml-LST,
- firstnumber=444,linerange={444-453},
+ firstnumber=463,linerange={463-472},
numbers=left,
}
@@ -700,85 +700,3 @@
\input{references}
\input{appendices}
\end{document}
-
-version history:
-
-1.0: first release
-https://www.ctan.org/ctan-ann/id/mailman.278.1369470527.5851.ctan-ann@dante.de
-
-1.1R
-Changed Bin to RealBin so that I hope the script can get bundled into TeXLive 2013. Some other updates, too, detailed in the documentation.
-https://www.ctan.org/ctan-ann/id/mailman.3048.1384345731.2385.ctan-ann@dante.de
-
-1.11R
-This release updates the script to use $FindBin::RealBin which should help in the TeXLive implementation.
-
-Version 2.0R
-Version 2.0R of latexindent.pl adds a number of new features, including: - indentation after \item commands - alignment of delimitered environments in commands, such as \matrix - indentation of \if...\else...\fi statements - maximum number of backups can cycle through backups - better support for .cls and .sty files - and a few other bug fixes
-https://www.ctan.org/ctan-ann/id/mailman.3090.1417864461.4370.ctan-ann@dante.de
-
-Version 2.1R
-indentconfig.yaml can now be a 'hidden' file, .indentconfig.yaml The Windows executable file, latexindent.exe, should now work much better with Windows TeXLive.
-https://www.ctan.org/ctan-ann/id/mailman.343.1429509943.4405.ctan-ann@dante.de
-
-Version 2.2
-v2.2 addresses a regexp issue, and adds a few enhancements; full details are here: https://github.com/cmhughes/latexindent.pl/pull/49
-https://www.ctan.org/ctan-ann/id/mailman.198.1477655196.4574.ctan-ann@ctan.org
-
-Version 3.0
-latexindent.pl version 3.0: this represents a complete re-build of the script; full details are given here:
-https://github.com/cmhughes/latexindent.pl/pull/56
-
-V3.0.1
-provides support for the alignment at ampersands routine for code that contains unicode characters; see
-https://github.com/cmhughes/latexindent.pl/pull/61
-
-V3.0.2
-A minor release to fix a small bug related to indentPreamble; details given here:
-https://github.com/cmhughes/latexindent.pl/pull/62
-
-Version 3.1 of latexindent.pl,
-including options for text wrapping and paragraph line break removal. Full details here:
-https://github.com/cmhughes/latexindent.pl/pull/64
-
-Version 3.2
-implements a new feature called 'multiColumnGrouping' which gives a new option for the alignment-at-ampersands routine.
-More details are given at
-https://github.com/cmhughes/latexindent.pl/pull/67
-
-Version 3.2.1
-Upgrades to the -o and -l switches
-https://github.com/cmhughes/latexindent.pl/pull/71
-
-Version 3.2.2
-Users can specify removeTrailingWhitespace as a scalar, for example, removeTrailingWhitespace: 0
-https://github.com/cmhughes/latexindent.pl/pull/72
-
-Version 3.3
-- maximum indentation: https://github.com/cmhughes/latexindent.pl/issues/50
-- blank line poly-switch: https://github.com/cmhughes/latexindent.pl/issues/57
-- ifnextchar issue: https://github.com/cmhughes/latexindent.pl/issues/73
-- the -y/yaml switch: https://github.com/cmhughes/latexindent.pl/issues/79
-- absolute paths for the -l switch: https://github.com/cmhughes/latexindent.pl/issues/82
-bug fixes:
-- an ifelsefi bug: https://github.com/cmhughes/latexindent.pl/issues/76
-- empty environment bug: https://github.com/cmhughes/latexindent.pl/issues/78
-- a command/special bug: https://github.com/cmhughes/latexindent.pl/issues/80
-https://github.com/cmhughes/latexindent.pl/releases/tag/V3.3
-
-Version 3.4
-- enhancements to alignment at ampersand routine: https://github.com/cmhughes/latexindent.pl/issues/74
-- log4Perl module: https://github.com/cmhughes/latexindent.pl/issues/75
-- one sentence per line: https://github.com/cmhughes/latexindent.pl/issues/81
-- STDIN allowed: https://github.com/cmhughes/latexindent.pl/issues/88
-- textwrap bug fix: https://github.com/cmhughes/latexindent.pl/issues/90
-- polyswitch bug fix: https://github.com/cmhughes/latexindent.pl/issues/94
-
-Version 3.4.1
-- the reading of defaultSettings.yaml needed addressing
-- https://github.com/cmhughes/latexindent.pl/releases/tag/V3.4.1
-
-Version 3.4.2
-- enhancements to specialBeginEnd: https://github.com/cmhughes/latexindent.pl/issues/100
-- enhancements to commandCodeBlocks: https://github.com/cmhughes/latexindent.pl/issues/105
-- better support for forrest syntax: https://github.com/cmhughes/latexindent.pl/issues/107
Modified: trunk/Master/texmf-dist/doc/support/latexindent/sec-conclusions-know-limitations.tex
===================================================================
--- trunk/Master/texmf-dist/doc/support/latexindent/sec-conclusions-know-limitations.tex 2018-08-14 22:01:02 UTC (rev 48401)
+++ trunk/Master/texmf-dist/doc/support/latexindent/sec-conclusions-know-limitations.tex 2018-08-14 22:01:47 UTC (rev 48402)
@@ -1,37 +1,37 @@
% arara: pdflatex: {shell: yes, files: [latexindent]}
\section{Conclusions and known limitations}\label{sec:knownlimitations}
- There are a number of known limitations of the script, and almost certainly quite a
- few that are \emph{unknown}!
+ There are a number of known limitations of the script, and almost certainly quite a few
+ that are \emph{unknown}!
- The main limitation is to do with the alignment routine discussed on \cpageref{yaml:lookforaligndelims}; for example,
- consider the file given in \cref{lst:matrix2}.
+ The main limitation is to do with the alignment routine discussed on
+ \cpageref{yaml:lookforaligndelims}; for example, consider the file given in \cref{lst:matrix2}.
\cmhlistingsfromfile{demonstrations/matrix2.tex}{\texttt{matrix2.tex}}{lst:matrix2}
- The default output is given in \cref{lst:matrix2-default}, and it is clear that the alignment routine
- has not worked as hoped, but it is \emph{expected}.
- \cmhlistingsfromfile{demonstrations/matrix2-default.tex}{\texttt{matrix2.tex} default output}{lst:matrix2-default}
+ The default output is given in \cref{lst:matrix2-default}, and it is clear that the alignment
+ routine has not worked as hoped, but it is \emph{expected}. \cmhlistingsfromfile{demonstrations/matrix2-default.tex}{\texttt{matrix2.tex} default output}{lst:matrix2-default}
- The reason for the problem is that when \texttt{latexindent.pl} stores its code blocks (see \vref{tab:code-blocks})
- it uses replacement tokens. The alignment routine is using the \emph{length of the replacement token} in its measuring -- I hope
- to be able to address this in the future.
+ The reason for the problem is that when \texttt{latexindent.pl} stores its code blocks
+ (see \vref{tab:code-blocks}) it uses replacement tokens. The alignment routine is using
+ the \emph{length of the replacement token} in its measuring -- I hope to be able to address this in the
+ future.
- There are other limitations to do with the multicolumn alignment routine (see \vref{lst:tabular2-mod2}); in particular,
- when working with codeblocks in which multicolumn commands overlap, the algorithm can fail.
+ There are other limitations to do with the multicolumn alignment routine (see
+ \vref{lst:tabular2-mod2}); in particular, when working with codeblocks in which multicolumn
+ commands overlap, the algorithm can fail.
Another limitation is to do with efficiency, particularly when the \texttt{-m}
switch is active, as this adds many checks and processes. The current implementation
- relies upon finding and storing \emph{every} code block (see the discussion on \cpageref{page:phases});
- it is hoped that, in a future version, only \emph{nested} code blocks will need
- to be stored in the `packing' phase, and that this will improve the efficiency of the script.
+ relies upon finding and storing \emph{every} code block (see the discussion on
+ \cpageref{page:phases}); it is hoped that, in a future version, only
+ \emph{nested} code blocks will need to be stored in the `packing' phase, and
+ that this will improve the efficiency of the script.
- You can run \texttt{latexindent} on \texttt{.sty}, \texttt{.cls} and any file types
- that you specify in \lstinline[breaklines=true]!fileExtensionPreference! (see \vref{lst:fileExtensionPreference});
- if you find a case in which the script struggles, please feel free
- to report it at \cite{latexindent-home}, and
- in the meantime, consider using a \texttt{noIndentBlock} (see \cpageref{lst:noIndentBlockdemo}).
+ You can run \texttt{latexindent} on \texttt{.sty}, \texttt{.cls} and
+ any file types that you specify in \lstinline[breaklines=true]!fileExtensionPreference! (see \vref{lst:fileExtensionPreference});
+ if you find a case in which the script struggles, please feel free to report it at
+ \cite{latexindent-home}, and in the meantime, consider using a \texttt{noIndentBlock} (see \cpageref{lst:noIndentBlockdemo}).
- I hope that this script is useful to some; if you find an example where the
- script does not behave as you think it should, the best way to contact me is to
- report an issue on \cite{latexindent-home}; otherwise, feel free to find me on
- the \url{http://tex.stackexchange.com/users/6621/cmhughes}.
+ I hope that this script is useful to some; if you find an example where the script does
+ not behave as you think it should, the best way to contact me is to report an issue on
+ \cite{latexindent-home}; otherwise, feel free to find me on the \url{http://tex.stackexchange.com/users/6621/cmhughes}.
Modified: trunk/Master/texmf-dist/doc/support/latexindent/sec-default-user-local.tex
===================================================================
--- trunk/Master/texmf-dist/doc/support/latexindent/sec-default-user-local.tex 2018-08-14 22:01:02 UTC (rev 48401)
+++ trunk/Master/texmf-dist/doc/support/latexindent/sec-default-user-local.tex 2018-08-14 22:01:47 UTC (rev 48402)
@@ -1,23 +1,20 @@
% arara: pdflatex: {shell: yes, files: [latexindent]}
\section{defaultSettings.yaml}\label{sec:defuseloc}
- \texttt{latexindent.pl} loads its settings from \texttt{defaultSettings.yaml}. The idea is to separate the behaviour of the script
- from the internal working -- this is very similar to the way that we separate content
- from form when writing our documents in \LaTeX.
+ \texttt{latexindent.pl} loads its settings from \texttt{defaultSettings.yaml}. The idea is to
+ separate the behaviour of the script from the internal working -- this is very similar to
+ the way that we separate content from form when writing our documents in \LaTeX.
- If you look in \texttt{defaultSettings.yaml} you'll find the switches
- that govern the behaviour of \texttt{latexindent.pl}. If you're not sure where
- \texttt{defaultSettings.yaml} resides on your computer, don't worry as \texttt{indent.log}
- will tell you where to find it.
- \texttt{defaultSettings.yaml} is commented,
- but here is a description of what each switch is designed to do. The default
- value is given in each case; whenever you see \emph{integer} in \emph{this}
- section, assume that it must be greater than or equal to \texttt{0} unless
- otherwise stated.
+ If you look in \texttt{defaultSettings.yaml} you'll find the switches that govern the behaviour
+ of \texttt{latexindent.pl}. If you're not sure where \texttt{defaultSettings.yaml} resides on
+ your computer, don't worry as \texttt{indent.log} will tell you where to find it.
+ \texttt{defaultSettings.yaml} is commented, but here is a description of what each switch is
+ designed to do. The default value is given in each case; whenever you see
+ \emph{integer} in \emph{this} section, assume that it must be
+ greater than or equal to \texttt{0} unless otherwise stated.
\yamltitle{fileExtensionPreference}*{fields}
\texttt{latexindent.pl} can be called to
- act on a file without
- specifying the file extension. For example we can call
+ act on a file without specifying the file extension. For example we can call
\begin{commandshell}
latexindent.pl myfile
\end{commandshell}
@@ -26,48 +23,49 @@
\end{wrapfigure}
in which case the script will look for \texttt{myfile} with the extensions
- specified in \texttt{fileExtensionPreference} in their numeric order. If
- no match is found, the script will exit. As with all of the fields, you should
- change and/or add to this as necessary.
+ specified in \texttt{fileExtensionPreference} in their numeric order. If no match is found, the
+ script will exit. As with all of the fields, you should change and/or add to this as
+ necessary.
- Calling \texttt{latexindent.pl myfile} with the (default) settings specified in \cref{lst:fileExtensionPreference}
- means that the script will first look for \texttt{myfile.tex}, then \texttt{myfile.sty}, \texttt{myfile.cls},
- and finally \texttt{myfile.bib} in order\footnote{Throughout this manual, listings shown with line numbers represent code
+ Calling \texttt{latexindent.pl myfile} with the (default) settings specified in
+ \cref{lst:fileExtensionPreference} means that the script will first look for
+ \texttt{myfile.tex}, then \texttt{myfile.sty}, \texttt{myfile.cls}, and
+ finally \texttt{myfile.bib} in order\footnote{Throughout this manual, listings shown with line numbers represent code
taken directly from \texttt{defaultSettings.yaml}.}.
\yamltitle{backupExtension}*{extension name}
If you call \texttt{latexindent.pl} with the \texttt{-w} switch (to overwrite
- \texttt{myfile.tex}) then it will create a backup file before doing
- any indentation; the default extension is \texttt{.bak}, so, for example, \texttt{myfile.bak0}
- would be created when calling \texttt{latexindent.pl myfile.tex} for the first time.
+ \texttt{myfile.tex}) then it will create a backup file before doing any indentation;
+ the default extension is \texttt{.bak}, so, for example,
+ \texttt{myfile.bak0} would be created when calling \texttt{latexindent.pl myfile.tex} for the
+ first time.
- By default, every time you subsequently call \texttt{latexindent.pl} with
- the \texttt{-w} to act upon \texttt{myfile.tex}, it will create successive back up files: \texttt{myfile.bak1}, \texttt{myfile.bak2},
- etc.
+ By default, every time you subsequently call \texttt{latexindent.pl} with the
+ \texttt{-w} to act upon \texttt{myfile.tex}, it will create successive
+ back up files: \texttt{myfile.bak1}, \texttt{myfile.bak2}, etc.
\yamltitle{onlyOneBackUp}*{integer}
\label{page:onlyonebackup}
If you don't want a backup for every time that you call \texttt{latexindent.pl} (so
- you don't want \texttt{myfile.bak1}, \texttt{myfile.bak2}, etc) and you simply
- want \texttt{myfile.bak} (or whatever you chose \texttt{backupExtension} to be)
- then change \texttt{onlyOneBackUp} to \texttt{1}; the default value of
- \texttt{onlyOneBackUp} is \texttt{0}.
+ you don't want \texttt{myfile.bak1}, \texttt{myfile.bak2}, etc) and you
+ simply want \texttt{myfile.bak} (or whatever you chose \texttt{backupExtension} to be) then change \texttt{onlyOneBackUp} to
+ \texttt{1}; the default value of \texttt{onlyOneBackUp} is
+ \texttt{0}.
\yamltitle{maxNumberOfBackUps}*{integer}
- Some users may only want a finite number of backup files,
- say at most $3$, in which case, they can change this switch.
- The smallest value of \texttt{maxNumberOfBackUps} is $0$ which will \emph{not}
- prevent backup files being made; in this case, the behaviour will be dictated
- entirely by \texttt{onlyOneBackUp}. The default value of \texttt{maxNumberOfBackUps}
- is \texttt{0}.
+ Some users may only want a finite number of backup files, say at most
+ $3$, in which case, they can change this switch. The smallest value of
+ \texttt{maxNumberOfBackUps} is $0$ which will \emph{not}
+ prevent backup files being made; in this case, the behaviour will be dictated entirely by
+ \texttt{onlyOneBackUp}. The default value of \texttt{maxNumberOfBackUps} is
+ \texttt{0}.
\yamltitle{cycleThroughBackUps}*{integer}
- Some users may wish to cycle through backup files, by deleting the
- oldest backup file and keeping only the most recent; for example,
- with \texttt{maxNumberOfBackUps: 4}, and \texttt{cycleThroughBackUps}
- set to \texttt{1} then the \texttt{copy} procedure given below
- would be obeyed.
+ Some users may wish to cycle through backup files, by deleting the oldest backup file and
+ keeping only the most recent; for example, with \texttt{maxNumberOfBackUps: 4}, and
+ \texttt{cycleThroughBackUps} set to \texttt{1} then the
+ \texttt{copy} procedure given below would be obeyed.
\begin{commandshell}
copy myfile.bak1 to myfile.bak0
@@ -79,35 +77,39 @@
\yamltitle{logFilePreferences}*{fields}
\texttt{latexindent.pl} writes information to \texttt{indent.log}, some
- of which can be customized by changing \texttt{logFilePreferences}; see \cref{lst:logFilePreferences}.
- If you load your own user settings (see \vref{sec:indentconfig}) then \texttt{latexindent.pl} will
- detail them in \texttt{indent.log}; you can choose not to have the details logged by switching
- \texttt{showEveryYamlRead} to \texttt{0}. Once all of your settings have
- been loaded, you can see the amalgamated settings in the log file by switching \texttt{showAmalgamatedSettings}
- to \texttt{1}, if you wish.
+ of which can be customized by changing \texttt{logFilePreferences}; see
+ \cref{lst:logFilePreferences}. If you load your own user settings (see \vref{sec:indentconfig})
+ then \texttt{latexindent.pl} will detail them in \texttt{indent.log}; you can choose
+ not to have the details logged by switching \texttt{showEveryYamlRead} to
+ \texttt{0}. Once all of your settings have been loaded, you can see the
+ amalgamated settings in the log file by switching \texttt{showAmalgamatedSettings} to
+ \texttt{1}, if you wish.
\cmhlistingsfromfile[style=logFilePreferences,]*{../defaultSettings.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{logFilePreferences}}{lst:logFilePreferences}
- When%
- \announce{2018-01-13}{showDecorationStartCodeBlockTrace feature for log file} either of the \texttt{trace} modes (see \cpageref{page:traceswitch})
- are active, you will receive detailed information in \texttt{indent.log}. You can specify character strings
- to appear before and after the notification of a found code block using, respectively, \texttt{showDecorationStartCodeBlockTrace}
- and \texttt{showDecorationFinishCodeBlockTrace}. A demonstration is given in \vref{app:logfile-demo}.
+ When%%%%
+ \announce{2018-01-13}{showDecorationStartCodeBlockTrace feature for log file} either of the
+ \texttt{trace} modes (see \cpageref{page:traceswitch}) are active, you will receive
+ detailed information in \texttt{indent.log}. You can specify character strings to
+ appear before and after the notification of a found code block using, respectively,
+ \texttt{showDecorationStartCodeBlockTrace} and \texttt{showDecorationFinishCodeBlockTrace}. A demonstration is given in
+ \vref{app:logfile-demo}.
- The log file will end with the characters
- given in \texttt{endLogFileWith}, and will report the \texttt{GitHub} address
- of \texttt{latexindent.pl} to the log file if \texttt{showGitHubInfoFooter} is set to \texttt{1}.
+ The log file will end with the characters given in \texttt{endLogFileWith}, and will
+ report the \texttt{GitHub} address of \texttt{latexindent.pl} to the log file if
+ \texttt{showGitHubInfoFooter} is set to \texttt{1}.
\texttt{latexindent.pl}%
\announce{2018-01-13}{log file pattern layout for log file} uses the \texttt{log4perl} module \cite{log4perl}
- to handle the creation of the logfile. You can specify the layout of the information given in the logfile
- using any of the \texttt{Log Layouts} detailed at \cite{log4perl}.
+ to handle the creation of the logfile. You can specify the layout of the information
+ given in the logfile using any of the \texttt{Log Layouts} detailed at
+ \cite{log4perl}.
\yamltitle{verbatimEnvironments}*{fields}
- A field that contains a list of environments
- that you would like left completely alone -- no indentation will be performed
- on environments that you have specified in this field, see \cref{lst:verbatimEnvironments}.
+ A field that contains a list of environments that you would like left completely alone --
+ no indentation will be performed on environments that you have specified in this field,
+ see \cref{lst:verbatimEnvironments}.
\begin{minipage}{.45\textwidth}
\cmhlistingsfromfile[style=verbatimEnvironments]*{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{verbatimEnvironments}}{lst:verbatimEnvironments}
@@ -117,14 +119,15 @@
\cmhlistingsfromfile[style=verbatimCommands]*{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{verbatimCommands}}{lst:verbatimCommands}
\end{minipage}%
- Note that if you put an environment in \texttt{verbatimEnvironments}
- and in other fields such as \texttt{lookForAlignDelims} or \texttt{noAdditionalIndent}
- then \texttt{latexindent.pl} will \emph{always} prioritize \texttt{verbatimEnvironments}.
+ Note that if you put an environment in \texttt{verbatimEnvironments} and in other fields such
+ as \texttt{lookForAlignDelims} or \texttt{noAdditionalIndent} then \texttt{latexindent.pl} will
+ \emph{always} prioritize \texttt{verbatimEnvironments}.
\yamltitle{verbatimCommands}*{fields}
A field that contains a list of commands that are verbatim commands, for example
- \lstinline|\lstinline|; any commands populated in this field are protected from line breaking
- routines (only relevant if the \texttt{-m} is active, see \vref{sec:modifylinebreaks}).
+ \lstinline|\lstinline|; any commands populated in this field are protected from line
+ breaking routines (only relevant if the \texttt{-m} is active, see
+ \vref{sec:modifylinebreaks}).
\yamltitle{noIndentBlock}*{fields}
@@ -131,15 +134,14 @@
\begin{wrapfigure}[8]{r}[0pt]{6cm}
\cmhlistingsfromfile[style=noIndentBlock]*{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{noIndentBlock}}{lst:noIndentBlock}
\end{wrapfigure}
- If you have a block of code that you don't want \texttt{latexindent.pl} to touch (even if it is \emph{not} a verbatim-like
- environment) then you can wrap it in an environment from \texttt{noIndentBlock};
- you can use any name you like for this, provided you populate it as demonstrate in
- \cref{lst:noIndentBlock}.
+ If you have a block of code that you don't want \texttt{latexindent.pl} to touch (even if
+ it is \emph{not} a verbatim-like environment) then you can wrap it in an
+ environment from \texttt{noIndentBlock}; you can use any name you like for this,
+ provided you populate it as demonstrate in \cref{lst:noIndentBlock}.
- Of course, you don't want to have to specify these as null environments
- in your code, so you use them with a comment symbol, \lstinline!%!, followed
- by as many spaces (possibly none) as you like; see \cref{lst:noIndentBlockdemo} for
- example.
+ Of course, you don't want to have to specify these as null environments in your code, so
+ you use them with a comment symbol, \lstinline!%!, followed by as many spaces
+ (possibly none) as you like; see \cref{lst:noIndentBlockdemo} for example.
\begin{cmhlistings}[style=demo,escapeinside={(*@}{@*)}]{\texttt{noIndentBlock} demonstration}{lst:noIndentBlockdemo}
%(*@@*) \begin{noindent}
@@ -161,32 +163,34 @@
removeTrailingWhitespace: 1
\end{yaml}
\end{wrapfigure}
- Trailing white space can be removed both \emph{before} and \emph{after} processing
- the document, as detailed in \cref{lst:removeTrailingWhitespace}; each of the fields
- can take the values \texttt{0} or \texttt{1}. See \vref{lst:removeTWS-before,lst:env-mlb5-modAll,lst:env-mlb5-modAll-remove-WS}
- for before and after results. Thanks to \cite{vosskuhle} for providing this feature.
+ Trailing white space can be removed both \emph{before} and
+ \emph{after} processing the document, as detailed in \cref{lst:removeTrailingWhitespace};
+ each of the fields can take the values \texttt{0} or
+ \texttt{1}. See \vref{lst:removeTWS-before,lst:env-mlb5-modAll,lst:env-mlb5-modAll-remove-WS} for before and after results. Thanks
+ to \cite{vosskuhle} for providing this feature.
- You can specify \texttt{removeTrailingWhitespace} simply as \texttt{0} or \texttt{1}, if you wish; in this case,
- \announce{2017-06-28}{removeTrailingWhitespace}
- \texttt{latexindent.pl} will set both \texttt{beforeProcessing} and \texttt{afterProcessing} to the value you specify;
- see \cref{lst:removeTrailingWhitespace-alt}.
+ You can specify \texttt{removeTrailingWhitespace} simply as \texttt{0} or
+ \texttt{1}, if you wish; in this case,%
+ \announce{2017-06-28}{removeTrailingWhitespace} \texttt{latexindent.pl} will set both \texttt{beforeProcessing} and
+ \texttt{afterProcessing} to the value you specify; see \cref{lst:removeTrailingWhitespace-alt}.
\yamltitle{fileContentsEnvironments}*{field}
\begin{wrapfigure}[6]{r}[0pt]{6cm}
\cmhlistingsfromfile[style=fileContentsEnvironments]*{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{fileContentsEnvironments}}{lst:fileContentsEnvironments}
\end{wrapfigure}
- Before \texttt{latexindent.pl} determines the difference between preamble (if any) and the main document,
- it first searches for any of the environments specified in \texttt{fileContentsEnvironments}, see
- \cref{lst:fileContentsEnvironments}.
- The behaviour of \texttt{latexindent.pl} on these environments is determined by their location (preamble or not), and
- the value \texttt{indentPreamble}, discussed next.
+ Before \texttt{latexindent.pl} determines the difference between preamble (if any) and
+ the main document, it first searches for any of the environments specified in
+ \texttt{fileContentsEnvironments}, see \cref{lst:fileContentsEnvironments}. The behaviour of
+ \texttt{latexindent.pl} on these environments is determined by their location (preamble
+ or not), and the value \texttt{indentPreamble}, discussed next.
\yamltitle{indentPreamble}{0|1}
- The preamble of a document can sometimes contain some trickier code
- for \texttt{latexindent.pl} to operate upon. By default, \texttt{latexindent.pl}
- won't try to operate on the preamble (as \texttt{indentPreamble} is set to \texttt{0},
- by default), but if you'd like \texttt{latexindent.pl} to try then change \texttt{indentPreamble} to \texttt{1}.
+ The preamble of a document can sometimes contain some trickier code for
+ \texttt{latexindent.pl} to operate upon. By default, \texttt{latexindent.pl} won't try to
+ operate on the preamble (as \texttt{indentPreamble} is set to \texttt{0}, by
+ default), but if you'd like \texttt{latexindent.pl} to try then change
+ \texttt{indentPreamble} to \texttt{1}.
\yamltitle{lookForPreamble}*{fields}
@@ -193,14 +197,18 @@
\begin{wrapfigure}[8]{r}[0pt]{5cm}
\cmhlistingsfromfile[style=lookForPreamble]*{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{lookForPreamble}{lst:lookForPreamble}
\end{wrapfigure}
- Not all files contain preamble; for example, \texttt{sty}, \texttt{cls} and \texttt{bib} files typically do \emph{not}. Referencing
- \cref{lst:lookForPreamble}, if you set, for example, \texttt{.tex} to \texttt{0}, then regardless of the setting of the value of \texttt{indentPreamble}, preamble
- will not be assumed when operating upon \texttt{.tex} files.
+ Not all files contain preamble; for example, \texttt{sty},
+ \texttt{cls} and \texttt{bib} files typically do
+ \emph{not}. Referencing \cref{lst:lookForPreamble}, if you set, for example,
+ \texttt{.tex} to \texttt{0}, then regardless of the setting of the
+ value of \texttt{indentPreamble}, preamble will not be assumed when operating upon
+ \texttt{.tex} files.
\yamltitle{preambleCommandsBeforeEnvironments}{0|1}
- Assuming that \texttt{latexindent.pl} is asked to operate upon the preamble of a document,
- when this switch is set to \texttt{0} then environment code blocks will be sought first,
- and then command code blocks. When this switch is set to \texttt{1}, commands
- will be sought first. The example that first motivated this switch contained the code given in \cref{lst:motivatepreambleCommandsBeforeEnvironments}.
+ Assuming that \texttt{latexindent.pl} is asked to operate upon the preamble of a
+ document, when this switch is set to \texttt{0} then environment code blocks
+ will be sought first, and then command code blocks. When this switch is set to
+ \texttt{1}, commands will be sought first. The example that first motivated
+ this switch contained the code given in \cref{lst:motivatepreambleCommandsBeforeEnvironments}.
\begin{cmhlistings}{Motivating \texttt{preambleCommandsBeforeEnvironments}}{lst:motivatepreambleCommandsBeforeEnvironments}
...
@@ -210,12 +218,12 @@
\end{cmhlistings}
\yamltitle{defaultIndent}*{horizontal space}
- This is the default indentation (\lstinline!\t! means a tab, and is the default value) used in the absence of other details
- for the command or environment we are working with; see \texttt{indentRules} in \vref{sec:noadd-indent-rules}
- for more details.
+ This is the default indentation (\lstinline!\t! means a tab, and is the default
+ value) used in the absence of other details for the command or environment we are working
+ with; see \texttt{indentRules} in \vref{sec:noadd-indent-rules} for more details.
- If you're interested in experimenting with \texttt{latexindent.pl} then you
- can \emph{remove} all indentation by setting \texttt{defaultIndent: ""}.
+ If you're interested in experimenting with \texttt{latexindent.pl} then you can
+ \emph{remove} all indentation by setting \texttt{defaultIndent: ""}.
\yamltitle{lookForAlignDelims}*{fields}\label{yaml:lookforaligndelims}
\begin{wrapfigure}[12]{r}[0pt]{5cm}
@@ -229,19 +237,23 @@
...
\end{yaml}
\end{wrapfigure}
- This contains a list of environments and/or commands that
- are operated upon in a special way by \texttt{latexindent.pl} (see \cref{lst:aligndelims:basic}).
- In fact, the fields in \texttt{lookForAlignDelims} can actually
- take two different forms: the \emph{basic} version is shown in \cref{lst:aligndelims:basic}
- and the \emph{advanced} version in \cref{lst:aligndelims:advanced}; we will discuss each in turn.
+ This contains a list of environments and/or commands that are operated upon in a special
+ way by \texttt{latexindent.pl} (see \cref{lst:aligndelims:basic}). In fact, the fields in \texttt{lookForAlignDelims} can
+ actually take two different forms: the \emph{basic} version is shown in
+ \cref{lst:aligndelims:basic} and the \emph{advanced} version in
+ \cref{lst:aligndelims:advanced}; we will discuss each in turn.
- The environments specified in this field will be operated on in a special way by \texttt{latexindent.pl}. In particular, it will try and align each column by its alignment
- tabs. It does have some limitations (discussed further in \cref{sec:knownlimitations}),
- but in many cases it will produce results such as those in \cref{lst:tabularbefore:basic,lst:tabularafter:basic}.
+ The environments specified in this field will be operated on in a special way by
+ \texttt{latexindent.pl}. In particular, it will try and align each column by its
+ alignment tabs. It does have some limitations (discussed further in
+ \cref{sec:knownlimitations}), but in many cases it will produce results such as those in
+ \cref{lst:tabularbefore:basic,lst:tabularafter:basic}.
If you find that \texttt{latexindent.pl} does not perform satisfactorily on such
- environments then you can set the relevant key to \texttt{0}, for example \texttt{tabular: 0}; alternatively, if you just want to ignore \emph{specific}
- instances of the environment, you could wrap them in something from \texttt{noIndentBlock} (see \vref{lst:noIndentBlock}).
+ environments then you can set the relevant key to \texttt{0}, for example
+ \texttt{tabular: 0}; alternatively, if you just want to ignore
+ \emph{specific} instances of the environment, you could wrap them in something
+ from \texttt{noIndentBlock} (see \vref{lst:noIndentBlock}).
\begin{minipage}{.45\textwidth}
\cmhlistingsfromfile{demonstrations/tabular1.tex}{\texttt{tabular1.tex}}{lst:tabularbefore:basic}
@@ -251,36 +263,46 @@
\cmhlistingsfromfile{demonstrations/tabular1-default.tex}{\texttt{tabular1.tex} default output}{lst:tabularafter:basic}
\end{minipage}%
- If, for example, you wish to remove the alignment of the \lstinline!\\! within a delimiter-aligned block, then the
- advanced form of \texttt{lookForAlignDelims} shown in \cref{lst:aligndelims:advanced} is for you.
+ If, for example, you wish to remove the alignment of the \lstinline!\\! within a
+ delimiter-aligned block, then the advanced form of \texttt{lookForAlignDelims} shown in
+ \cref{lst:aligndelims:advanced} is for you.
\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/tabular.yaml}[yaml-TCB]{\texttt{tabular.yaml}}{lst:aligndelims:advanced}
- Note that you can use a mixture of the basic and advanced form: in \cref{lst:aligndelims:advanced} \texttt{tabular} and \texttt{tabularx}
- are advanced and \texttt{longtable} is basic. When using the advanced form, each field should receive at least 1 sub-field, and \emph{can}
- (but does not have to) receive any of the following fields:
+ Note that you can use a mixture of the basic and advanced form: in
+ \cref{lst:aligndelims:advanced} \texttt{tabular} and \texttt{tabularx} are advanced
+ and \texttt{longtable} is basic. When using the advanced form, each field should
+ receive at least 1 sub-field, and \emph{can}
+ (but does not have to) receive any of the following
+ fields:
\begin{itemize}
- \item \texttt{delims}: binary switch (0 or 1) equivalent to simply specifying, for example, \texttt{tabular: 1} in
- the basic version shown in \cref{lst:aligndelims:basic}. If \texttt{delims} is set to \texttt{0} then the align at ampersand routine
- will not be called for this code block (default: 1);
- \item \texttt{alignDoubleBackSlash}: binary switch (0 or 1) to determine if \lstinline!\\! should be aligned (default: 1);
+ \item \texttt{delims}: binary switch (0 or 1) equivalent to simply specifying, for
+ example, \texttt{tabular: 1} in the basic version shown in \cref{lst:aligndelims:basic}. If
+ \texttt{delims} is set to \texttt{0} then the align at ampersand
+ routine will not be called for this code block (default: 1);
+ \item \texttt{alignDoubleBackSlash}: binary switch (0 or 1) to determine if \lstinline!\\!
+ should be aligned (default: 1);
\item \texttt{spacesBeforeDoubleBackSlash}: optionally,%
- \announce{2018-01-13}*{update to spacesBeforeDoubleBackSlash in ampersand alignment} specifies the number (integer $\geq$ 0) of spaces to be inserted
- before \lstinline!\\! (default: 1). \footnote{Previously this only activated if \texttt{alignDoubleBackSlash} was set to \texttt{0}.}
- \item \announce{2017-06-19}{multiColumnGrouping} \texttt{multiColumnGrouping}: binary switch (0 or 1) that details if \texttt{latexindent.pl} should group columns
+ \announce{2018-01-13}*{update to spacesBeforeDoubleBackSlash in ampersand alignment} specifies the number (integer $\geq$ 0) of spaces
+ to be inserted before \lstinline!\\! (default: 1). \footnote{Previously this only activated if \texttt{alignDoubleBackSlash} was set to \texttt{0}.}
+ \item \announce{2017-06-19}{multiColumnGrouping} \texttt{multiColumnGrouping}: binary switch (0 or 1) that details if
+ \texttt{latexindent.pl} should group columns
above and below a \lstinline!\multicolumn! command (default: 0);
- \item \announce{2017-06-19}{alignRowsWithoutMaxDelims} \texttt{alignRowsWithoutMaxDelims}: binary switch (0 or 1) that details if rows that do not contain the
- maximum number of delimeters should be formatted so as to have the ampersands aligned (default: 1);
- \item \announce{2018-01-13}{spacesBeforeAmpersand in ampersand alignment}\texttt{spacesBeforeAmpersand}: optionally specifies the number (integer $\geq$ 0) of
+ \item \announce{2017-06-19}{alignRowsWithoutMaxDelims} \texttt{alignRowsWithoutMaxDelims}: binary switch (0 or 1) that details if
+ rows that do not contain the maximum number of delimeters should be formatted so as to
+ have the ampersands aligned (default: 1);
+ \item \announce{2018-01-13}{spacesBeforeAmpersand in ampersand alignment}\texttt{spacesBeforeAmpersand}: optionally specifies the number (integer
+ $\geq$ 0) of
spaces to be placed \emph{before} ampersands (default: 1);
- \item \announce{2018-01-13}{spacesAfterAmpersand in ampersand alignment}\texttt{spacesAfterAmpersand}: optionally specifies the number (integer $\geq$ 0) of
+ \item \announce{2018-01-13}{spacesAfterAmpersand in ampersand alignment}\texttt{spacesAfterAmpersand}: optionally specifies the number (integer
+ $\geq$ 0) of
spaces to be placed \emph{After} ampersands (default: 1);
- \item \announce{2018-01-13}{justification of cells in ampersand alignment}\texttt{justification}: optionally specifies the justification of each cell as either \emph{left}
- or \emph{right} (default: left).
+ \item \announce{2018-01-13}{justification of cells in ampersand alignment}\texttt{justification}: optionally specifies the justification of
+ each cell as either \emph{left} or \emph{right} (default: left).
\end{itemize}
- We will explore each of these features using the file \texttt{tabular2.tex} in \cref{lst:tabular2} (which contains a \lstinline!\multicolumn! command),
- and the YAML files in \crefrange{lst:tabular2YAML}{lst:tabular8YAML}.
+ We will explore each of these features using the file \texttt{tabular2.tex} in
+ \cref{lst:tabular2} (which contains a \lstinline!\multicolumn! command), and the YAML files in \crefrange{lst:tabular2YAML}{lst:tabular8YAML}.
\cmhlistingsfromfile{demonstrations/tabular2.tex}{\texttt{tabular2.tex}}{lst:tabular2}
\begin{minipage}{.45\textwidth}
@@ -337,37 +359,47 @@
Notice in particular:
\begin{itemize}
- \item in both \cref{lst:tabular2-default,lst:tabular2-mod2} all rows have been aligned at the ampersand, even
- those that do not contain the maximum number of ampersands (3 ampersands, in this case);
+ \item in both \cref{lst:tabular2-default,lst:tabular2-mod2} all rows have been aligned at the ampersand, even those
+ that do not contain the maximum number of ampersands (3 ampersands, in this case);
\item in \cref{lst:tabular2-default} the columns have been aligned at the ampersand;
- \item in \cref{lst:tabular2-mod2} the \lstinline!\multicolumn! command has grouped the $2$ columns beneath \emph{and} above it,
- because \texttt{multiColumnGrouping} is set to $1$ in \cref{lst:tabular2YAML};
- \item in \cref{lst:tabular2-mod3} rows~3 and~6 have \emph{not} been aligned at the ampersand, because
- \texttt{alignRowsWithoutMaxDelims} has been to set to $0$ in \cref{lst:tabular3YAML}; however,
- the \lstinline!\\! \emph{have} still been aligned;
- \item in \cref{lst:tabular2-mod4} the columns beneath and above the \lstinline!\multicolumn! commands have been
- grouped (because \texttt{multiColumnGrouping} is set to $1$), and there are at least $4$ spaces \emph{before}
- each aligned ampersand because \texttt{spacesBeforeAmpersand} is set to $4$;
- \item in \cref{lst:tabular2-mod5} the columns beneath and above the \lstinline!\multicolumn! commands have been
- grouped (because \texttt{multiColumnGrouping} is set to $1$), and there are at least $4$ spaces \emph{after}
- each aligned ampersand because \texttt{spacesAfterAmpersand} is set to $4$;
- \item in \cref{lst:tabular2-mod6} the \lstinline!\\! have \emph{not} been aligned, because \texttt{alignDoubleBackSlash}
- is set to \texttt{0}, otherwise the output is the same as \cref{lst:tabular2-mod2};
- \item in \cref{lst:tabular2-mod7} the \lstinline!\\! \emph{have} been aligned, and because \texttt{spacesBeforeDoubleBackSlash}
- is set to \texttt{0}, there are no spaces ahead of them; the output is otherwise the same as \cref{lst:tabular2-mod2}.
- \item in \cref{lst:tabular2-mod8} the cells have been \emph{right}-justified; note that cells above and below the \lstinline!\multicol!
- statements have still been group correctly, because of the settings in \cref{lst:tabular2YAML}.
+ \item in \cref{lst:tabular2-mod2} the \lstinline!\multicolumn! command has grouped the
+ $2$ columns beneath \emph{and} above it, because
+ \texttt{multiColumnGrouping} is set to $1$ in \cref{lst:tabular2YAML};
+ \item in \cref{lst:tabular2-mod3} rows~3 and~6 have \emph{not} been aligned at the
+ ampersand, because \texttt{alignRowsWithoutMaxDelims} has been to set to $0$ in
+ \cref{lst:tabular3YAML}; however, the \lstinline!\\! \emph{have} still
+ been aligned;
+ \item in \cref{lst:tabular2-mod4} the columns beneath and above the \lstinline!\multicolumn!
+ commands have been grouped (because \texttt{multiColumnGrouping} is set to
+ $1$), and there are at least $4$ spaces
+ \emph{before} each aligned ampersand because \texttt{spacesBeforeAmpersand} is set to
+ $4$;
+ \item in \cref{lst:tabular2-mod5} the columns beneath and above the \lstinline!\multicolumn!
+ commands have been grouped (because \texttt{multiColumnGrouping} is set to
+ $1$), and there are at least $4$ spaces
+ \emph{after} each aligned ampersand because \texttt{spacesAfterAmpersand} is set to
+ $4$;
+ \item in \cref{lst:tabular2-mod6} the \lstinline!\\! have \emph{not} been
+ aligned, because \texttt{alignDoubleBackSlash} is set to \texttt{0}, otherwise the
+ output is the same as \cref{lst:tabular2-mod2};
+ \item in \cref{lst:tabular2-mod7} the \lstinline!\\! \emph{have} been
+ aligned, and because \texttt{spacesBeforeDoubleBackSlash} is set to \texttt{0}, there are
+ no spaces ahead of them; the output is otherwise the same as \cref{lst:tabular2-mod2}.
+ \item in \cref{lst:tabular2-mod8} the cells have been \emph{right}-justified; note
+ that cells above and below the \lstinline!\multicol! statements have still been group
+ correctly, because of the settings in \cref{lst:tabular2YAML}.
\end{itemize}
- As of Version 3.0, the alignment routine works on mandatory and optional arguments within commands, and also within `special' code blocks
- (see \texttt{specialBeginEnd} on \cpageref{yaml:specialBeginEnd}); for example, assuming that you have a command called \lstinline!\matrix!
- and that it is populated within \texttt{lookForAlignDelims} (which it is, by default), and that you
- run the command
+ As of Version 3.0, the alignment routine works on mandatory and optional arguments within
+ commands, and also within `special' code blocks (see \texttt{specialBeginEnd} on
+ \cpageref{yaml:specialBeginEnd}); for example, assuming that you have a command called
+ \lstinline!\matrix! and that it is populated within \texttt{lookForAlignDelims} (which it is, by default), and that
+ you run the command
\begin{commandshell}
latexindent.pl matrix1.tex
\end{commandshell}
- then the before-and-after results
- shown in \cref{lst:matrixbefore,lst:matrixafter} are achievable by default.
+ then the before-and-after results shown in \cref{lst:matrixbefore,lst:matrixafter} are achievable by
+ default.
\begin{minipage}{.45\textwidth}
\cmhlistingsfromfile{demonstrations/matrix1.tex}{\texttt{matrix1.tex}}{lst:matrixbefore}
@@ -377,10 +409,12 @@
\cmhlistingsfromfile{demonstrations/matrix1-default.tex}{\texttt{matrix1.tex} default output}{lst:matrixafter}
\end{minipage}%
- If you have blocks of code that you wish to align at the \& character that
- are \emph{not} wrapped in, for example, \lstinline!\begin{tabular}! \ldots \lstinline!\end{tabular}!, then you can use the mark up
- illustrated in \cref{lst:alignmentmarkup}; the default output is shown in \cref{lst:alignmentmarkup-default}. Note that the \lstinline!%*! must be next to
- each other, but that there can be any number of spaces (possibly none) between the
+ If you have blocks of code that you wish to align at the \& character that are
+ \emph{not} wrapped in, for example, \lstinline!\begin{tabular}! \ldots
+ \lstinline!\end{tabular}!, then you can use the mark up illustrated in
+ \cref{lst:alignmentmarkup}; the default output is shown in \cref{lst:alignmentmarkup-default}. Note
+ that the \lstinline!%*! must be next to each other, but that there can be any
+ number of spaces (possibly none) between the
\lstinline!*! and \lstinline!\begin{tabular}!; note also that you may use any
environment name that you have specified in \texttt{lookForAlignDelims}.
@@ -392,17 +426,19 @@
\cmhlistingsfromfile{demonstrations/align-block-default.tex}{\texttt{align-block.tex} default output}{lst:alignmentmarkup-default}
\end{minipage}%
- With reference to \vref{tab:code-blocks} and the, yet undiscussed, fields of \texttt{noAdditionalIndent} and \texttt{indentRules}
- (see \vref{sec:noadd-indent-rules}), these comment-marked blocks are considered \texttt{environments}.
+ With reference to \vref{tab:code-blocks} and the, yet undiscussed, fields of
+ \texttt{noAdditionalIndent} and \texttt{indentRules}
+ (see \vref{sec:noadd-indent-rules}), these comment-marked blocks are
+ considered \texttt{environments}.
\yamltitle{indentAfterItems}*{fields}
\begin{wrapfigure}[5]{r}[0pt]{7cm}
\cmhlistingsfromfile[style=indentAfterItems]*{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{indentAfterItems}}{lst:indentafteritems}
\end{wrapfigure}
- The environment names specified in \texttt{indentAfterItems} tell
- \texttt{latexindent.pl} to look for \lstinline!\item! commands; if these switches are set to \texttt{1}
- then indentation will be performed so as indent the code after each \texttt{item}.
- A demonstration is given in \cref{lst:itemsbefore,lst:itemsafter}
+ The environment names specified in \texttt{indentAfterItems} tell \texttt{latexindent.pl}
+ to look for \lstinline!\item! commands; if these switches are set to
+ \texttt{1} then indentation will be performed so as indent the code after
+ each \texttt{item}. A demonstration is given in \cref{lst:itemsbefore,lst:itemsafter}
\begin{minipage}{.45\textwidth}
\cmhlistingsfromfile{demonstrations/items1.tex}{\texttt{items1.tex}}{lst:itemsbefore}
@@ -416,26 +452,28 @@
\begin{wrapfigure}[5]{r}[0pt]{5cm}
\cmhlistingsfromfile[style=itemNames]*{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{itemNames}}{lst:itemNames}
\end{wrapfigure}
- If you have your own \texttt{item} commands (perhaps you
- prefer to use \texttt{myitem}, for example)
- then you can put populate them in \texttt{itemNames}.
- For example, users of the \texttt{exam} document class might like to add
- \texttt{parts} to \texttt{indentAfterItems} and \texttt{part} to \texttt{itemNames}
- to their user settings (see \vref{sec:indentconfig} for details of how to configure user settings,
- and \vref{lst:mysettings} \\ in particular \label{page:examsettings}.)
+ If you have your own \texttt{item} commands (perhaps you prefer to use
+ \texttt{myitem}, for example) then you can put populate them in
+ \texttt{itemNames}. For example, users of the \texttt{exam} document class
+ might like to add \texttt{parts} to \texttt{indentAfterItems} and
+ \texttt{part} to \texttt{itemNames} to their user settings (see
+ \vref{sec:indentconfig} for details of how to configure user settings, and
+ \vref{lst:mysettings} \\ in particular \label{page:examsettings}.)
\yamltitle{specialBeginEnd}*{fields}\label{yaml:specialBeginEnd}
- The fields specified%
- \announce{2017-08-21}*{specialBeginEnd} in \texttt{specialBeginEnd} are, in their default state, focused on math mode begin and end statements, but
- there is no requirement for this to be the case; \cref{lst:specialBeginEnd} shows the
- default settings of \texttt{specialBeginEnd}.
+ The fields specified%%%%
+ \announce{2017-08-21}*{specialBeginEnd} in
+ \texttt{specialBeginEnd} are, in their default state, focused on math mode begin and end
+ statements, but there is no requirement for this to be the case; \cref{lst:specialBeginEnd}
+ shows the default settings of \texttt{specialBeginEnd}.
\cmhlistingsfromfile[style=specialBeginEnd]*{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{specialBeginEnd}}{lst:specialBeginEnd}
- The field \texttt{displayMath} represents \lstinline!\[...\]!, \texttt{inlineMath} represents
- \lstinline!$...$! and \texttt{displayMathTex} represents \lstinline!$$...$$!. You can, of course,
- rename these in your own YAML files (see \vref{sec:localsettings}); indeed, you
- might like to set up your own special begin and end statements.
+ The field \texttt{displayMath} represents \lstinline!\[...\]!,
+ \texttt{inlineMath} represents
+ \lstinline!$...$! and \texttt{displayMathTex} represents \lstinline!$$...$$!.
+ You can, of course, rename these in your own YAML files (see \vref{sec:localsettings});
+ indeed, you might like to set up your own special begin and end statements.
A demonstration of the before-and-after results are shown in \cref{lst:specialbefore,lst:specialafter}.
@@ -447,14 +485,16 @@
\cmhlistingsfromfile{demonstrations/special1-default.tex}{\texttt{special1.tex} default output}{lst:specialafter}
\end{minipage}
- For each field, \texttt{lookForThis} is set to \texttt{1} by default, which means that \texttt{latexindent.pl}
- will look for this pattern; you can tell \texttt{latexindent.pl} not to look for the pattern, by setting
- \texttt{lookForThis} to \texttt{0}.
+ For each field, \texttt{lookForThis} is set to \texttt{1} by default,
+ which means that \texttt{latexindent.pl} will look for this pattern; you can tell
+ \texttt{latexindent.pl} not to look for the pattern, by setting \texttt{lookForThis}
+ to \texttt{0}.
- There are%
- \announce{2017-08-21}{specialBeforeCommand} examples in which it is advantageous to search for \texttt{specialBeginEnd} fields \emph{before}
- searching for commands, and the \texttt{specialBeforeCommand} switch controls this behaviour. For example, consider
- the file shown in \cref{lst:specialLRbefore}.
+ There are%%%%
+ \announce{2017-08-21}{specialBeforeCommand} examples in which it
+ is advantageous to search for \texttt{specialBeginEnd} fields \emph{before}
+ searching for commands, and the \texttt{specialBeforeCommand} switch controls this behaviour.
+ For example, consider the file shown in \cref{lst:specialLRbefore}.
\cmhlistingsfromfile{demonstrations/specialLR.tex}{\texttt{specialLR.tex}}{lst:specialLRbefore}
@@ -487,16 +527,19 @@
Notice that in:
\begin{itemize}
- \item \cref{lst:specialLR-comm-first-tex} the \lstinline!\left! has been treated as a \emph{command}, with one optional argument;
- \item \cref{lst:specialLR-special-first-tex} the \texttt{specialBeginEnd} pattern in \cref{lst:specialsLeftRight-yaml} has been obeyed
- because \cref{lst:specialBeforeCommand-yaml} specifies that the \texttt{specialBeginEnd} should be sought \emph{before} commands.
+ \item \cref{lst:specialLR-comm-first-tex} the \lstinline!\left! has been treated as a
+ \emph{command}, with one optional argument;
+ \item \cref{lst:specialLR-special-first-tex} the \texttt{specialBeginEnd} pattern in \cref{lst:specialsLeftRight-yaml}
+ has been obeyed because \cref{lst:specialBeforeCommand-yaml} specifies that the
+ \texttt{specialBeginEnd} should be sought \emph{before} commands.
\end{itemize}
- You can,optionally, specify%
- \announce*{2018-04-27}{update to specialBeginEnd} the \texttt{middle} field for anything that you
- specify in \texttt{specialBeginEnd}. For example, let's consider the \texttt{.tex} file in \cref{lst:special2}.
+ You can,optionally, specify%%%%
+ \announce{2018-04-27}{update to specialBeginEnd} the
+ \texttt{middle} field for anything that you specify in \texttt{specialBeginEnd}.
+ For example, let's consider the \texttt{.tex} file in \cref{lst:special2}.
- \cmhlistingsfromfile*{demonstrations/special2.tex}{\texttt{special2.tex}}{lst:special2}
+ \cmhlistingsfromfile{demonstrations/special2.tex}{\texttt{special2.tex}}{lst:special2}
Upon saving the YAML settings in \cref{lst:middle-yaml,lst:middle1-yaml} and running the commands
\begin{commandshell}
@@ -506,52 +549,80 @@
then we obtain the output given in \cref{lst:special2-mod1,lst:special2-mod2}.
\begin{minipage}{.4\linewidth}
- \cmhlistingsfromfile*{demonstrations/middle.yaml}[yaml-TCB]{\texttt{middle.yaml}}{lst:middle-yaml}
+ \cmhlistingsfromfile{demonstrations/middle.yaml}[yaml-TCB]{\texttt{middle.yaml}}{lst:middle-yaml}
\end{minipage}
\hfill
\begin{minipage}{.5\linewidth}
- \cmhlistingsfromfile*{demonstrations/special2-mod1.tex}{\texttt{special2.tex} using \cref{lst:middle-yaml}}{lst:special2-mod1}
+ \cmhlistingsfromfile{demonstrations/special2-mod1.tex}{\texttt{special2.tex} using \cref{lst:middle-yaml}}{lst:special2-mod1}
\end{minipage}
\begin{minipage}{.4\linewidth}
- \cmhlistingsfromfile*{demonstrations/middle1.yaml}[yaml-TCB]{\texttt{middle1.yaml}}{lst:middle1-yaml}
+ \cmhlistingsfromfile{demonstrations/middle1.yaml}[yaml-TCB]{\texttt{middle1.yaml}}{lst:middle1-yaml}
\end{minipage}
\hfill
\begin{minipage}{.5\linewidth}
- \cmhlistingsfromfile*{demonstrations/special2-mod2.tex}{\texttt{special2.tex} using \cref{lst:middle1-yaml}}{lst:special2-mod2}
+ \cmhlistingsfromfile{demonstrations/special2-mod2.tex}{\texttt{special2.tex} using \cref{lst:middle1-yaml}}{lst:special2-mod2}
\end{minipage}
We note that:
\begin{itemize}
- \item in \cref{lst:special2-mod1} the bodies of each of the \texttt{Elsif} statements have been indented appropriately;
- \item the \texttt{Else} statement has \emph{not} been indented appropriately in \cref{lst:special2-mod1} -- read on!
- \item we have specified multiple settings for the \texttt{middle} field using the syntax demonstrated in
- \cref{lst:middle1-yaml} so that the body of the \texttt{Else} statement has been indented appropriately in \cref{lst:special2-mod2}.
+ \item in \cref{lst:special2-mod1} the bodies of each of the \texttt{Elsif} statements
+ have been indented appropriately;
+ \item the \texttt{Else} statement has \emph{not} been indented
+ appropriately in \cref{lst:special2-mod1} -- read on!
+ \item we have specified multiple settings for the \texttt{middle} field using the
+ syntax demonstrated in \cref{lst:middle1-yaml} so that the body of the
+ \texttt{Else} statement has been indented appropriately in
+ \cref{lst:special2-mod2}.
\end{itemize}
+ You may%%
+ \announce*{2018-08-13}{specialBeginEnd verbatim} specify fields in
+ \texttt{specialBeginEnd} to be treated as verbatim code blocks by changing
+ \texttt{lookForThis} to be \texttt{verbatim}.
+
+ For example, beginning with the code in \cref{lst:special3-mod1} and the YAML in
+ \cref{lst:special-verb1-yaml}, and running
+ \begin{commandshell}
+latexindent.pl special3.tex -l=special-verb1
+ \end{commandshell}
+ then the output in \cref{lst:special3-mod1} is unchanged.
+
+ \begin{minipage}{.4\linewidth}
+ \cmhlistingsfromfile*{demonstrations/special-verb1.yaml}[yaml-TCB]{\texttt{special-verb1.yaml}}{lst:special-verb1-yaml}
+ \end{minipage}
+ \hfill
+ \begin{minipage}{.5\linewidth}
+ \cmhlistingsfromfile*{demonstrations/special3-mod1.tex}{\texttt{special3.tex} and output using \cref{lst:special-verb1-yaml}}{lst:special3-mod1}
+ \end{minipage}
+
\yamltitle{indentAfterHeadings}*{fields}
\begin{wrapfigure}[17]{r}[0pt]{8cm}
\cmhlistingsfromfile[style=indentAfterHeadings]*{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{indentAfterHeadings}}{lst:indentAfterHeadings}
\end{wrapfigure}
- This field enables the user to specify
- indentation rules that take effect after heading commands such as \lstinline!\part!, \lstinline!\chapter!,
- \lstinline!\section!, \lstinline!\subsection*!, or indeed any user-specified command written in this field.\footnote{There is a slight
+ This field enables the user to specify indentation rules that take effect after heading
+ commands such as \lstinline!\part!, \lstinline!\chapter!,
+ \lstinline!\section!, \lstinline!\subsection*!, or indeed any user-specified command
+ written in this field.\footnote{There is a slight
difference in interface for this field when comparing Version 2.2 to Version 3.0; see \vref{app:differences} for details.}
- The default settings do \emph{not} place indentation after a heading, but you
- can easily switch them on by changing \\ \texttt{indentAfterThisHeading: 0} to \\ \texttt{indentAfterThisHeading: 1}.
- The \texttt{level} field tells \texttt{latexindent.pl} the hierarchy of the heading
- structure in your document. You might, for example, like to have both \texttt{section}
- and \texttt{subsection} set with \texttt{level: 3} because you do not want the indentation to go too deep.
+ The default settings do \emph{not} place indentation after a heading, but
+ you can easily switch them on by changing \\ \texttt{indentAfterThisHeading: 0} to \\
+ \texttt{indentAfterThisHeading: 1}. The \texttt{level} field tells \texttt{latexindent.pl}
+ the hierarchy of the heading structure in your document. You might, for example, like to
+ have both \texttt{section} and \texttt{subsection} set with
+ \texttt{level: 3} because you do not want the indentation to go too deep.
- You can add any of your own custom heading commands to this field, specifying the \texttt{level}
- as appropriate. You can also specify your own indentation in \texttt{indentRules} (see \vref{sec:noadd-indent-rules});
- you will find the default \texttt{indentRules} contains \lstinline!chapter: " "! which
- tells \texttt{latexindent.pl} simply to use a space character after \texttt{\chapter} headings
- (once \texttt{indent} is set to \texttt{1} for \texttt{chapter}).
+ You can add any of your own custom heading commands to this field, specifying the
+ \texttt{level} as appropriate. You can also specify your own indentation in
+ \texttt{indentRules} (see \vref{sec:noadd-indent-rules}); you will find the default \texttt{indentRules} contains
+ \lstinline!chapter: " "! which tells \texttt{latexindent.pl} simply to use a space
+ character after \texttt{\chapter} headings (once \texttt{indent} is set to
+ \texttt{1} for \texttt{chapter}).
- For example, assuming that you have the code in \cref{lst:headings1yaml} saved into \texttt{headings1.yaml},
- and that you have the text from \cref{lst:headings1} saved into \texttt{headings1.tex}.
+ For example, assuming that you have the code in \cref{lst:headings1yaml} saved into
+ \texttt{headings1.yaml}, and that you have the text from \cref{lst:headings1} saved
+ into \texttt{headings1.tex}.
\begin{minipage}{.45\textwidth}
\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/headings1.yaml}[yaml-TCB]{\texttt{headings1.yaml}}{lst:headings1yaml}
@@ -575,23 +646,25 @@
\cmhlistingsfromfile[showtabs=true]{demonstrations/headings1-mod2.tex}{\texttt{headings1.tex} second modification}{lst:headings1-mod2}
\end{minipage}
- Now say that you modify the \texttt{YAML} from \cref{lst:headings1yaml} so that the \texttt{paragraph} \texttt{level} is \texttt{1}; after
+ Now say that you modify the \texttt{YAML} from \cref{lst:headings1yaml} so that
+ the \texttt{paragraph} \texttt{level} is \texttt{1}; after
running
\begin{commandshell}
latexindent.pl headings1.tex -l=headings1.yaml
\end{commandshell}
- you should receive the code given in \cref{lst:headings1-mod2}; notice that
- the \texttt{paragraph} and \texttt{subsection} are at the same indentation level.
+ you should receive the code given in \cref{lst:headings1-mod2}; notice that the
+ \texttt{paragraph} and \texttt{subsection} are at the same indentation level.
\yamltitle{maximumIndentation}*{horizontal space}
- You can control the maximum indentation given to your file by%
- \announce{2017-08-21}{maximumIndentation}
- specifying the \texttt{maximumIndentation} field as horizontal space (but \emph{not} including tabs).
- This feature uses the \texttt{Text::Tabs} module \cite{texttabs}, and is \emph{off}
- by default.
+ You can control the maximum indentation given to your file
+ by%%%%
+ \announce{2017-08-21}{maximumIndentation} specifying the
+ \texttt{maximumIndentation} field as horizontal space (but \emph{not} including
+ tabs). This feature uses the \texttt{Text::Tabs} module \cite{texttabs}, and
+ is \emph{off} by default.
- For example, consider the example shown in \cref{lst:mult-nested} together with the default output
- shown in \cref{lst:mult-nested-default}.
+ For example, consider the example shown in \cref{lst:mult-nested} together with the
+ default output shown in \cref{lst:mult-nested-default}.
\begin{minipage}{.45\textwidth}
\cmhlistingsfromfile{demonstrations/mult-nested.tex}{\texttt{mult-nested.tex}}{lst:mult-nested}
@@ -601,8 +674,8 @@
\cmhlistingsfromfile[showtabs=true]{demonstrations/mult-nested-default.tex}{\texttt{mult-nested.tex} default output}{lst:mult-nested-default}
\end{minipage}
- Now say that, for example, you have the \texttt{max-indentation1.yaml} from \cref{lst:max-indentation1yaml} and
- that you run the following command:
+ Now say that, for example, you have the \texttt{max-indentation1.yaml} from
+ \cref{lst:max-indentation1yaml} and that you run the following command:
\begin{commandshell}
latexindent.pl mult-nested.tex -l=max-indentation1
\end{commandshell}
@@ -616,15 +689,16 @@
\cmhlistingsfromfile[showspaces=true]{demonstrations/mult-nested-max-ind1.tex}{\texttt{mult-nested.tex} using \cref{lst:max-indentation1yaml}}{lst:mult-nested-max-ind1}
\end{minipage}
- Comparing the output in \cref{lst:mult-nested-default,lst:mult-nested-max-ind1} we notice that the (default) tabs
- of indentation have been replaced by a single space.
+ Comparing the output in \cref{lst:mult-nested-default,lst:mult-nested-max-ind1} we notice that the (default) tabs of
+ indentation have been replaced by a single space.
- In general, when using the \texttt{maximumIndentation} feature, any leading tabs will be replaced by equivalent
- spaces except, of course, those found in \texttt{verbatimEnvironments} (see \vref{lst:verbatimEnvironments}) or \texttt{noIndentBlock} (see \vref{lst:noIndentBlock}).
+ In general, when using the \texttt{maximumIndentation} feature, any leading tabs will be
+ replaced by equivalent spaces except, of course, those found in \texttt{verbatimEnvironments} (see \vref{lst:verbatimEnvironments})
+ or \texttt{noIndentBlock} (see \vref{lst:noIndentBlock}).
\subsection{The code blocks known latexindent.pl}\label{subsubsec:code-blocks}
- As of Version 3.0, \texttt{latexindent.pl} processes documents using code blocks; each
- of these are shown in \cref{tab:code-blocks}.
+ As of Version 3.0, \texttt{latexindent.pl} processes documents using code blocks; each of
+ these are shown in \cref{tab:code-blocks}.
\begin{table}[!htp]
\begin{widepage}
Modified: trunk/Master/texmf-dist/doc/support/latexindent/sec-demonstration.tex
===================================================================
--- trunk/Master/texmf-dist/doc/support/latexindent/sec-demonstration.tex 2018-08-14 22:01:02 UTC (rev 48401)
+++ trunk/Master/texmf-dist/doc/support/latexindent/sec-demonstration.tex 2018-08-14 22:01:47 UTC (rev 48402)
@@ -1,18 +1,17 @@
% arara: pdflatex: {shell: yes, files: [latexindent]}
\section{Demonstration: before and after}
- Let's give a demonstration of some before and after code -- after all, you probably
- won't want to try the script if you don't much like the results. You might also
- like to watch the video demonstration I made on youtube \cite{cmh:videodemo}
+ Let's give a demonstration of some before and after code -- after all, you probably won't
+ want to try the script if you don't much like the results. You might also like to watch
+ the video demonstration I made on youtube \cite{cmh:videodemo}
- As you look at \crefrange{lst:filecontentsbefore}{lst:pstricksafter}, remember
- that \texttt{latexindent.pl} is just following its rules, and there is nothing
- particular about these code snippets. All of the rules can be modified
- so that you can personalize your indentation scheme.
+ As you look at \crefrange{lst:filecontentsbefore}{lst:pstricksafter}, remember that \texttt{latexindent.pl} is just
+ following its rules, and there is nothing particular about these code snippets. All of
+ the rules can be modified so that you can personalize your indentation scheme.
- In each of the samples given in \crefrange{lst:filecontentsbefore}{lst:pstricksafter}
- the `before' case is a `worst case scenario' with no effort to make indentation. The `after'
- result would be the same, regardless of the leading white space at the beginning of
- each line which is stripped by \texttt{latexindent.pl} (unless a \texttt{verbatim}-like
+ In each of the samples given in \crefrange{lst:filecontentsbefore}{lst:pstricksafter} the `before' case is a `worst case
+ scenario' with no effort to make indentation. The `after' result would be the same,
+ regardless of the leading white space at the beginning of each line which is stripped by
+ \texttt{latexindent.pl} (unless a \texttt{verbatim}-like
environment or \texttt{noIndentBlock} is specified -- more on this in \cref{sec:defuseloc}).
\begin{widepage}
Modified: trunk/Master/texmf-dist/doc/support/latexindent/sec-how-to-use.tex
===================================================================
--- trunk/Master/texmf-dist/doc/support/latexindent/sec-how-to-use.tex 2018-08-14 22:01:02 UTC (rev 48401)
+++ trunk/Master/texmf-dist/doc/support/latexindent/sec-how-to-use.tex 2018-08-14 22:01:47 UTC (rev 48402)
@@ -1,37 +1,38 @@
% arara: pdflatex: {shell: yes, files: [latexindent]}
\section{How to use the script}
\texttt{latexindent.pl} ships as part of the \TeX Live distribution for
- Linux and Mac users; \texttt{latexindent.exe} ships as part of the \TeX Live
- and MiK\TeX{} distributions for Windows users. These files are also available
- from github \cite{latexindent-home} should you wish to use them without
- a \TeX{} distribution; in this case, you may like to read \vref{sec:updating-path}
- which details how the \texttt{path} variable can be updated.
+ Linux and Mac users; \texttt{latexindent.exe} ships as part of the \TeX Live and
+ MiK\TeX{} distributions for Windows users. These files are also available
+ from github \cite{latexindent-home} should you wish to use them without a
+ \TeX{} distribution; in this case, you may like to read
+ \vref{sec:updating-path} which details how the \texttt{path} variable can be
+ updated.
- In what follows, we will always refer to \texttt{latexindent.pl}, but depending on
- your operating system and preference, you might substitute \texttt{latexindent.exe} or
- simply \texttt{latexindent}.
+ In what follows, we will always refer to \texttt{latexindent.pl}, but depending on your
+ operating system and preference, you might substitute \texttt{latexindent.exe} or simply
+ \texttt{latexindent}.
- There are two ways to use \texttt{latexindent.pl}: from the command line,
- and using \texttt{arara}; we discuss these in \cref{sec:commandline} and
+ There are two ways to use \texttt{latexindent.pl}: from the command line, and using
+ \texttt{arara}; we discuss these in \cref{sec:commandline} and
\cref{sec:arara} respectively. We will discuss how to change the settings and
behaviour of the script in \vref{sec:defuseloc}.
\texttt{latexindent.pl} ships with \texttt{latexindent.exe} for Windows
- users, so that you can use the script with or without a Perl distribution.
- If you plan to use \texttt{latexindent.pl} (i.e, the original Perl script) then you will
- need a few standard Perl modules -- see \vref{sec:requiredmodules} for details;
- \announce{2018-01-13}{perl module installer helper script} in particular, note
- that a module installer helper script is shipped with \texttt{latexindent.pl}.
+ users, so that you can use the script with or without a Perl distribution. If you plan to
+ use \texttt{latexindent.pl} (i.e, the original Perl script) then you will need a few standard Perl modules -- see
+ \vref{sec:requiredmodules} for details;%
+ \announce{2018-01-13}{perl module installer helper script} in particular, note that a module installer helper script is
+ shipped with \texttt{latexindent.pl}.
\subsection{From the command line}\label{sec:commandline}
\texttt{latexindent.pl} has a number of different switches/flags/options, which
can be combined in any way that you like, either in short or long form as detailed below.
- \texttt{latexindent.pl} produces a \texttt{.log} file, \texttt{indent.log}, every time it
- is run; the name of the log file can be customized, but we will
- refer to the log file as \texttt{indent.log} throughout this document.
- There is a base of information that is written to \texttt{indent.log},
- but other additional information will be written depending
- on which of the following options are used.
+ \texttt{latexindent.pl} produces a \texttt{.log} file,
+ \texttt{indent.log}, every time it is run; the name of the log file can be customized,
+ but we will refer to the log file as \texttt{indent.log} throughout this document.
+ There is a base of information that is written to \texttt{indent.log}, but other
+ additional information will be written depending on which of the following options are
+ used.
\flagbox{-v, --version}
\announce{2017-06-25}{version}
@@ -52,8 +53,9 @@
latexindent.pl myfile.tex
\end{commandshell}
- This will operate on \texttt{myfile.tex}, but will simply output to your terminal; \texttt{myfile.tex} will not be changed
- by \texttt{latexindent.pl} in any way using this command.
+ This will operate on \texttt{myfile.tex}, but will simply output to your terminal;
+ \texttt{myfile.tex} will not be changed by \texttt{latexindent.pl} in any way
+ using this command.
\flagbox{-w, --overwrite}
\begin{commandshell}
@@ -62,14 +64,15 @@
latexindent.pl myfile.tex --overwrite
\end{commandshell}
- This \emph{will} overwrite \texttt{myfile.tex}, but it will
- make a copy of \texttt{myfile.tex} first. You can control the name of
- the extension (default is \texttt{.bak}), and how many different backups are made --
- more on this in \cref{sec:defuseloc}, and in particular see \texttt{backupExtension} and \texttt{onlyOneBackUp}.
+ This \emph{will} overwrite \texttt{myfile.tex}, but it will make a copy of
+ \texttt{myfile.tex} first. You can control the name of the extension (default is
+ \texttt{.bak}), and how many different backups are made -- more on this in
+ \cref{sec:defuseloc}, and in particular see \texttt{backupExtension} and
+ \texttt{onlyOneBackUp}.
- Note that if \texttt{latexindent.pl} can not create the backup, then it
- will exit without touching your original file; an error message will be given
- asking you to check the permissions of the backup file.
+ Note that if \texttt{latexindent.pl} can not create the backup, then it will exit without
+ touching your original file; an error message will be given asking you to check the
+ permissions of the backup file.
\flagbox{-o=output.tex,--outputfile=output.tex}
\begin{commandshell}
@@ -81,10 +84,10 @@
This will indent \texttt{myfile.tex} and output it to \texttt{output.tex},
overwriting it (\texttt{output.tex}) if it already exists\footnote{Users of version 2.* should
- note the subtle change in syntax}. Note that if \texttt{latexindent.pl} is called with both
- the \texttt{-w} and \texttt{-o} switches, then \texttt{-w} will
- be ignored and \texttt{-o} will take priority (this seems safer than the
- other way round).
+ note the subtle change in syntax}. Note
+ that if \texttt{latexindent.pl} is called with both the \texttt{-w} and
+ \texttt{-o} switches, then \texttt{-w} will be ignored and
+ \texttt{-o} will take priority (this seems safer than the other way round).
Note that using \texttt{-o} as above is equivalent to using
\begin{commandshell}
@@ -91,29 +94,32 @@
latexindent.pl myfile.tex > output.tex
\end{commandshell}
- You can call the \texttt{-o} switch with the name of the output file \emph{without} an extension; in
- \announce{2017-06-25}{upgrade to -o switch}
- this case, \texttt{latexindent.pl} will use the extension from the original file. For example,
- the following two calls to \texttt{latexindent.pl} are equivalent:
+ You can call the \texttt{-o} switch with the name of the output file
+ \emph{without} an extension; in%
+ \announce{2017-06-25}{upgrade to -o switch} this case, \texttt{latexindent.pl} will use the extension from the
+ original file. For example, the following two calls to \texttt{latexindent.pl} are
+ equivalent:
\begin{commandshell}
latexindent.pl myfile.tex -o=output
latexindent.pl myfile.tex -o=output.tex
\end{commandshell}
- You can call the \texttt{-o} switch using a \texttt{+} symbol at the beginning; this will
+ You can call the \texttt{-o} switch using a \texttt{+} symbol at
+ the beginning; this will%%%
\announce{2017-06-25}{+ sign in o switch}
- concatenate the name of the input file and the text given to the \texttt{-o} switch.
- For example, the following two calls to \texttt{latexindent.pl} are equivalent:
+ concatenate the name of the input file and the text given to the \texttt{-o}
+ switch. For example, the following two calls to \texttt{latexindent.pl} are equivalent:
\begin{commandshell}
latexindent.pl myfile.tex -o=+new
latexindent.pl myfile.tex -o=myfilenew.tex
\end{commandshell}
- You can call the \texttt{-o} switch using a \texttt{++} symbol at the end of the name
- \announce{2017-06-25}{++ in o switch}
- of your output file; this tells \texttt{latexindent.pl} to search successively for
- the name of your output file concatenated with $0, 1, \ldots$ while the name of the
- output file exists. For example,
+ You can call the \texttt{-o} switch using a \texttt{++} symbol at
+ the end of the name%%%
+ \announce{2017-06-25}{++ in o switch} of your output
+ file; this tells \texttt{latexindent.pl} to search successively for the name of your
+ output file concatenated with $0, 1, \ldots$ while the name of the output file
+ exists. For example,
\begin{commandshell}
latexindent.pl myfile.tex -o=output++
\end{commandshell}
@@ -124,10 +130,11 @@
\begin{commandshell}
latexindent.pl myfile.tex -o=++
\end{commandshell}
- tells it to output to \texttt{myfile0.tex}, but if it exists then output to \texttt{myfile1.tex}
- and so on.
+ tells it to output to \texttt{myfile0.tex}, but if it exists then output to
+ \texttt{myfile1.tex} and so on.
- The \texttt{+} and \texttt{++} feature of the \texttt{-o} switch can be combined; for example, calling
+ The \texttt{+} and \texttt{++} feature of the
+ \texttt{-o} switch can be combined; for example, calling
\begin{commandshell}
latexindent.pl myfile.tex -o=+out++
\end{commandshell}
@@ -134,14 +141,15 @@
tells \texttt{latexindent.pl} to output to \texttt{myfileout0.tex}, but if it exists, then
try \texttt{myfileout1.tex}, and so on.
- There is no need to specify a file extension when using the \texttt{++} feature, but if you wish to,
- then you should include it \emph{after} the \texttt{++} symbols, for example
+ There is no need to specify a file extension when using the \texttt{++}
+ feature, but if you wish to, then you should include it \emph{after} the
+ \texttt{++} symbols, for example
\begin{commandshell}
latexindent.pl myfile.tex -o=+out++.tex
\end{commandshell}
- See \vref{app:differences} for details of how the interface has changed
- from Version 2.2 to Version 3.0 for this flag.
+ See \vref{app:differences} for details of how the interface has changed from Version 2.2
+ to Version 3.0 for this flag.
\flagbox{-s, --silent}
\begin{commandshell}
latexindent.pl -s myfile.tex
@@ -157,12 +165,11 @@
\end{commandshell}
\label{page:traceswitch}
- Tracing mode: verbose output will be given to \texttt{indent.log}. This
- is useful if \texttt{latexindent.pl} has made a mistake and you're
- trying to find out where and why. You might also be interested in learning
- about \texttt{latexindent.pl}'s thought process -- if so, this
- switch is for you, although it should be noted that, especially for large files, this does affect
- performance of the script.
+ Tracing mode: verbose output will be given to \texttt{indent.log}. This is useful if
+ \texttt{latexindent.pl} has made a mistake and you're trying to find out where and why.
+ You might also be interested in learning about \texttt{latexindent.pl}'s thought process
+ -- if so, this switch is for you, although it should be noted that, especially for large
+ files, this does affect performance of the script.
\flagbox{-tt, --ttrace}
\begin{commandshell}
@@ -170,9 +177,11 @@
latexindent.pl myfile.tex -tt
\end{commandshell}
- \emph{More detailed} tracing mode: this option gives more details to \texttt{indent.log}
- than the standard \texttt{trace} option (note that, even more so than with \texttt{-t},
- especially for large files, performance of the script will be affected).
+ \emph{More detailed} tracing mode: this option gives more details to
+ \texttt{indent.log}
+ than the standard \texttt{trace} option (note that, even more so than with
+ \texttt{-t}, especially for large files, performance of the script will be
+ affected).
\flagbox{-l, --local[=myyaml.yaml,other.yaml,...]}
\begin{commandshell}
@@ -186,26 +195,29 @@
\label{page:localswitch}
\texttt{latexindent.pl} will always load \texttt{defaultSettings.yaml} (rhymes with camel)
- and if it is called with the \texttt{-l} switch and it finds \texttt{localSettings.yaml}
- in the same directory as \texttt{myfile.tex} then these settings will be
- added to the indentation scheme. Information will be given in \texttt{indent.log} on
- the success or failure of loading \texttt{localSettings.yaml}.
+ and if it is called with the \texttt{-l} switch and it finds
+ \texttt{localSettings.yaml} in the same directory as \texttt{myfile.tex} then these
+ settings will be added to the indentation scheme. Information will be given in
+ \texttt{indent.log} on the success or failure of loading \texttt{localSettings.yaml}.
- The \texttt{-l} flag can take an \emph{optional} parameter which details the name (or names separated by commas) of a YAML file(s)
- that resides in the same directory as \texttt{myfile.tex}; you can use this option if you would
- like to load a settings file in the current working directory that is \emph{not} called \texttt{localSettings.yaml}.
- \announce{2017-08-21}*{-l switch absolute paths} In fact, you can specify both \emph{relative} and \emph{absolute paths} for your YAML files;
- for example
+ The \texttt{-l} flag can take an \emph{optional} parameter which
+ details the name (or names separated by commas) of a YAML file(s) that resides in the
+ same directory as \texttt{myfile.tex}; you can use this option if you would like to
+ load a settings file in the current working directory that is \emph{not}
+ called \texttt{localSettings.yaml}.%%%
+ \announce{2017-08-21}*{-l switch absolute paths}
+ In fact, you can specify both \emph{relative} and \emph{absolute paths} for
+ your YAML files; for example
\begin{commandshell}
latexindent.pl -l=../../myyaml.yaml myfile.tex
latexindent.pl -l=/home/cmhughes/Desktop/myyaml.yaml myfile.tex
latexindent.pl -l=C:\Users\cmhughes\Desktop\myyaml.yaml myfile.tex
\end{commandshell}
- You will find a lot of other explicit demonstrations of how to use the \texttt{-l} switch throughout this documentation,
+ You will find a lot of other explicit demonstrations of how to use the
+ \texttt{-l} switch throughout this documentation,
You can call the \texttt{-l} switch with a `+' symbol either before or after
- \announce{2017-06-25}{+ sign with -l switch}
- another YAML file; for example:
+ \announce{2017-06-25}{+ sign with -l switch} another YAML file; for example:
\begin{commandshell}
latexindent.pl -l=+myyaml.yaml myfile.tex
latexindent.pl -l "+ myyaml.yaml" myfile.tex
@@ -225,8 +237,9 @@
\begin{commandshell}
latexindent.pl -l + myyaml.yaml myfile.tex
\end{commandshell}
- will \emph{only} load \texttt{localSettings.yaml}, and \texttt{myyaml.yaml} will be ignored. If you wish
- to use spaces between any of the YAML settings, then you must wrap the entire list of YAML files in quotes, as demonstrated above.
+ will \emph{only} load \texttt{localSettings.yaml}, and \texttt{myyaml.yaml}
+ will be ignored. If you wish to use spaces between any of the YAML settings, then you
+ must wrap the entire list of YAML files in quotes, as demonstrated above.
You may also choose to omit the \texttt{yaml} extension, such as
\announce{2017-06-25}{no extension for -l switch}
@@ -242,26 +255,30 @@
latexindent.pl myfile.tex -y='modifyLineBreaks:environments:one:EndStartsOnOwnLine:3' -m
\end{commandshell}
\label{page:yamlswitch}You%
- \announce{2017-08-21}{the -y switch} can specify YAML settings from the command line using the \texttt{-y} or \texttt{--yaml} switch;
- sample demonstrations are given above. Note, in particular, that multiple settings can be specified by separating them
- via commas. There is a further option to use a \texttt{;} to separate fields, which is demonstrated in \vref{sec:yamlswitch}.
+ \announce{2017-08-21}{the -y switch} can specify YAML settings from the command line using the
+ \texttt{-y} or \texttt{--yaml} switch;
+ sample demonstrations are given above. Note, in particular, that multiple settings can
+ be specified by separating them via commas. There is a further option to use a
+ \texttt{;} to separate fields, which is demonstrated in
+ \vref{sec:yamlswitch}.
- Any settings specified via this switch will be loaded \emph{after}
- any specified using the \texttt{-l} switch. This is discussed further in \vref{sec:loadorder}.
+ Any settings specified via this switch will be loaded \emph{after} any
+ specified using the \texttt{-l} switch. This is discussed further in
+ \vref{sec:loadorder}.
\flagbox{-d, --onlydefault}
\begin{commandshell}
latexindent.pl -d myfile.tex
\end{commandshell}
- Only \texttt{defaultSettings.yaml}: you might like to read \cref{sec:defuseloc} before
- using this switch. By default, \texttt{latexindent.pl} will always search for
- \texttt{indentconfig.yaml} or \texttt{.indentconfig.yaml} in your home directory. If you would prefer it not to do so
- then (instead of deleting or renaming \texttt{indentconfig.yaml} or \texttt{.indentconfig.yaml}) you can simply
- call the script with the \texttt{-d} switch; note that this will also tell
- the script to ignore \texttt{localSettings.yaml} even if it has been called with the
- \texttt{-l} switch; \texttt{latexindent.pl}%
- \announce{2017-08-21}*{updated -d switch} will also ignore any settings specified
- from the \texttt{-y} switch.
+ Only \texttt{defaultSettings.yaml}: you might like to read \cref{sec:defuseloc} before using
+ this switch. By default, \texttt{latexindent.pl} will always search for
+ \texttt{indentconfig.yaml} or \texttt{.indentconfig.yaml} in your home directory. If you would
+ prefer it not to do so then (instead of deleting or renaming \texttt{indentconfig.yaml} or
+ \texttt{.indentconfig.yaml}) you can simply call the script with the \texttt{-d}
+ switch; note that this will also tell the script to ignore \texttt{localSettings.yaml} even
+ if it has been called with the \texttt{-l} switch; \texttt{latexindent.pl}%
+ \announce{2017-08-21}*{updated -d switch} will also ignore any settings specified from the
+ \texttt{-y} switch.
\flagbox{-c, --cruft=<directory>}
\begin{commandshell}
@@ -268,10 +285,9 @@
latexindent.pl -c=/path/to/directory/ myfile.tex
\end{commandshell}
- If you wish to have backup files and \texttt{indent.log} written to a directory
- other than the current working directory, then you can send these `cruft' files
- to another directory.
- % this switch was made as a result of http://tex.stackexchange.com/questions/142652/output-latexindent-auxiliary-files-to-a-different-directory
+ If you wish to have backup files and \texttt{indent.log} written to a directory other
+ than the current working directory, then you can send these `cruft' files to another
+ directory. % this switch was made as a result of http://tex.stackexchange.com/questions/142652/output-latexindent-auxiliary-files-to-a-different-directory
\flagbox{-g, --logfile=<name of log file>}
\begin{commandshell}
@@ -281,8 +297,9 @@
latexindent.pl myfile.tex -g other.log
\end{commandshell}
- By default, \texttt{latexindent.pl} reports information to \texttt{indent.log}, but if you wish to change the
- name of this file, simply call the script with your chosen name after the \texttt{-g} switch as demonstrated above.
+ By default, \texttt{latexindent.pl} reports information to \texttt{indent.log}, but
+ if you wish to change the name of this file, simply call the script with your chosen name
+ after the \texttt{-g} switch as demonstrated above.
\flagbox{-sl, --screenlog}
\begin{commandshell}
@@ -289,9 +306,10 @@
latexindent.pl -sl myfile.tex
latexindent.pl -screenlog myfile.tex
\end{commandshell}
- Using this%
- \announce{2018-01-13}{screenlog switch created} option tells \texttt{latexindent.pl} to output the log file to the screen, as well
- as to your chosen log file.
+ Using this%%%%
+ \announce{2018-01-13}{screenlog switch created} option tells
+ \texttt{latexindent.pl} to output the log file to the screen, as well as to your chosen
+ log file.
\flagbox{-m, --modifylinebreaks}
\begin{commandshell}
@@ -299,8 +317,8 @@
latexindent.pl -modifylinebreaks myfile.tex
\end{commandshell}
- One of the most exciting developments in Version~3.0 is the ability to modify line breaks; for full details
- see \vref{sec:modifylinebreaks}
+ One of the most exciting developments in Version~3.0 is the ability to modify line
+ breaks; for full details see \vref{sec:modifylinebreaks}
\texttt{latexindent.pl} can also be called on a file without the file extension, for
example
@@ -307,9 +325,8 @@
\begin{commandshell}
latexindent.pl myfile
\end{commandshell}
- and in which case, you can specify
- the order in which extensions are searched for; see \vref{lst:fileExtensionPreference}
- for full details.
+ and in which case, you can specify the order in which extensions are searched for; see
+ \vref{lst:fileExtensionPreference} for full details.
\flagbox{STDIN}
\begin{commandshell}
cat myfile.tex | latexindent.pl
@@ -316,12 +333,14 @@
\end{commandshell}
\texttt{latexindent.pl} will%
\announce{2018-01-13}{STDIN allowed} allow input from STDIN, which means that you can pipe output from
- other commands directly into the script. For example assuming that you have content in \texttt{myfile.tex}, then the above
- command will output the results of operating upon \texttt{myfile.tex}
+ other commands directly into the script. For example assuming that you have content in
+ \texttt{myfile.tex}, then the above command will output the results of operating upon
+ \texttt{myfile.tex}
- Similarly, if you%
- \announce{2018-01-13}*{no options/filename updated} simply type \texttt{latexindent.pl}
- at the command line, then it will expect (STDIN) input from the command line.
+ Similarly, if you%%%%
+ \announce{2018-01-13}*{no options/filename updated} simply type
+ \texttt{latexindent.pl} at the command line, then it will expect (STDIN) input from the
+ command line.
\begin{commandshell}
latexindent.pl
\end{commandshell}
@@ -331,41 +350,10 @@
\item \texttt{CTRL+D} on Linux
\item \texttt{CTRL+Z} followed by \texttt{ENTER} on Windows
\end{itemize}
- to signify that your input has finished.
+ to signify that your input has finished. Thanks to \cite{xu-cheng} for an update
+ to this feature.
\subsection{From arara}\label{sec:arara}
- Using \texttt{latexindent.pl} from the command line is fine for some folks, but
- others may find it easier to use from \texttt{arara}; you can find the arara rule at \cite{paulo}.
-
- You can use the rule in any of the ways described in \cref{lst:arara} (or combinations thereof).
- In fact, \texttt{arara} allows yet greater flexibility -- you can use \texttt{yes/no}, \texttt{true/false}, or \texttt{on/off} to toggle the various options.
-
- \cmhlistingsfromfile{demonstrations/arara-demo.tex}{\texttt{arara} sample usage}{lst:arara}
-
- Hopefully the use of these rules is fairly self-explanatory, but for completeness
- \cref{tab:orbsandswitches} shows the relationship between \texttt{arara} directive arguments and the
- switches given in \cref{sec:commandline}.
-
- \begin{table}[!ht]
- \centering
- \caption{\texttt{arara} directive arguments and corresponding switches}
- \label{tab:orbsandswitches}
- \begin{tabular}{lc}
- \toprule
- \texttt{arara} directive argument & switch \\
- \midrule
- \texttt{overwrite} & \texttt{-w} \\
- \texttt{output} & \texttt{-o} \\
- \texttt{silent} & \texttt{-s} \\
- \texttt{trace} & \texttt{-t} \\
- \texttt{localSettings} & \texttt{-l} \\
- \texttt{onlyDefault} & \texttt{-d} \\
- \texttt{cruft} & \texttt{-c} \\
- %\texttt{modifylinebreaks} & \texttt{-m} \\
- \bottomrule
- \end{tabular}
- \end{table}
-
- The \texttt{cruft} directive does not work well when used with
- directories that contain spaces.
-
+ Using \texttt{latexindent.pl} from the command line is fine for some folks, but others
+ may find it easier to use from \texttt{arara}; you can find the arara rule for
+ \texttt{latexindent.pl} and its associated documentation at \cite{paulo}.
Modified: trunk/Master/texmf-dist/doc/support/latexindent/sec-indent-config-and-settings.tex
===================================================================
--- trunk/Master/texmf-dist/doc/support/latexindent/sec-indent-config-and-settings.tex 2018-08-14 22:01:02 UTC (rev 48401)
+++ trunk/Master/texmf-dist/doc/support/latexindent/sec-indent-config-and-settings.tex 2018-08-14 22:01:47 UTC (rev 48402)
@@ -1,28 +1,28 @@
% arara: pdflatex: {shell: yes, files: [latexindent]}
\section{indentconfig.yaml, local settings and the -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.
+ 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{indentconfig.yaml and .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.
+ 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
+ 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.
+ 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
@@ -39,20 +39,19 @@
- 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 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.
+ 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.
+ \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
@@ -64,10 +63,10 @@
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
+ 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}
@@ -81,26 +80,29 @@
\end{warning}
\subsection{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}. For example, if you use the following command
+ The \texttt{-l} switch tells \texttt{latexindent.pl} to look for
+ \texttt{localSettings.yaml} in the \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}.
+ 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,
+ 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=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,
- any user setting files specified in \texttt{indentconfig.yaml}.
+ Any settings file(s) specified using the \texttt{-l} switch will be read
+ \emph{after} \texttt{defaultSettings.yaml} and, assuming they exist, 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.
+ 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
@@ -110,43 +112,50 @@
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.
+ 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 -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:
+ 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:
+ 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,
+ 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.
+ 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}
\item \texttt{defaultSettings.yaml} is always loaded, and can not be renamed;
- \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 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.
+ \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 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}.
Modified: trunk/Master/texmf-dist/doc/support/latexindent/sec-introduction.tex
===================================================================
--- trunk/Master/texmf-dist/doc/support/latexindent/sec-introduction.tex 2018-08-14 22:01:02 UTC (rev 48401)
+++ trunk/Master/texmf-dist/doc/support/latexindent/sec-introduction.tex 2018-08-14 22:01:47 UTC (rev 48402)
@@ -1,35 +1,36 @@
% arara: pdflatex: {shell: yes, files: [latexindent]}
\section{Introduction}
\subsection{Thanks}
- I first created \texttt{latexindent.pl} to help me format chapter files
- in a big project. After I blogged about it on the
- \TeX{} stack exchange \cite{cmhblog} I received some positive feedback and
- follow-up feature requests. A big thank you to Harish Kumar \cite{harish} who
- helped to develop and test the initial versions of the script.
+ I first created \texttt{latexindent.pl} to help me format chapter files in a big project.
+ After I blogged about it on the \TeX{} stack exchange
+ \cite{cmhblog} I received some positive feedback and follow-up feature requests.
+ A big thank you to Harish Kumar \cite{harish} who helped to develop and test the
+ initial versions of the script.
- The \texttt{YAML}-based interface of \texttt{latexindent.pl} was inspired
- by the wonderful \texttt{arara} tool; any similarities are deliberate, and
- I hope that it is perceived as the compliment that it is. Thank you to Paulo Cereda and the
- team for releasing this awesome tool; I initially worried that I was going to
- have to make a GUI for \texttt{latexindent.pl}, but the release of \texttt{arara}
- has meant there is no need.
+ The \texttt{YAML}-based interface of \texttt{latexindent.pl} was inspired by the
+ wonderful \texttt{arara} tool; any similarities are deliberate, and I hope that
+ it is perceived as the compliment that it is. Thank you to Paulo Cereda and the team for
+ releasing this awesome tool; I initially worried that I was going to have to make a GUI
+ for \texttt{latexindent.pl}, but the release of \texttt{arara} has meant there is
+ no need.
- There have been several contributors to the project so far (and hopefully more in
- the future!); thank you very much to the people detailed in \vref{sec:contributors}
- for their valued contributions, and thank you to those who report bugs and request features
- at \cite{latexindent-home}.
+ There have been several contributors to the project so far (and hopefully more in the
+ future!); thank you very much to the people detailed in \vref{sec:contributors} for their
+ valued contributions, and thank you to those who report bugs and request features at
+ \cite{latexindent-home}.
\subsection{License}
\texttt{latexindent.pl} is free and open source, and it always will be; it
is released under the GNU General Public License v3.0.
- Before you start using it on any important files, bear in mind that \texttt{latexindent.pl} has the option to overwrite your \texttt{.tex} files.
- It will always make at least one backup (you can choose how many it makes, see \cpageref{page:onlyonebackup})
- but you should still be careful when using it. The script has been tested on many
- files, but there are some known limitations (see \cref{sec:knownlimitations}).
- You, the user, are responsible for ensuring that you maintain backups of your files
- before running \texttt{latexindent.pl} on them. I think it is important at this
- stage to restate an important part of the license here:
+ Before you start using it on any important files, bear in mind that
+ \texttt{latexindent.pl} has the option to overwrite your \texttt{.tex} files. It
+ will always make at least one backup (you can choose how many it makes, see
+ \cpageref{page:onlyonebackup}) but you should still be careful when using it. The script has
+ been tested on many files, but there are some known limitations (see
+ \cref{sec:knownlimitations}). You, the user, are responsible for ensuring that you maintain
+ backups of your files before running \texttt{latexindent.pl} on them. I think it is
+ important at this stage to restate an important part of the license here:
\begin{quote}\itshape
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
@@ -36,9 +37,9 @@
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
\end{quote}
- There is certainly no malicious intent in releasing this script, and I do hope
- that it works as you expect it to; if it does not, please first of all
- make sure that you have the correct settings, and then feel free to let me know at \cite{latexindent-home} with a
+ There is certainly no malicious intent in releasing this script, and I do hope that it
+ works as you expect it to; if it does not, please first of all make sure that you have
+ the correct settings, and then feel free to let me know at \cite{latexindent-home} with a
complete minimum working example as I would like to improve the code as much as possible.
\begin{warning}
Before you try the script on anything important (like your thesis), test it
@@ -50,10 +51,10 @@
throughout this document for details}.
\subsection{About this documentation}
- As you read through this documentation, you will see many listings; in this version of the documentation,
- there are a total of \totallstlistings. This may seem a lot, but I deem it necessary in
- presenting the various different options of \texttt{latexindent.pl} and the associated output that they are capable of
- producing.
+ As you read through this documentation, you will see many listings; in this version of
+ the documentation, there are a total of \totallstlistings. This may seem a lot, but I
+ deem it necessary in presenting the various different options of \texttt{latexindent.pl}
+ and the associated output that they are capable of producing.
The different listings are presented using different styles:
@@ -86,15 +87,17 @@
\end{minipage}%
% \begin{latexonly}
- You will occasionally see dates shown in the margin (for example, next to this paragraph!)
- \announce{2017-06-25}{announce} which detail the date of the version in which the feature was implemented;
- the `N' stands for `new as of the date shown' and `U' stands for `updated as of the date shown'.
- If you see \stardemo, it
- means that the feature is either new (N) or updated (U) as of the release of the current version; if you see \stardemo\,
- attached to a listing, then it means that listing is new (N) or updated (U) as of the current version. If you have
- not read this document before (and even if you have!), then you can ignore every occurrence of the \stardemo;
- they are simply there to highlight new and updated features.
- The new and updated features in this documentation (\gitRel) are on the following pages: \listOfNewFeatures
+ You will occasionally see dates shown in the margin (for example, next to this
+ paragraph!)%%%
+ \announce{2017-06-25}{announce} which detail the date
+ of the version in which the feature was implemented; the `N' stands for `new as of the
+ date shown' and `U' stands for `updated as of the date shown'. If you see \stardemo, it
+ means that the feature is either new (N) or updated (U) as of the release of the current
+ version; if you see \stardemo\, attached to a listing, then it means that listing is new
+ (N) or updated (U) as of the current version. If you have not read this document before
+ (and even if you have!), then you can ignore every occurrence of the \stardemo; they are
+ simply there to highlight new and updated features. The new and updated features in this
+ documentation (\gitRel) are on the following pages: \listOfNewFeatures
% \end{latexonly}
\subsection{Quick start}\label{sec:quickstart}
@@ -102,15 +105,16 @@
\begin{commandshell}
latexindent.pl myfile.tex
\end{commandshell}
- from the command line. If you receive an error message such as that given in \cref{lst:poss-errors},
- then you need to install the missing perl modules.
+ from the command line. If you receive an error message such as that given in
+ \cref{lst:poss-errors}, then you need to install the missing perl modules.
\begin{cmhlistings}[style=tcblatex,language=Perl]{Possible error messages}{lst:poss-errors}
Can't locate File/HomeDir.pm in @INC (@INC contains: /Library/Perl/5.12/darwin-thread-multi-2level /Library/Perl/5.12 /Network/Library/Perl/5.12/darwin-thread-multi-2level /Network/Library/Perl/5.12 /Library/Perl/Updates/5.12.4/darwin-thread-multi-2level /Library/Perl/Updates/5.12.4 /System/Library/Perl/5.12/darwin-thread-multi-2level /System/Library/Perl/5.12 /System/Library/Perl/Extras/5.12/darwin-thread-multi-2level /System/Library/Perl/Extras/5.12 .) at helloworld.pl line 10.
BEGIN failed--compilation aborted at helloworld.pl line 10.
\end{cmhlistings}
- \texttt{latexindent.pl} ships with a script to help with this process; if you run the following script, you should be prompted
- to install the appropriate modules.
+ \texttt{latexindent.pl} ships with a script to help with this process; if you run the
+ following script, you should be prompted to install the appropriate modules.
\begin{commandshell}
perl latexindent-module-installer.pl
\end{commandshell}
- You might also like to see \href{https://stackoverflow.com/questions/19590042/error-cant-locate-file-homedir-pm-in-inc}{https://stackoverflow.com/questions/19590042/error-cant-locate-file-homedir-pm-in-inc}, for example, as well as \vref{sec:requiredmodules}.
+ You might also like to see \href{https://stackoverflow.com/questions/19590042/error-cant-locate-file-homedir-pm-in-inc}{https://stackoverflow.com/questions/19590042/error-cant-locate-file-homedir-pm-in-inc}, for example, as well as
+ \vref{sec:requiredmodules}.
Modified: trunk/Master/texmf-dist/doc/support/latexindent/sec-the-m-switch.tex
===================================================================
--- trunk/Master/texmf-dist/doc/support/latexindent/sec-the-m-switch.tex 2018-08-14 22:01:02 UTC (rev 48401)
+++ trunk/Master/texmf-dist/doc/support/latexindent/sec-the-m-switch.tex 2018-08-14 22:01:47 UTC (rev 48402)
@@ -4,8 +4,8 @@
\node at (1,0){\includegraphics{logo}};
}}
\section{The -m (modifylinebreaks) switch}\label{sec:modifylinebreaks}
- All features described in this section will only be relevant if the \texttt{-m} switch
- is used.
+ All features described in this section will only be relevant if the
+ \texttt{-m} switch is used.
\startcontents[the-m-switch]
\printcontents[the-m-switch]{}{0}{}
@@ -17,15 +17,15 @@
\makebox[0pt][r]{%
\raisebox{-\totalheight}[0pt][0pt]{%
\tikz\node[opacity=1] at (0,0) {\includegraphics[width=4cm]{logo}};}}%
- 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
+ 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}.
- A snippet of the default settings of this field is shown in \cref{lst:modifylinebreaks}.
+ in this field will only be considered if the \texttt{-m} switch has been used}. A
+ snippet of the default settings of this field is shown in \cref{lst:modifylinebreaks}.
- Having read the previous paragraph, it should sound reasonable that, if you call \texttt{latexindent.pl}
- using the \texttt{-m} switch, then you give it permission to modify line breaks in your file,
- but let's be clear:
+ Having read the previous paragraph, it should sound reasonable that, if you call
+ \texttt{latexindent.pl} using the \texttt{-m} switch, then you give
+ it permission to modify line breaks in your file, but let's be clear:
\begin{warning}
If you call \texttt{latexindent.pl} with the \texttt{-m} switch, then you
@@ -35,21 +35,23 @@
\end{warning}
\yamltitle{preserveBlankLines}{0|1}
- This field is directly related to \emph{poly-switches}, discussed below.
- By default, it is set to \texttt{1}, which means that blank lines will
- be protected from removal; however, regardless of this setting, multiple
- blank lines can be condensed if \texttt{condenseMultipleBlankLinesInto} is
- greater than \texttt{0}, discussed next.
+ This field is directly related to \emph{poly-switches}, discussed below. By
+ default, it is set to \texttt{1}, which means that blank lines will be
+ protected from removal; however, regardless of this setting, multiple blank lines can be
+ condensed if \texttt{condenseMultipleBlankLinesInto} is greater than \texttt{0},
+ discussed next.
\yamltitle{condenseMultipleBlankLinesInto}*{positive integer}
- Assuming that this switch takes an integer value greater than \texttt{0}, \texttt{latexindent.pl} will condense multiple blank lines into
- the number of blank lines illustrated by this switch. As an example, \cref{lst:mlb-bl} shows a sample file
- with blank lines; upon running
+ Assuming that this switch takes an integer value greater than
+ \texttt{0}, \texttt{latexindent.pl} will condense multiple blank
+ lines into the number of blank lines illustrated by this switch. As an example,
+ \cref{lst:mlb-bl} shows a sample file with blank lines; upon running
\begin{commandshell}
latexindent.pl myfile.tex -m
\end{commandshell}
- the output is shown in \cref{lst:mlb-bl-out}; note that the multiple blank lines have been
- condensed into one blank line, and note also that we have used the \texttt{-m} switch!
+ the output is shown in \cref{lst:mlb-bl-out}; note that the multiple blank lines
+ have been condensed into one blank line, and note also that we have used the
+ \texttt{-m} switch!
\begin{minipage}{.45\textwidth}
\cmhlistingsfromfile{demonstrations/mlb1.tex}{\texttt{mlb1.tex}}{lst:mlb-bl}
@@ -59,14 +61,16 @@
\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
- \announce{2017-05-27}{textWrapOptions}
- 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.
+\subsection{textWrapOptions: modifying line breaks by text wrapping}\label{subsec:textwrapping}
+ When the \texttt{-m} switch is active \texttt{latexindent.pl} has the
+ ability to wrap text using the options%
+ \announce{2017-05-27}{textWrapOptions} 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}
@@ -76,7 +80,8 @@
\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
+ 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}
@@ -90,13 +95,14 @@
\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},
+ 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},
+ 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}
@@ -105,11 +111,13 @@
\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}
+ 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},
+ 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}
@@ -117,17 +125,17 @@
\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.
+ 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 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
+ 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}
@@ -141,31 +149,233 @@
\cmhlistingsfromfile{demonstrations/textwrap2.yaml}[MLB-TCB]{\texttt{textwrap2.yaml}}{lst:textwrap2-yaml}
\end{minipage}
- \textbf{Summary of text wrapping}
+\subsubsection{text wrapping on a per-code-block basis}
+ By default, if the value of \texttt{columns} is greater than 0 and the
+ \texttt{-m} switch is active, then%
+ \announce*{2018-08-13}*{updates to textWrapOptions} the text wrapping routine will operate before the code blocks
+ have been searched for. This behaviour is customisable; in particular, you can instead
+ instruct \texttt{latexindent.pl} to apply \texttt{textWrap} on a
+ per-code-block basis. Thanks to \cite{zoehneto} for their help in testing and
+ shaping this feature.
+
+ The full details of \texttt{textWrapOptions} are shown in \cref{lst:textWrapOptionsAll}.
+ In particular, note the field \texttt{perCodeBlockBasis: 0}.
+
+ \cmhlistingsfromfile*[style=textWrapOptionsAll]*{../defaultSettings.yaml}[MLB-TCB,width=.85\linewidth,before=\centering]{\texttt{textWrapOptions}}{lst:textWrapOptionsAll}
+
+ The code blocks detailed in \cref{lst:textWrapOptionsAll} are with direct reference to
+ those detailed in \vref{tab:code-blocks}. 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. The same notation is used
+ between this feature and the \texttt{removeParagraphLineBreaks} described in
+ \vref{lst:removeParagraphLineBreaks}; in fact, the two features can even be combined (this is
+ detailed in \vref{subsec:removeparagraphlinebreaks:and:textwrap}).
+
+ Let's explore these switches with reference to the code given in
+ \cref{lst:textwrap5}; the text outside of the environment is considered part of
+ the \texttt{masterDocument}.
+
+ \begin{widepage}
+ \cmhlistingsfromfile*{demonstrations/textwrap5.tex}{\texttt{textwrap5.tex}}{lst:textwrap5}
+ \end{widepage}
+
+ With reference to this codeblock, the settings given in \cref{lst:textwrap3-yaml,lst:textwrap4-yaml,lst:textwrap5-yaml} each
+ give the same output.
+
+ \begin{adjustwidth}{-3.5cm}{-2.5cm}
+ \begin{minipage}{.33\linewidth}
+ \cmhlistingsfromfile*{demonstrations/textwrap3.yaml}[MLB-TCB]{\texttt{textwrap3.yaml}}{lst:textwrap3-yaml}
+ \end{minipage}%
+ \begin{minipage}{.33\linewidth}
+ \cmhlistingsfromfile*{demonstrations/textwrap4.yaml}[MLB-TCB]{\texttt{textwrap4.yaml}}{lst:textwrap4-yaml}
+ \end{minipage}%
+ \begin{minipage}{.33\linewidth}
+ \cmhlistingsfromfile*{demonstrations/textwrap5.yaml}[MLB-TCB]{\texttt{textwrap5.yaml}}{lst:textwrap5-yaml}
+ \end{minipage}
+ \end{adjustwidth}
+
+ Let's explore the similarities and differences in the equivalent (with respect to
+ \cref{lst:textwrap5}) syntax specified in \cref{lst:textwrap3-yaml,lst:textwrap4-yaml,lst:textwrap5-yaml}:
+ \begin{itemize}
+ \item in each of \cref{lst:textwrap3-yaml,lst:textwrap4-yaml,lst:textwrap5-yaml} notice that \texttt{columns: 30};
+ \item in each of \cref{lst:textwrap3-yaml,lst:textwrap4-yaml,lst:textwrap5-yaml} notice that \texttt{perCodeBlockBasis: 1};
+ \item in \cref{lst:textwrap3-yaml} we have specified \texttt{all: 1} so that the
+ text wrapping will operate upon \emph{all} code blocks;
+ \item in \cref{lst:textwrap4-yaml} we have \emph{not} specified
+ \texttt{all}, and instead, have specified that text wrapping should be
+ applied to each of \texttt{environments} and \texttt{masterDocument};
+ \item in \cref{lst:textwrap5-yaml} we have specified text wrapping for
+ \texttt{masterDocument} and on a \emph{per-name} basis for
+ \texttt{environments} code blocks.
+ \end{itemize}
+
+ Upon running the following commands
+ \begin{commandshell}
+latexindent.pl -s textwrap5.tex -l=textwrap3.yaml -m
+latexindent.pl -s textwrap5.tex -l=textwrap4.yaml -m
+latexindent.pl -s textwrap5.tex -l=textwrap5.yaml -m
+ \end{commandshell}
+ we obtain the output shown in \cref{lst:textwrap5-mod3}.
+
+ \cmhlistingsfromfile*{demonstrations/textwrap5-mod3.tex}{\texttt{textwrap5-mod3.tex}}{lst:textwrap5-mod3}
+
+ We can explore the idea of per-name text wrapping given in \cref{lst:textwrap5-yaml} by
+ using \cref{lst:textwrap6}.
+
+ \begin{widepage}
+ \cmhlistingsfromfile*{demonstrations/textwrap6.tex}{\texttt{textwrap6.tex}}{lst:textwrap6}
+ \end{widepage}
+
+ In particular, upon running
+ \begin{commandshell}
+latexindent.pl -s textwrap6.tex -l=textwrap5.yaml -m
+ \end{commandshell}
+ we obtain the output given in \cref{lst:textwrap6-mod5}.
+
+ \begin{widepage}
+ \cmhlistingsfromfile*{demonstrations/textwrap6-mod5.tex}{\texttt{textwrap6.tex} using \cref{lst:textwrap5-yaml}}{lst:textwrap6-mod5}
+ \end{widepage}
+
+ Notice that, because \texttt{environments} has been specified only for
+ \texttt{myenv} (in \cref{lst:textwrap5-yaml}) that the environment named \texttt{another} has
+ \emph{not} had text wrapping applied to it.
+
+ The {all} field can be specified with exceptions which can either
+ be done on a per-code-block or per-name basis; we explore this in relation to
+ \cref{lst:textwrap6} in the settings given in \crefrange{lst:textwrap6-yaml}{lst:textwrap8-yaml}.
+
+ \begin{adjustwidth}{-3.5cm}{-2.5cm}
+ \begin{minipage}{.33\linewidth}
+ \cmhlistingsfromfile*{demonstrations/textwrap6.yaml}[MLB-TCB]{\texttt{textwrap6.yaml}}{lst:textwrap6-yaml}
+ \end{minipage}%
+ \begin{minipage}{.33\linewidth}
+ \cmhlistingsfromfile*{demonstrations/textwrap7.yaml}[MLB-TCB]{\texttt{textwrap7.yaml}}{lst:textwrap7-yaml}
+ \end{minipage}%
+ \begin{minipage}{.33\linewidth}
+ \cmhlistingsfromfile*{demonstrations/textwrap8.yaml}[MLB-TCB]{\texttt{textwrap8.yaml}}{lst:textwrap8-yaml}
+ \end{minipage}
+ \end{adjustwidth}
+
+ Upon running the commands
+ \begin{commandshell}
+latexindent.pl -s textwrap6.tex -l=textwrap6.yaml -m
+latexindent.pl -s textwrap6.tex -l=textwrap7.yaml -m
+latexindent.pl -s textwrap6.tex -l=textwrap8.yaml -m
+ \end{commandshell}
+ we receive the respective output given in \crefrange{lst:textwrap6-mod6}{lst:textwrap6-mod8}.
+ \begin{widepage}
+ \cmhlistingsfromfile*{demonstrations/textwrap6-mod6.tex}{\texttt{textwrap6.tex} using \cref{lst:textwrap6-yaml}}{lst:textwrap6-mod6}
+
+ \cmhlistingsfromfile*{demonstrations/textwrap6-mod7.tex}{\texttt{textwrap6.tex} using \cref{lst:textwrap7-yaml}}{lst:textwrap6-mod7}
+
+ \cmhlistingsfromfile*{demonstrations/textwrap6-mod8.tex}{\texttt{textwrap6.tex} using \cref{lst:textwrap8-yaml}}{lst:textwrap6-mod8}
+ \end{widepage}
+
+ Notice that:
+ \begin{itemize}
+ \item in \cref{lst:textwrap6-mod6} the text wrapping routine has not been applied to any
+ \texttt{environments} because it has been switched off (per-code-block) in
+ \cref{lst:textwrap6-yaml};
+ \item in \cref{lst:textwrap6-mod7} the text wrapping routine has not been applied to
+ \texttt{myenv} because it has been switched off (per-name) in
+ \cref{lst:textwrap7-yaml};
+ \item in \cref{lst:textwrap6-mod8} the text wrapping routine has not been applied to
+ \texttt{masterDocument} because of the settings in \cref{lst:textwrap8-yaml}.
+ \end{itemize}
+
+ The \texttt{columns} field has a variety of different ways that it can be
+ specified; we've seen two basic ways already: the default (set to
+ \texttt{0}) and a positive integer (see \vref{lst:textwrap6}, for
+ example). We explore further options in \crefrange{lst:textwrap9-yaml}{lst:textwrap11-yaml}.
+
+ \begin{adjustwidth}{-3.5cm}{-2.5cm}
+ \begin{minipage}{.33\linewidth}
+ \cmhlistingsfromfile*{demonstrations/textwrap9.yaml}[MLB-TCB]{\texttt{textwrap9.yaml}}{lst:textwrap9-yaml}
+ \end{minipage}%
+ \begin{minipage}{.33\linewidth}
+ \cmhlistingsfromfile*{demonstrations/textwrap10.yaml}[MLB-TCB]{\texttt{textwrap10.yaml}}{lst:textwrap10-yaml}
+ \end{minipage}%
+ \begin{minipage}{.33\linewidth}
+ \cmhlistingsfromfile*{demonstrations/textwrap11.yaml}[MLB-TCB]{\texttt{textwrap11.yaml}}{lst:textwrap11-yaml}
+ \end{minipage}
+ \end{adjustwidth}
+
+ \Cref{lst:textwrap9-yaml} and \cref{lst:textwrap10-yaml} are equivalent. Upon running
+ the commands
+ \begin{commandshell}
+latexindent.pl -s textwrap6.tex -l=textwrap9.yaml -m
+latexindent.pl -s textwrap6.tex -l=textwrap11.yaml -m
+ \end{commandshell}
+ we receive the respective output given in \cref{lst:textwrap6-mod9,lst:textwrap6-mod11}.
+
+ \begin{widepage}
+ \cmhlistingsfromfile*{demonstrations/textwrap6-mod9.tex}{\texttt{textwrap6.tex} using \cref{lst:textwrap9-yaml}}{lst:textwrap6-mod9}
+
+ \cmhlistingsfromfile*{demonstrations/textwrap6-mod11.tex}{\texttt{textwrap6.tex} using \cref{lst:textwrap11-yaml}}{lst:textwrap6-mod11}
+ \end{widepage}
+
+ Notice that:
+ \begin{itemize}
+ \item in \cref{lst:textwrap6-mod9} the text for the \texttt{masterDocument} has been
+ wrapped using \texttt{30} columns, while \texttt{environments} has
+ been wrapped using \texttt{50} columns;
+ \item in \cref{lst:textwrap6-mod11} the text for \texttt{myenv} has been wrapped
+ using \texttt{50} columns, the text for \texttt{another} has
+ been wrapped using \texttt{15} columns, and \texttt{masterDocument}
+ has been wrapped using \texttt{30} columns.
+ \end{itemize}
+ If you don't specify a \texttt{default} value on per-code-block basis, then
+ the \texttt{default} value from \texttt{columns} will be inherited;
+ if you don't specify a default value for \texttt{columns} then
+ \texttt{80} will be used.
+
+ \texttt{alignAtAmpersandTakesPriority} is set to \texttt{1} by default; assuming
+ that text wrapping is occuring on a per-code-block basis, and the current
+ environment/code block is specified within \vref{lst:aligndelims:basic} then text wrapping
+ will be disabled for this code block.
+
+ If you wish to specify \texttt{afterHeading} commands (see
+ \vref{lst:indentAfterHeadings}) on a per-name basis, then you need to append the name with
+ \texttt{:heading}, for example, you might use \texttt{section:heading}.
+
+\subsubsection{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.
+ \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 it is possible to wrap text on a per-code-block and a per-name basis;
+ \announce*{2018-08-13}*{updates to textWrapOptions}
+ \item the text wrapping routine sets \texttt{preserveBlankLines} as
+ \texttt{1};
+ \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}
\subsection{oneSentencePerLine: modifying line breaks for sentences}\label{sec:onesentenceperline}
- You can instruct \texttt{latexindent.pl} to format%
- \announce{2018-01-13}{one sentence per line} your file so that it puts one sentence
- per line. Thank you to \cite{mlep} for helping to shape and test this feature. The behaviour of this part of the script is controlled by the switches detailed in \cref{lst:oneSentencePerLine},
- all of which we discuss next.
+ You can instruct \texttt{latexindent.pl} to
+ format%%%%%
+ \announce{2018-01-13}{one sentence per line} your file so that
+ it puts one sentence per line. Thank you to \cite{mlep} for helping to
+ shape and test this feature. The behaviour of this part of the script is controlled by
+ the switches detailed in \cref{lst:oneSentencePerLine}, all of which we discuss next.
- \cmhlistingsfromfile[style=oneSentencePerLine]*{../defaultSettings.yaml}[MLB-TCB,width=.85\linewidth,before=\centering]{\texttt{oneSentencePerLine}}{lst:oneSentencePerLine}
+ \cmhlistingsfromfile*[style=oneSentencePerLine]*{../defaultSettings.yaml}[MLB-TCB,width=.85\linewidth,before=\centering]{\texttt{oneSentencePerLine}}{lst:oneSentencePerLine}
\yamltitle{manipulateSentences}{0|1}
- This is a binary switch that details if \texttt{latexindent.pl} should perform the sentence manipulation routine; it
- is \emph{off} (set to \texttt{0}) by default, and you will need to turn it on (by setting it to \texttt{1}) if you want the script
+ This is a binary switch that details if \texttt{latexindent.pl} should perform the
+ sentence manipulation routine; it is \emph{off} (set to \texttt{0}) by default, and you will
+ need to turn it on (by setting it to \texttt{1}) if you want the script
to modify line breaks surrounding and within sentences.
\yamltitle{removeSentenceLineBreaks}{0|1}
- When operating upon sentences \texttt{latexindent.pl} will, by default, remove internal linebreaks as \texttt{removeSentenceLineBreaks}
- is set to \texttt{1}. Setting this switch to \texttt{0} instructs \texttt{latexindent.pl} not to do so.
+ When operating upon sentences \texttt{latexindent.pl} will, by default, remove
+ internal linebreaks as \texttt{removeSentenceLineBreaks} is set to \texttt{1}.
+ Setting this switch to \texttt{0} instructs \texttt{latexindent.pl}
+ not to do so.
For example, consider \texttt{multiple-sentences.tex} shown in \cref{lst:multiple-sentences}.
@@ -196,21 +406,26 @@
\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/keep-sen-line-breaks.yaml}[MLB-TCB]{\texttt{keep-sen-line-breaks.yaml}}{lst:keep-sen-line-breaks-yaml}
\end{minipage}
- Notice, in particular, that the `internal' sentence line breaks in \cref{lst:multiple-sentences} have
- been removed in \cref{lst:multiple-sentences-mod1}, but have not been removed in \cref{lst:multiple-sentences-mod2}.
+ Notice, in particular, that the `internal' sentence line breaks in
+ \cref{lst:multiple-sentences} have been removed in \cref{lst:multiple-sentences-mod1}, but have
+ not been removed in \cref{lst:multiple-sentences-mod2}.
- The remainder of the settings displayed in \vref{lst:oneSentencePerLine} instruct \texttt{latexindent.pl} on how to define
- a sentence. From the perpesctive of \texttt{latexindent.pl} a sentence must:
+ The remainder of the settings displayed in \vref{lst:oneSentencePerLine} instruct
+ \texttt{latexindent.pl} on how to define a sentence. From the perpesctive of
+ \texttt{latexindent.pl} a sentence must:
\begin{itemize}
- \item \emph{follow} a certain character or set of characters (see \cref{lst:sentencesFollow}); by default, this is either \lstinline!\par!, a blank line,
- a full stop/period (.), exclamation mark (!), question mark (?) right brace (\}) or a comment
- on the previous line;
- \item \emph{begin} with a character type (see \cref{lst:sentencesBeginWith}); by default, this is only capital letters;
- \item \emph{end} with a character (see \cref{lst:sentencesEndWith}); by default, these are
- full stop/period (.), exclamation mark (!) and question mark (?).
+ \item \emph{follow} a certain character or set of characters (see
+ \cref{lst:sentencesFollow}); by default, this is either \lstinline!\par!, a
+ blank line, a full stop/period (.), exclamation mark (!), question mark (?) right brace
+ (\}) or a comment on the previous line;
+ \item \emph{begin} with a character type (see \cref{lst:sentencesBeginWith}); by
+ default, this is only capital letters;
+ \item \emph{end} with a character (see \cref{lst:sentencesEndWith}); by
+ default, these are full stop/period (.), exclamation mark (!) and question mark (?).
\end{itemize}
- In each case, you can specify the \texttt{other} field to include any pattern that you would like; you can specify anything in
- this field using the language of regular expressions.
+ In each case, you can specify the \texttt{other} field to include any
+ pattern that you would like; you can specify anything in this field using the language of
+ regular expressions.
\begin{adjustwidth}{-3.5cm}{-2.5cm}
\begin{minipage}{.36\linewidth}
@@ -227,8 +442,9 @@
\end{adjustwidth}
\subsubsection{sentencesFollow}
- Let's explore a few of the switches in \texttt{sentencesFollow}; let's start with \vref{lst:multiple-sentences}, and use the YAML
- settings given in \cref{lst:sentences-follow1-yaml}. Using the command
+ Let's explore a few of the switches in \texttt{sentencesFollow}; let's start with
+ \vref{lst:multiple-sentences}, and use the YAML settings given in
+ \cref{lst:sentences-follow1-yaml}. Using the command
\begin{commandshell}
latexindent.pl multiple-sentences -m -l=sentences-follow1.yaml
\end{commandshell}
@@ -242,10 +458,12 @@
\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/sentences-follow1.yaml}[MLB-TCB]{\texttt{sentences-follow1.yaml}}{lst:sentences-follow1-yaml}
\end{minipage}
- Notice that, because \texttt{blankLine} is set to \texttt{0}, \texttt{latexindent.pl} will not seek sentences following a blank line,
- and so the fourth sentence has not been accounted for.
+ Notice that, because \texttt{blankLine} is set to \texttt{0},
+ \texttt{latexindent.pl} will not seek sentences following a blank line, and so the
+ fourth sentence has not been accounted for.
- We can explore the \texttt{other} field in \cref{lst:sentencesFollow} with the \texttt{.tex} file detailed in \cref{lst:multiple-sentences1}.
+ We can explore the \texttt{other} field in \cref{lst:sentencesFollow} with
+ the \texttt{.tex} file detailed in \cref{lst:multiple-sentences1}.
\cmhlistingsfromfile{demonstrations/multiple-sentences1.tex}{\texttt{multiple-sentences1.tex}}{lst:multiple-sentences1}
@@ -267,14 +485,17 @@
\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/sentences-follow2.yaml}[MLB-TCB]{\texttt{sentences-follow2.yaml}}{lst:sentences-follow2-yaml}
\end{minipage}
- Notice that in \cref{lst:multiple-sentences1-mod1} the first sentence after the \texttt{)} has not been accounted for, but that
- following the inclusion of \cref{lst:sentences-follow2-yaml}, the output given in \cref{lst:multiple-sentences1-mod2} demonstrates that
- the sentence \emph{has} been accounted for correctly.
+ Notice that in \cref{lst:multiple-sentences1-mod1} the first sentence after the
+ \texttt{)} has not been accounted for, but that following the inclusion
+ of \cref{lst:sentences-follow2-yaml}, the output given in \cref{lst:multiple-sentences1-mod2}
+ demonstrates that the sentence \emph{has} been accounted for correctly.
\subsubsection{sentencesBeginWith}
- By default, \texttt{latexindent.pl} will only assume that sentences begin with the upper case letters \texttt{A-Z}; you can instruct the
- script to define sentences to begin with lower case letters (see \cref{lst:sentencesBeginWith}), and we can use the \texttt{other} field
- to define sentences to begin with other characters.
+ By default, \texttt{latexindent.pl} will only assume that sentences begin with the
+ upper case letters \texttt{A-Z}; you can instruct the script to define
+ sentences to begin with lower case letters (see \cref{lst:sentencesBeginWith}), and we can
+ use the \texttt{other} field to define sentences to begin with other
+ characters.
\cmhlistingsfromfile{demonstrations/multiple-sentences2.tex}{\texttt{multiple-sentences2.tex}}{lst:multiple-sentences2}
@@ -295,14 +516,19 @@
\begin{minipage}{.45\linewidth}
\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/sentences-begin1.yaml}[MLB-TCB]{\texttt{sentences-begin1.yaml}}{lst:sentences-begin1-yaml}
\end{minipage}
- Notice that in \cref{lst:multiple-sentences2-mod1}, the first sentence has been accounted for but that the subsequent sentences
- have not. In \cref{lst:multiple-sentences2-mod2}, all of the sentences have been accounted for, because the \texttt{other} field
- in \cref{lst:sentences-begin1-yaml} has defined sentences to begin with either \lstinline!$! or any numeric digit, \texttt{0} to \texttt{9}.
+ Notice that in \cref{lst:multiple-sentences2-mod1}, the first sentence has been accounted for but
+ that the subsequent sentences have not. In \cref{lst:multiple-sentences2-mod2}, all of the
+ sentences have been accounted for, because the \texttt{other} field in
+ \cref{lst:sentences-begin1-yaml} has defined sentences to begin with either
+ \lstinline!$! or any numeric digit, \texttt{0} to
+ \texttt{9}.
\subsubsection{sentencesEndWith}
- Let's return to \vref{lst:multiple-sentences}; we have already seen the default way in which \texttt{latexindent.pl} will operate on the
- sentences in this file in \vref{lst:multiple-sentences-mod1}. We can populate the \texttt{other} field with any character that we wish;
- for example, using the YAML specified in \cref{lst:sentences-end1-yaml} and the command
+ Let's return to \vref{lst:multiple-sentences}; we have already seen the default way in
+ which \texttt{latexindent.pl} will operate on the sentences in this file in
+ \vref{lst:multiple-sentences-mod1}. We can populate the \texttt{other} field with
+ any character that we wish; for example, using the YAML specified in
+ \cref{lst:sentences-end1-yaml} and the command
\begin{commandshell}
latexindent.pl multiple-sentences -m -l=sentences-end1.yaml
latexindent.pl multiple-sentences -m -l=sentences-end2.yaml
@@ -325,13 +551,16 @@
\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/sentences-end2.yaml}[MLB-TCB]{\texttt{sentences-end2.yaml}}{lst:sentences-end2-yaml}
\end{minipage}
- There is a subtle difference between the output in \cref{lst:multiple-sentences-mod4,lst:multiple-sentences-mod5}; in particular,
- in \cref{lst:multiple-sentences-mod4} the word \texttt{sentence} has not been defined as a sentence, because we have not instructed
- \texttt{latexindent.pl} to begin sentences with lower case letters. We have changed this by using the settings in \cref{lst:sentences-end2-yaml},
- and the associated output in \cref{lst:multiple-sentences-mod5} reflects this.
+ There is a subtle difference between the output in \cref{lst:multiple-sentences-mod4,lst:multiple-sentences-mod5}; in
+ particular, in \cref{lst:multiple-sentences-mod4} the word \texttt{sentence} has not
+ been defined as a sentence, because we have not instructed \texttt{latexindent.pl} to
+ begin sentences with lower case letters. We have changed this by using the settings in
+ \cref{lst:sentences-end2-yaml}, and the associated output in \cref{lst:multiple-sentences-mod5}
+ reflects this.
- Referencing \vref{lst:sentencesEndWith}, you'll notice that there is a field called \texttt{basicFullStop}, which
- is set to \texttt{0}, and that the \texttt{betterFullStop} is set to \texttt{1} by default.
+ Referencing \vref{lst:sentencesEndWith}, you'll notice that there is a field called
+ \texttt{basicFullStop}, which is set to \texttt{0}, and that the
+ \texttt{betterFullStop} is set to \texttt{1} by default.
Let's consider the file shown in \cref{lst:url}.
@@ -345,22 +574,25 @@
\cmhlistingsfromfile{demonstrations/url-mod1.tex}{\texttt{url.tex} using \vref{lst:manipulate-sentences-yaml}}{lst:url-mod1}
- Notice that the full stop within the url has been interpreted correctly. This is because, within the \texttt{betterFullStop},
- full stops at the end of sentences have the following properties:
+ Notice that the full stop within the url has been interpreted correctly. This is because,
+ within the \texttt{betterFullStop}, full stops at the end of sentences have the
+ following properties:
\begin{itemize}
\item they are ignored within \texttt{e.g.} and \texttt{i.e.};
\item they can not be immediately followed by a lower case or upper case letter;
\item they can not be immediately followed by a hyphen, comma, or number.
\end{itemize}
- If you find that the \texttt{betterFullStop} does not work for your purposes, then you can switch it off by setting
- it to \texttt{0}, and you can experiment with the \texttt{other} field.
+ If you find that the \texttt{betterFullStop} does not work for your purposes, then
+ you can switch it off by setting it to \texttt{0}, and you can
+ experiment with the \texttt{other} field.
- The \texttt{basicFullStop} routine should probably be avoided in most situations, as it does not accomodate the specifications
- above. For example, using the following command
+ The \texttt{basicFullStop} routine should probably be avoided in most situations, as
+ it does not accomodate the specifications above. For example, using the following command
\begin{commandshell}
latexindent.pl url -m -l=alt-full-stop1.yaml
\end{commandshell}
- and the YAML in \cref{lst:alt-full-stop1-yaml} gives the output in \cref{lst:url-mod2}.
+ and the YAML in \cref{lst:alt-full-stop1-yaml} gives the output in
+ \cref{lst:url-mod2}.
\begin{adjustwidth}{-3.5cm}{-1.5cm}
\begin{minipage}{.6\linewidth}
@@ -372,35 +604,38 @@
\end{minipage}
\end{adjustwidth}
- Notice that the full stop within the URL has not been accomodated correctly because of the non-default settings in \cref{lst:alt-full-stop1-yaml}.
+ Notice that the full stop within the URL has not been accomodated correctly because of
+ the non-default settings in \cref{lst:alt-full-stop1-yaml}.
\subsubsection{Features of the oneSentencePerLine routine}
- The sentence manipulation routine takes place \emph{after} verbatim environments, preamble and trailing comments have
- been accounted for; this means that any characters within these types of code blocks will not be part
- of the sentence manipulation routine.
+ The sentence manipulation routine takes place \emph{after} verbatim
+ environments, preamble and trailing comments have been accounted for; this means that any
+ characters within these types of code blocks will not be part of the sentence
+ manipulation routine.
- For example, if we begin with the \texttt{.tex} file in \cref{lst:multiple-sentences3}, and run the command
+ For example, if we begin with the \texttt{.tex} file in
+ \cref{lst:multiple-sentences3}, and run the command
\begin{commandshell}
latexindent.pl multiple-sentences3 -m -l=manipulate-sentences.yaml
\end{commandshell}
- then we obtain the output in \cref{lst:multiple-sentences3-mod1}.
- \cmhlistingsfromfile{demonstrations/multiple-sentences3.tex}{\texttt{multiple-sentences3.tex}}{lst:multiple-sentences3}
+ then we obtain the output in \cref{lst:multiple-sentences3-mod1}. \cmhlistingsfromfile{demonstrations/multiple-sentences3.tex}{\texttt{multiple-sentences3.tex}}{lst:multiple-sentences3}
\cmhlistingsfromfile{demonstrations/multiple-sentences3-mod1.tex}{\texttt{multiple-sentences3.tex} using \vref{lst:manipulate-sentences-yaml}}{lst:multiple-sentences3-mod1}
- Furthermore, if sentences run across environments then, by default, the line breaks internal to the sentence will be removed.
- For example, if we use the \texttt{.tex} file in \cref{lst:multiple-sentences4} and run the commands
+ Furthermore, if sentences run across environments then, by default, the line breaks
+ internal to the sentence will be removed. For example, if we use the
+ \texttt{.tex} file in \cref{lst:multiple-sentences4} and run the commands
\begin{commandshell}
latexindent.pl multiple-sentences4 -m -l=manipulate-sentences.yaml
latexindent.pl multiple-sentences4 -m -l=keep-sen-line-breaks.yaml
\end{commandshell}
- then we obtain the output in \cref{lst:multiple-sentences4-mod1,lst:multiple-sentences4-mod2}.
- \cmhlistingsfromfile{demonstrations/multiple-sentences4.tex}{\texttt{multiple-sentences4.tex}}{lst:multiple-sentences4}
+ then we obtain the output in \cref{lst:multiple-sentences4-mod1,lst:multiple-sentences4-mod2}. \cmhlistingsfromfile{demonstrations/multiple-sentences4.tex}{\texttt{multiple-sentences4.tex}}{lst:multiple-sentences4}
\begin{widepage}
\cmhlistingsfromfile{demonstrations/multiple-sentences4-mod1.tex}{\texttt{multiple-sentences4.tex} using \vref{lst:manipulate-sentences-yaml}}{lst:multiple-sentences4-mod1}
\end{widepage}
\cmhlistingsfromfile{demonstrations/multiple-sentences4-mod2.tex}{\texttt{multiple-sentences4.tex} using \vref{lst:keep-sen-line-breaks-yaml}}{lst:multiple-sentences4-mod2}
- Once you've read \cref{sec:poly-switches}, you will know that you can accomodate the removal of internal sentence line breaks
- by using the YAML in \cref{lst:item-rules2-yaml} and the command
+ Once you've read \cref{sec:poly-switches}, you will know that you can accomodate the
+ removal of internal sentence line breaks by using the YAML in \cref{lst:item-rules2-yaml}
+ and the command
\begin{commandshell}
latexindent.pl multiple-sentences4 -m -l=item-rules2.yaml
\end{commandshell}
@@ -414,31 +649,66 @@
\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/item-rules2.yaml}[MLB-TCB]{\texttt{item-rules2.yaml}}{lst:item-rules2-yaml}
\end{minipage}
-\subsection{removeParagraphLineBreaks: modifying line breaks for paragraphs}
- 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.
+\subsubsection{text wrapping and indenting sentences}
+ The \texttt{oneSentencePerLine}%%
+ \announce*{2018-08-13}{oneSentencePerline text wrap and indent} can be instructed to perform
+ text wrapping and indentation upon sentences.
+
+ Let's use the code in \cref{lst:multiple-sentences5}.
+
+ \cmhlistingsfromfile*{demonstrations/multiple-sentences5.tex}{\texttt{multiple-sentences5.tex}}{lst:multiple-sentences5}
+
+ Referencing \cref{lst:sentence-wrap1-yaml}, and running the following command
+ \begin{commandshell}
+latexindent.pl multiple-sentences5 -m -l=sentence-wrap1.yaml
+\end{commandshell}
+ we receive the output given in \cref{lst:multiple-sentences5-mod1}.
+
+ \begin{widepage}
+ \begin{minipage}{.55\linewidth}
+ \cmhlistingsfromfile*{demonstrations/multiple-sentences5-mod1.tex}{\texttt{multiple-sentences5.tex} using \cref{lst:sentence-wrap1-yaml}}{lst:multiple-sentences5-mod1}
+ \end{minipage}%
+ \hfill
+ \begin{minipage}{.45\linewidth}
+ \cmhlistingsfromfile*[style=yaml-LST]*{demonstrations/sentence-wrap1.yaml}[MLB-TCB]{\texttt{sentence-wrap1.yaml}}{lst:sentence-wrap1-yaml}
+ \end{minipage}
+ \end{widepage}
+
+ If you wish to specify the \texttt{columns} field on a per-code-block basis
+ for sentences, then you would use \texttt{sentence}; explicitly, starting with
+ \vref{lst:textwrap9-yaml}, for example, you would replace/append
+ \texttt{environments} with, for example, \texttt{sentence: 50}.
+
+\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}.
+ This feature is considered complimentary to the \texttt{oneSentencePerLine} feature
+ described in \vref{sec:onesentenceperline}.
- \cmhlistingsfromfile[style=removeParagraphLineBreaks]*{../defaultSettings.yaml}[MLB-TCB,width=.85\linewidth,before=\centering]{\texttt{removeParagraphLineBreaks}}{lst: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:
+ 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}.
+ \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}.
+ 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[showspaces=true]{demonstrations/shortlines.tex}{\texttt{shortlines.tex}}{lst:shortlines}
@@ -456,19 +726,21 @@
\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
+ 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.
+ 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}
+ 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}
@@ -491,13 +763,15 @@
\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.
+ 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
+ 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}
@@ -521,13 +795,15 @@
\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 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}.
+ 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}
@@ -543,23 +819,31 @@
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}
+ 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
+ \cref{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}.
+ 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}.
- \cmhlistingsfromfile[style=paragraphsStopAt]*{../defaultSettings.yaml}[MLB-TCB,width=.85\linewidth,before=\centering]{\texttt{paragraphsStopAt}}{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.
+ 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}.
+ 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}
@@ -579,52 +863,112 @@
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:
+ 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.
+ \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}.
+ 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{Combining removeParagraphLineBreaks and textWrapOptions}\label{subsec:removeparagraphlinebreaks:and:textwrap}
+
+ The%%%%
+ \announce*{2018-08-13}{combine text wrap and remove paragraph line breaks} text wrapping
+ routine (\vref{subsec:textwrapping}) and remove paragraph line breaks routine
+ (\vref{subsec:removeparagraphlinebreaks}) can be combined.
+
+ We motivate this feature with the code given in \cref{lst:textwrap7}.
+
+ \cmhlistingsfromfile*{demonstrations/textwrap7.tex}{\texttt{textwrap7.tex}}{lst:textwrap7}
+
+ Applying the text wrap routine from \vref{subsec:textwrapping} with, for example,
+ \vref{lst:textwrap3-yaml} gives the output in \cref{lst:textwrap7-mod3}.
+
+ \cmhlistingsfromfile*{demonstrations/textwrap7-mod3.tex}{\texttt{textwrap7.tex} using \cref{lst:textwrap3-yaml}}{lst:textwrap7-mod3}
+
+ The text wrapping routine has behaved as expected, but it may be desired to remove
+ paragraph line breaks \emph{before} performing the text wrapping routine.
+ The desired behaviour can be achieved by employing the \texttt{beforeTextWrap}
+ switch.
+
+ Explicitly, using the settings in \cref{lst:textwrap12-yaml} and running the command
+ \begin{commandshell}
+latexindent.pl -m textwrap7.tex -l=textwrap12.yaml -o=+-mod12
+ \end{commandshell}
+ we obtain the output in \cref{lst:textwrap7-mod12}.
+
+ \begin{minipage}{.45\linewidth}
+ \cmhlistingsfromfile*{demonstrations/textwrap7-mod12.tex}{\texttt{textwrap7-mod12.tex}}{lst:textwrap7-mod12}
+ \end{minipage}
+ \hfill
+ \begin{minipage}{.49\linewidth}
+ \cmhlistingsfromfile*{demonstrations/textwrap12.yaml}[MLB-TCB]{\texttt{textwrap12.yaml}}{lst:textwrap12-yaml}
+ \end{minipage}
+
+ In \cref{lst:textwrap7-mod12} the paragraph linebreaks have first been removed from
+ \cref{lst:textwrap7}, and then the text wrapping routine has been applied. It is
+ envisaged that variants of \cref{lst:textwrap12-yaml} will be among the most useful
+ settings for these two features.
+
\subsection{Poly-switches}\label{sec:poly-switches}
- Every other field in the \texttt{modifyLineBreaks} field uses poly-switches, and can take
- one of \emph{five}%
+ Every other field in the \texttt{modifyLineBreaks} field uses poly-switches, and can
+ take one of \emph{five}%%%%%
\announce{2017-08-21}*{blank line poly-switch} integer values:
\begin{itemize}[font=\bfseries]
- \item[$-1$] \emph{remove mode}: line breaks before or after the \emph{<part of thing>} can be removed (assuming that \texttt{preserveBlankLines} is set to \texttt{0});
- \item[0] \emph{off mode}: line breaks will not be modified for the \emph{<part of thing>} under consideration;
- \item[1] \emph{add mode}: a line break will be added before or after the \emph{<part of thing>} under consideration, assuming that
+ \item[$-1$] \emph{remove mode}: line breaks before or after the
+ \emph{<part of thing>} can be removed (assuming that \texttt{preserveBlankLines} is
+ set to \texttt{0});
+ \item[0] \emph{off mode}: line breaks will not be modified for the
+ \emph{<part of thing>} under consideration;
+ \item[1] \emph{add mode}: a line break will be added before or after the
+ \emph{<part of thing>} under consideration, assuming that
there is not already a line break before or after the \emph{<part of thing>};
- \item[2] \emph{comment then add mode}: a comment symbol will be added, followed by a line break before or after the \emph{<part of thing>} under consideration, assuming that
- there is not already a comment and line break before or after the \emph{<part of thing>};
+ \item[2] \emph{comment then add mode}: a comment symbol will be added, followed by a line break
+ before or after the \emph{<part of thing>} under consideration, assuming that there
+ is not already a comment and line break before or after the \emph{<part of thing>};
\item[3] \emph{add then blank line mode}%
- \announce{2017-08-21}{blank line poly-switch}: a line break will be added before or after the \emph{<part of thing>} under consideration, assuming that
- there is not already a line break before or after the \emph{<part of thing>}, followed by a blank line.
+ \announce{2017-08-21}{blank line poly-switch}: a line break will be added before or after the
+ \emph{<part of thing>} under consideration, assuming that
+ there is not already a line break before or after the \emph{<part of thing>},
+ followed by a blank line.
\end{itemize}
- In the above, \emph{<part of thing>} refers to either the \emph{begin statement}, \emph{body} or \emph{end statement} of the
- code blocks detailed in \vref{tab:code-blocks}.
- All poly-switches are \emph{off} by default; \texttt{latexindent.pl} searches first of all for per-name settings, and then followed by global per-thing settings.
+ In the above, \emph{<part of thing>} refers to either the
+ \emph{begin statement}, \emph{body} or \emph{end statement}
+ of the code blocks detailed in \vref{tab:code-blocks}. All poly-switches are
+ \emph{off} by default; \texttt{latexindent.pl} searches first of all
+ for per-name settings, and then followed by global per-thing settings.
\subsection{modifyLineBreaks for environments}\label{sec:modifylinebreaks-environments}
- We start by viewing a snippet of \texttt{defaultSettings.yaml} in \cref{lst:environments-mlb}; note that it contains \emph{global} settings (immediately
- 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.
+ We start by viewing a snippet of \texttt{defaultSettings.yaml} in
+ \cref{lst:environments-mlb}; note that it contains \emph{global} settings
+ (immediately 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[style=modifylinebreaksEnv]*{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,MLB-TCB]{\texttt{environments}}{lst:environments-mlb}
- 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$,
- $\BodyStartsOnOwnLine$, $\EndStartsOnOwnLine$ and $\EndFinishesWithLineBreak$, these will be related to fields specified in \cref{lst:environments-mlb}.
+ 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$,
+ $\BodyStartsOnOwnLine$, $\EndStartsOnOwnLine$ and $\EndFinishesWithLineBreak$,
+ these will be related to fields specified in \cref{lst:environments-mlb}.
\begin{cmhlistings}[style=tcblatex,escapeinside={(*@}{@*)}]{\texttt{env-mlb1.tex}}{lst:env-mlb1-tex}
before words(*@$\BeginStartsOnOwnLine$@*) \begin{myenv}(*@$\BodyStartsOnOwnLine$@*)body of myenv(*@$\EndStartsOnOwnLine$@*)\end{myenv}(*@$\EndFinishesWithLineBreak$@*) after words
@@ -631,8 +975,9 @@
\end{cmhlistings}
\subsubsection{Adding line breaks: BeginStartsOnOwnLine and BodyStartsOnOwnLine}
- Let's explore \texttt{BeginStartsOnOwnLine} and \texttt{BodyStartsOnOwnLine} in \cref{lst:env-mlb1,lst:env-mlb2}, and in particular,
- let's allow each of them in turn to take a value of $1$.
+ Let's explore \texttt{BeginStartsOnOwnLine} and \texttt{BodyStartsOnOwnLine} in
+ \cref{lst:env-mlb1,lst:env-mlb2}, and in particular, let's allow each of them in turn to take
+ a value of $1$.
\begin{minipage}{.45\textwidth}
\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/env-mlb1.yaml}[MLB-TCB]{\texttt{env-mlb1.yaml}}{lst:env-mlb1}
@@ -661,14 +1006,19 @@
There are a couple of points to note:
\begin{itemize}
- \item in \cref{lst:env-mlb-mod1} a line break has been added at the point denoted by $\BeginStartsOnOwnLine$ in \cref{lst:env-mlb1-tex}; no
- other line breaks have been changed;
- \item in \cref{lst:env-mlb-mod2} a line break has been added at the point denoted by $\BodyStartsOnOwnLine$ in \cref{lst:env-mlb1-tex};
- furthermore, note that the \emph{body} of \texttt{myenv} has received the appropriate (default) indentation.
+ \item in \cref{lst:env-mlb-mod1} a line break has been added at the point denoted by
+ $\BeginStartsOnOwnLine$ in \cref{lst:env-mlb1-tex}; no other line breaks have been
+ changed;
+ \item in \cref{lst:env-mlb-mod2} a line break has been added at the point denoted by
+ $\BodyStartsOnOwnLine$ in \cref{lst:env-mlb1-tex}; furthermore, note that the
+ \emph{body} of \texttt{myenv} has received the appropriate
+ (default) indentation.
\end{itemize}
- Let's now change each of the \texttt{1} values in \cref{lst:env-mlb1,lst:env-mlb2} so that they are $2$ and
- save them into \texttt{env-mlb3.yaml} and \texttt{env-mlb4.yaml} respectively (see \cref{lst:env-mlb3,lst:env-mlb4}).
+ Let's now change each of the \texttt{1} values in
+ \cref{lst:env-mlb1,lst:env-mlb2} so that they are $2$ and save them
+ into \texttt{env-mlb3.yaml} and \texttt{env-mlb4.yaml} respectively (see
+ \cref{lst:env-mlb3,lst:env-mlb4}).
\begin{minipage}{.45\textwidth}
\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/env-mlb3.yaml}[MLB-TCB]{\texttt{env-mlb3.yaml}}{lst:env-mlb3}
@@ -690,13 +1040,15 @@
\end{minipage}
\end{widepage}
- Note that line breaks have been added as in \cref{lst:env-mlb-mod1,lst:env-mlb-mod2}, but this time a comment symbol
- has been added before adding the line break; in both cases, trailing horizontal
- space has been stripped before doing so.
+ Note that line breaks have been added as in \cref{lst:env-mlb-mod1,lst:env-mlb-mod2}, but this time a
+ comment symbol has been added before adding the line break; in both cases, trailing
+ horizontal space has been stripped before doing so.
- Let's%
- \announce{2017-08-21}{demonstration of blank line poly-switch (3)} now change each of the \texttt{1} values in \cref{lst:env-mlb1,lst:env-mlb2} so that they are $3$ and
- save them into \texttt{env-mlb5.yaml} and \texttt{env-mlb6.yaml} respectively (see \cref{lst:env-mlb5,lst:env-mlb6}).
+ Let's%%%%%
+ \announce{2017-08-21}{demonstration of blank line poly-switch (3)} now change each
+ of the \texttt{1} values in \cref{lst:env-mlb1,lst:env-mlb2} so that they are
+ $3$ and save them into \texttt{env-mlb5.yaml} and
+ \texttt{env-mlb6.yaml} respectively (see \cref{lst:env-mlb5,lst:env-mlb6}).
\begin{minipage}{.45\textwidth}
\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/env-mlb5.yaml}[MLB-TCB]{\texttt{env-mlb5.yaml}}{lst:env-mlb5}
@@ -718,12 +1070,13 @@
\end{minipage}
\end{widepage}
- Note that line breaks have been added as in \cref{lst:env-mlb-mod1,lst:env-mlb-mod2}, but this time a \emph{blank line}
- has been added after adding the line break.
+ Note that line breaks have been added as in \cref{lst:env-mlb-mod1,lst:env-mlb-mod2}, but this time a
+ \emph{blank line} has been added after adding the line break.
\subsubsection{Adding line breaks using EndStartsOnOwnLine and EndFinishesWithLineBreak}
- Let's explore \texttt{EndStartsOnOwnLine} and \texttt{EndFinishesWithLineBreak} in \cref{lst:env-mlb7,lst:env-mlb8},
- and in particular, let's allow each of them in turn to take a value of $1$.
+ Let's explore \texttt{EndStartsOnOwnLine} and \texttt{EndFinishesWithLineBreak} in
+ \cref{lst:env-mlb7,lst:env-mlb8}, and in particular, let's allow each of them in turn to take
+ a value of $1$.
\begin{minipage}{.49\textwidth}
\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/env-mlb7.yaml}[MLB-TCB]{\texttt{env-mlb7.yaml}}{lst:env-mlb7}
@@ -752,13 +1105,18 @@
There are a couple of points to note:
\begin{itemize}
- \item in \cref{lst:env-mlb-mod7} a line break has been added at the point denoted by $\EndStartsOnOwnLine$ in \vref{lst:env-mlb1-tex}; no
- other line breaks have been changed and the \lstinline!\end{myenv}! statement has \emph{not} received indentation (as intended);
- \item in \cref{lst:env-mlb-mod8} a line break has been added at the point denoted by $\EndFinishesWithLineBreak$ in \vref{lst:env-mlb1-tex}.
+ \item in \cref{lst:env-mlb-mod7} a line break has been added at the point denoted by
+ $\EndStartsOnOwnLine$ in \vref{lst:env-mlb1-tex}; no other line breaks have been
+ changed and the \lstinline!\end{myenv}! statement has \emph{not}
+ received indentation (as intended);
+ \item in \cref{lst:env-mlb-mod8} a line break has been added at the point denoted by
+ $\EndFinishesWithLineBreak$ in \vref{lst:env-mlb1-tex}.
\end{itemize}
- Let's now change each of the \texttt{1} values in \cref{lst:env-mlb7,lst:env-mlb8} so that they are $2$ and
- save them into \texttt{env-mlb9.yaml} and \texttt{env-mlb10.yaml} respectively (see \cref{lst:env-mlb9,lst:env-mlb10}).
+ Let's now change each of the \texttt{1} values in
+ \cref{lst:env-mlb7,lst:env-mlb8} so that they are $2$ and save them
+ into \texttt{env-mlb9.yaml} and \texttt{env-mlb10.yaml} respectively (see
+ \cref{lst:env-mlb9,lst:env-mlb10}).
\begin{minipage}{.49\textwidth}
\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/env-mlb9.yaml}[MLB-TCB]{\texttt{env-mlb9.yaml}}{lst:env-mlb9}
@@ -780,13 +1138,15 @@
\end{minipage}
\end{widepage}
- Note that line breaks have been added as in \cref{lst:env-mlb-mod7,lst:env-mlb-mod8}, but this time a comment symbol
- has been added before adding the line break; in both cases, trailing horizontal
- space has been stripped before doing so.
+ Note that line breaks have been added as in \cref{lst:env-mlb-mod7,lst:env-mlb-mod8}, but this time a
+ comment symbol has been added before adding the line break; in both cases, trailing
+ horizontal space has been stripped before doing so.
- Let's%
- \announce{2017-08-21}{demonstration of blank line poly-switch (3)} now change each of the \texttt{1} values in \cref{lst:env-mlb7,lst:env-mlb8} so that they are $3$ and
- save them into \texttt{env-mlb11.yaml} and \texttt{env-mlb12.yaml} respectively (see \cref{lst:env-mlb11,lst:env-mlb12}).
+ Let's%%%%%
+ \announce{2017-08-21}{demonstration of blank line poly-switch (3)} now change each of
+ the \texttt{1} values in \cref{lst:env-mlb7,lst:env-mlb8} so that they are
+ $3$ and save them into \texttt{env-mlb11.yaml} and
+ \texttt{env-mlb12.yaml} respectively (see \cref{lst:env-mlb11,lst:env-mlb12}).
\begin{minipage}{.49\textwidth}
\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/env-mlb11.yaml}[MLB-TCB]{\texttt{env-mlb11.yaml}}{lst:env-mlb11}
@@ -808,13 +1168,15 @@
\end{minipage}
\end{widepage}
- Note that line breaks have been added as in \cref{lst:env-mlb-mod7,lst:env-mlb-mod8}, and that a \emph{blank line}
- has been added after the line break.
+ Note that line breaks have been added as in \cref{lst:env-mlb-mod7,lst:env-mlb-mod8}, and that a
+ \emph{blank line} has been added after the line break.
\subsubsection{poly-switches only add line breaks when necessary}
- If you ask \texttt{latexindent.pl} to add a line break (possibly with a comment) using a poly-switch value of $1$ (or $2$),
- it will only do so if necessary. For example, if you process the file in \vref{lst:mlb2} using any of the YAML
- files presented so far in this section, it will be left unchanged.
+ If you ask \texttt{latexindent.pl} to add a line break (possibly with a comment)
+ using a poly-switch value of $1$ (or $2$),
+ it will only do so if necessary. For example, if you process the file in
+ \vref{lst:mlb2} using any of the YAML files presented so far in this section,
+ it will be left unchanged.
\begin{minipage}{.45\linewidth}
\cmhlistingsfromfile{demonstrations/env-mlb2.tex}{\texttt{env-mlb2.tex}}{lst:mlb2}
@@ -824,13 +1186,15 @@
\cmhlistingsfromfile{demonstrations/env-mlb3.tex}{\texttt{env-mlb3.tex}}{lst:mlb3}
\end{minipage}
- In contrast, the output from processing the file in \cref{lst:mlb3} will vary depending
- on the poly-switches used; in \cref{lst:env-mlb3-mod2} you'll see that the comment symbol after
- the \lstinline!\begin{myenv}! has been moved to the next line, as \texttt{BodyStartsOnOwnLine}
- is set to \texttt{1}. In \cref{lst:env-mlb3-mod4} you'll see that the comment has been accounted
- for correctly because \texttt{BodyStartsOnOwnLine} has been set to \texttt{2},
- and the comment symbol has \emph{not} been moved to its own line. You're encouraged to experiment
- with \cref{lst:mlb3} and by setting the other poly-switches considered so far to \texttt{2} in turn.
+ In contrast, the output from processing the file in \cref{lst:mlb3} will vary
+ depending on the poly-switches used; in \cref{lst:env-mlb3-mod2} you'll see that the
+ comment symbol after the \lstinline!\begin{myenv}! has been moved to the next line, as
+ \texttt{BodyStartsOnOwnLine} is set to \texttt{1}. In
+ \cref{lst:env-mlb3-mod4} you'll see that the comment has been accounted for correctly
+ because \texttt{BodyStartsOnOwnLine} has been set to \texttt{2}, and the
+ comment symbol has \emph{not} been moved to its own line. You're
+ encouraged to experiment with \cref{lst:mlb3} and by setting the other
+ poly-switches considered so far to \texttt{2} in turn.
\begin{minipage}{.45\linewidth}
\cmhlistingsfromfile{demonstrations/env-mlb3-mod2.tex}{\texttt{env-mlb3.tex} using \vref{lst:env-mlb2}}{lst:env-mlb3-mod2}
@@ -840,15 +1204,19 @@
\cmhlistingsfromfile{demonstrations/env-mlb3-mod4.tex}{\texttt{env-mlb3.tex} using \vref{lst:env-mlb4}}{lst:env-mlb3-mod4}
\end{minipage}
- The details of the discussion in this section have concerned \emph{global} poly-switches in the \texttt{environments} field;
- each switch can also be specified on a \emph{per-name} basis, which would take priority over the global values; with
- reference to \vref{lst:environments-mlb}, an example is shown for the \texttt{equation*} environment.
+ The details of the discussion in this section have concerned \emph{global}
+ poly-switches in the \texttt{environments} field; each switch can also be specified
+ on a \emph{per-name} basis, which would take priority over the global values;
+ with reference to \vref{lst:environments-mlb}, an example is shown for the
+ \texttt{equation*} environment.
\subsubsection{Removing line breaks (poly-switches set to $-1$)}
- Setting poly-switches to $-1$ tells \texttt{latexindent.pl} to remove line breaks of the \emph{<part of the thing>}, if necessary. We will consider the
+ Setting poly-switches to $-1$ tells \texttt{latexindent.pl} to
+ remove line breaks of the \emph{<part of the thing>}, if necessary. We will consider the
example code given in \cref{lst:mlb4}, noting in particular the positions of
- the line break highlighters, $\BeginStartsOnOwnLine$, $\BodyStartsOnOwnLine$, $\EndStartsOnOwnLine$
- and $\EndFinishesWithLineBreak$, together with the associated YAML files in \crefrange{lst:env-mlb13}{lst:env-mlb16}.
+ the line break highlighters, $\BeginStartsOnOwnLine$, $\BodyStartsOnOwnLine$,
+ $\EndStartsOnOwnLine$ and $\EndFinishesWithLineBreak$, together with the associated
+ YAML files in \crefrange{lst:env-mlb13}{lst:env-mlb16}.
\begin{minipage}{.45\linewidth}
\begin{cmhlistings}[style=tcblatex,escapeinside={(*@}{@*)}]{\texttt{env-mlb4.tex}}{lst:mlb4}
@@ -898,14 +1266,19 @@
Notice that in:
\begin{itemize}
- \item \cref{lst:env-mlb4-mod13} the line break denoted by $\BeginStartsOnOwnLine$ in \cref{lst:mlb4} has been removed;
- \item \cref{lst:env-mlb4-mod14} the line break denoted by $\BodyStartsOnOwnLine$ in \cref{lst:mlb4} has been removed;
- \item \cref{lst:env-mlb4-mod15} the line break denoted by $\EndStartsOnOwnLine$ in \cref{lst:mlb4} has been removed;
- \item \cref{lst:env-mlb4-mod16} the line break denoted by $\EndFinishesWithLineBreak$ in \cref{lst:mlb4} has been removed.
+ \item \cref{lst:env-mlb4-mod13} the line break denoted by $\BeginStartsOnOwnLine$ in
+ \cref{lst:mlb4} has been removed;
+ \item \cref{lst:env-mlb4-mod14} the line break denoted by $\BodyStartsOnOwnLine$ in
+ \cref{lst:mlb4} has been removed;
+ \item \cref{lst:env-mlb4-mod15} the line break denoted by $\EndStartsOnOwnLine$ in
+ \cref{lst:mlb4} has been removed;
+ \item \cref{lst:env-mlb4-mod16} the line break denoted by $\EndFinishesWithLineBreak$ in
+ \cref{lst:mlb4} has been removed.
\end{itemize}
- We examined each of these cases separately for clarity of explanation, but you can combine all of the YAML
- settings in \crefrange{lst:env-mlb13}{lst:env-mlb16} into one file; alternatively, you could tell \texttt{latexindent.pl}
- to load them all by using the following command, for example
+ We examined each of these cases separately for clarity of explanation, but you can
+ combine all of the YAML settings in \crefrange{lst:env-mlb13}{lst:env-mlb16} into one file;
+ alternatively, you could tell \texttt{latexindent.pl} to load them all by using the
+ following command, for example
\begin{widepage}
\begin{commandshell}
latexindent.pl -m env-mlb4.tex -l env-mlb13.yaml,env-mlb14.yaml,env-mlb15.yaml,env-mlb16.yaml
@@ -914,10 +1287,12 @@
which gives the output in \vref{lst:env-mlb1-tex}.
\subsubsection{About trailing horizontal space}
- Recall that on \cpageref{yaml:removeTrailingWhitespace} we discussed the YAML field \texttt{removeTrailingWhitespace},
- and that it has two (binary) switches to determine if horizontal space should be removed \texttt{beforeProcessing} and \texttt{afterProcessing}.
- The \texttt{beforeProcessing} is particularly relevant when considering the \texttt{-m} switch; let's consider the
- file shown in \cref{lst:mlb5}, which highlights trailing spaces.
+ Recall that on \cpageref{yaml:removeTrailingWhitespace} we discussed the YAML field
+ \texttt{removeTrailingWhitespace}, and that it has two (binary) switches to determine if
+ horizontal space should be removed \texttt{beforeProcessing} and
+ \texttt{afterProcessing}. The \texttt{beforeProcessing} is particularly relevant
+ when considering the \texttt{-m} switch; let's consider the file shown in
+ \cref{lst:mlb5}, which highlights trailing spaces.
\begin{minipage}{.45\linewidth}
\begin{cmhlistings}[style=tcblatex,showspaces=true,escapeinside={(*@}{@*)}]{\texttt{env-mlb5.tex}}{lst:mlb5}
@@ -940,9 +1315,10 @@
latexindent.pl -m env-mlb5.tex -l env-mlb13.yaml,env-mlb14.yaml,env-mlb15.yaml,env-mlb16.yaml,removeTWS-before.yaml
\end{commandshell}
\end{widepage}
- is shown, respectively, in \cref{lst:env-mlb5-modAll,lst:env-mlb5-modAll-remove-WS}; note that
- the trailing horizontal white space has been preserved (by default) in \cref{lst:env-mlb5-modAll}, while
- in \cref{lst:env-mlb5-modAll-remove-WS}, it has been removed using the switch specified in \cref{lst:removeTWS-before}.
+ is shown, respectively, in \cref{lst:env-mlb5-modAll,lst:env-mlb5-modAll-remove-WS}; note that the trailing horizontal
+ white space has been preserved (by default) in \cref{lst:env-mlb5-modAll}, while in
+ \cref{lst:env-mlb5-modAll-remove-WS}, it has been removed using the switch specified in
+ \cref{lst:removeTWS-before}.
\begin{widepage}
\cmhlistingsfromfile[showspaces=true]{demonstrations/env-mlb5-modAll.tex}{\texttt{env-mlb5.tex} using \crefrange{lst:env-mlb4-mod13}{lst:env-mlb4-mod16}}{lst:env-mlb5-modAll}
@@ -982,10 +1358,12 @@
\end{commandshell}
\end{widepage}
we receive the respective outputs in \cref{lst:env-mlb6-modAll,lst:env-mlb6-modAll-un-Preserve-Blank-Lines}. In
- \cref{lst:env-mlb6-modAll} we see that the multiple blank lines have each been condensed into one blank line,
- but that blank lines have \emph{not} been removed by the poly-switches -- this is because, by default, \texttt{preserveBlankLines}
- is set to \texttt{1}. By contrast, in \cref{lst:env-mlb6-modAll-un-Preserve-Blank-Lines}, we have allowed
- the poly-switches to remove blank lines because, in \cref{lst:UnpreserveBlankLines}, we have set \texttt{preserveBlankLines} to \texttt{0}.
+ \cref{lst:env-mlb6-modAll} we see that the multiple blank lines have each been condensed
+ into one blank line, but that blank lines have \emph{not} been removed
+ by the poly-switches -- this is because, by default, \texttt{preserveBlankLines} is set
+ to \texttt{1}. By contrast, in \cref{lst:env-mlb6-modAll-un-Preserve-Blank-Lines}, we have
+ allowed the poly-switches to remove blank lines because, in \cref{lst:UnpreserveBlankLines},
+ we have set \texttt{preserveBlankLines} to \texttt{0}.
\begin{widepage}
\begin{minipage}{.30\linewidth}
@@ -997,8 +1375,8 @@
\end{minipage}
\end{widepage}
- We can explore this further using the blank-line poly-switch value of $3$; let's use the file given
- in \cref{lst:env-mlb7-tex}.
+ We can explore this further using the blank-line poly-switch value of
+ $3$; let's use the file given in \cref{lst:env-mlb7-tex}.
\cmhlistingsfromfile{demonstrations/env-mlb7.tex}{\texttt{env-mlb7.tex}}{lst:env-mlb7-tex}
@@ -1014,18 +1392,24 @@
Notice that in:
\begin{itemize}
- \item \cref{lst:env-mlb7-preserve} that \lstinline!\end{one}! has added a blank line, because of the value of
- \texttt{EndFinishesWithLineBreak} in \vref{lst:env-mlb12}, and even though the line break ahead of \lstinline!\begin{two}! should have been removed
- (because of \texttt{BeginStartsOnOwnLine} in \vref{lst:env-mlb13}), the blank line has been preserved by default;
- \item \cref{lst:env-mlb7-no-preserve}, by contrast, has had the additional line-break removed, because of
- the settings in \cref{lst:UnpreserveBlankLines}.
+ \item \cref{lst:env-mlb7-preserve} that \lstinline!\end{one}! has added a blank line,
+ because of the value of \texttt{EndFinishesWithLineBreak} in \vref{lst:env-mlb12}, and
+ even though the line break ahead of \lstinline!\begin{two}! should have been removed
+ (because of \texttt{BeginStartsOnOwnLine} in \vref{lst:env-mlb13}), the blank line
+ has been preserved by default;
+ \item \cref{lst:env-mlb7-no-preserve}, by contrast, has had the additional line-break removed,
+ because of the settings in \cref{lst:UnpreserveBlankLines}.
\end{itemize}
\subsection{Poly-switches for other code blocks}
- Rather than repeat the examples shown for the environment code blocks (in \vref{sec:modifylinebreaks-environments}), we choose to detail the poly-switches for
- all other code blocks in \cref{tab:poly-switch-mapping}; note that each and every one of these poly-switches is \emph{off by default}, i.e, set to \texttt{0}. Note also that,
- by design, line breaks involving \texttt{verbatim}, \texttt{filecontents} and `comment-marked' code blocks (\vref{lst:alignmentmarkup}) can \emph{not} be
- modified using \texttt{latexindent.pl}.
+ Rather than repeat the examples shown for the environment code blocks (in
+ \vref{sec:modifylinebreaks-environments}), we choose to detail the poly-switches for all other code
+ blocks in \cref{tab:poly-switch-mapping}; note that each and every one of these
+ poly-switches is \emph{off by default}, i.e, set to \texttt{0}.
+ Note also that, by design, line breaks involving \texttt{verbatim},
+ \texttt{filecontents} and `comment-marked' code blocks
+ (\vref{lst:alignmentmarkup}) can \emph{not} be modified using
+ \texttt{latexindent.pl}.
\begin{longtable}{llll}
\caption{Poly-switch mappings for all code-block types}\label{tab:poly-switch-mapping} \\
@@ -1041,7 +1425,7 @@
ifelsefi & \verb!before words!$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & IfStartsOnOwnLine \\
& \verb!\if...!$\BodyStartsOnOwnLine$ & $\BodyStartsOnOwnLine$ & BodyStartsOnOwnLine \\
& \verb!body of if/or statement!$\OrStartsOnOwnLine$ & $\OrStartsOnOwnLine$ & OrStartsOnOwnLine %
- \announce*{2018-04-27}{new ifElseFi code block polyswitches} \\
+ \announce{2018-04-27}{new ifElseFi code block polyswitches} \\
& \verb!\or!$\OrFinishesWithLineBreak$ & $\OrFinishesWithLineBreak$ & OrFinishesWithLineBreak \\
& \verb!body of if/or statement!$\ElseStartsOnOwnLine$ & $\ElseStartsOnOwnLine$ & ElseStartsOnOwnLine \\
& \verb!\else!$\ElseFinishesWithLineBreak$ & $\ElseFinishesWithLineBreak$ & ElseFinishesWithLineBreak \\
@@ -1080,7 +1464,7 @@
specialBeginEnd & before words$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & SpecialBeginStartsOnOwnLine \\
& \verb!\[!$\BodyStartsOnOwnLine$ & $\BodyStartsOnOwnLine$ & SpecialBodyStartsOnOwnLine \\
& \verb!body of special/middle!$\ElseStartsOnOwnLine$ & $\ElseStartsOnOwnLine$ & SpecialMiddleStartsOnOwnLine %
- \announce*{2018-04-27}{new special code block polyswitches} \\
+ \announce{2018-04-27}{new special code block polyswitches} \\
& \verb!\middle!$\ElseFinishesWithLineBreak$ & $\ElseFinishesWithLineBreak$ & SpecialMiddleFinishesWithLineBreak \\
& body of special/middle $\EndStartsOnOwnLine$ & $\EndStartsOnOwnLine$ & SpecialEndStartsOnOwnLine \\
& \verb!\]!$\EndFinishesWithLineBreak$ & $\EndFinishesWithLineBreak$ & SpecialEndFinishesWithLineBreak \\
Modified: trunk/Master/texmf-dist/doc/support/latexindent/subsec-commands-and-their-options.tex
===================================================================
--- trunk/Master/texmf-dist/doc/support/latexindent/subsec-commands-and-their-options.tex 2018-08-14 22:01:02 UTC (rev 48401)
+++ trunk/Master/texmf-dist/doc/support/latexindent/subsec-commands-and-their-options.tex 2018-08-14 22:01:47 UTC (rev 48402)
@@ -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 @@
\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 @@
\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 @@
\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 @@
\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,56 +145,63 @@
\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}
@@ -185,27 +208,33 @@
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,15 +244,17 @@
\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}
@@ -230,11 +261,12 @@
\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}.
Modified: trunk/Master/texmf-dist/doc/support/latexindent/subsec-conflicting-poly-switches.tex
===================================================================
--- trunk/Master/texmf-dist/doc/support/latexindent/subsec-conflicting-poly-switches.tex 2018-08-14 22:01:02 UTC (rev 48401)
+++ trunk/Master/texmf-dist/doc/support/latexindent/subsec-conflicting-poly-switches.tex 2018-08-14 22:01:47 UTC (rev 48402)
@@ -1,7 +1,8 @@
% arara: pdflatex: {shell: yes, files: [latexindent]}
\subsection{Conflicting poly-switches: sequential code blocks}
- It is very easy to have conflicting poly-switches; if we use the example from \vref{lst:mycommand1},
- and consider the YAML settings given in \cref{lst:mycom-mlb4}. The output from running
+ It is very easy to have conflicting poly-switches; if we use the example from
+ \vref{lst:mycommand1}, and consider the YAML settings given in \cref{lst:mycom-mlb4}.
+ The output from running
\begin{commandshell}
latexindent.pl -m -l=mycom-mlb4.yaml mycommand1.tex
\end{commandshell}
@@ -15,16 +16,20 @@
\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/mycom-mlb4.yaml}[MLB-TCB,width=\linewidth]{\texttt{mycom-mlb4.yaml}}{lst:mycom-mlb4}
\end{minipage}
- Studying \cref{lst:mycom-mlb4}, we see that the two poly-switches are at opposition with one another:
+ Studying \cref{lst:mycom-mlb4}, we see that the two poly-switches are at opposition with
+ one another:
\begin{itemize}
- \item on the one hand, \texttt{LCuBStartsOnOwnLine} should \emph{not} start on its own line (as poly-switch is set to $-1$);
+ \item on the one hand, \texttt{LCuBStartsOnOwnLine} should \emph{not} start on its own line
+ (as poly-switch is set to $-1$);
\item on the other hand, \texttt{RCuBFinishesWithLineBreak} \emph{should} finish with a line break.
\end{itemize}
- So, which should win the conflict? As demonstrated in \cref{lst:mycommand1-mlb4}, it is clear that \texttt{LCuBStartsOnOwnLine} won
- this conflict, and the reason is that \emph{the second argument was processed after the first} -- in general, the most recently-processed
- code block and associated poly-switch takes priority.
+ So, which should win the conflict? As demonstrated in \cref{lst:mycommand1-mlb4}, it is clear
+ that \texttt{LCuBStartsOnOwnLine} won this conflict, and the reason is that
+ \emph{the second argument was processed after the first} -- in general, the most recently-processed code block and
+ associated poly-switch takes priority.
- We can explore this further by considering the YAML settings in \cref{lst:mycom-mlb5}; upon running the command
+ We can explore this further by considering the YAML settings in \cref{lst:mycom-mlb5};
+ upon running the command
\begin{commandshell}
latexindent.pl -m -l=mycom-mlb5.yaml mycommand1.tex
\end{commandshell}
@@ -38,8 +43,10 @@
\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/mycom-mlb5.yaml}[MLB-TCB,width=\linewidth]{\texttt{mycom-mlb5.yaml}}{lst:mycom-mlb5}
\end{minipage}
- As previously, the most-recently-processed code block takes priority -- as before, the second (i.e, \emph{last}) argument. Exploring this
- further, we consider the YAML settings in \cref{lst:mycom-mlb6}, which give associated output in \cref{lst:mycommand1-mlb6}.
+ As previously, the most-recently-processed code block takes priority -- as before, the
+ second (i.e, \emph{last}) argument. Exploring this further, we consider the
+ YAML settings in \cref{lst:mycom-mlb6}, which give associated output in
+ \cref{lst:mycommand1-mlb6}.
\begin{minipage}{.4\linewidth}
\cmhlistingsfromfile{demonstrations/mycommand1-mlb6.tex}{\texttt{mycommand1.tex} using \cref{lst:mycom-mlb6}}{lst:mycommand1-mlb6}
@@ -49,20 +56,26 @@
\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/mycom-mlb6.yaml}[MLB-TCB,width=\linewidth]{\texttt{mycom-mlb6.yaml}}{lst:mycom-mlb6}
\end{minipage}
- Note that a \lstinline!%! \emph{has} been added to the trailing first \lstinline!}!; this is because:
+ Note that a \lstinline!%! \emph{has} been added to the trailing
+ first \lstinline!}!; this is because:
\begin{itemize}
- \item while processing the \emph{first} argument, the trailing line break has been removed (\texttt{RCuBFinishesWithLineBreak} set to $-1$);
- \item while processing the \emph{second} argument, \texttt{latexindent.pl} finds that it does \emph{not} begin on its own line, and so
- because \texttt{LCuBStartsOnOwnLine} is set to $2$, it adds a comment, followed by a line break.
+ \item while processing the \emph{first} argument, the trailing line break has been
+ removed (\texttt{RCuBFinishesWithLineBreak} set to $-1$);
+ \item while processing the \emph{second} argument, \texttt{latexindent.pl} finds that
+ it does \emph{not} begin on its own line, and so because
+ \texttt{LCuBStartsOnOwnLine} is set to $2$, it adds a comment, followed by a
+ line break.
\end{itemize}
\subsection{Conflicting poly-switches: nested code blocks}
- Now let's consider an example when nested code blocks have conflicting poly-switches; we'll use the code in \cref{lst:nested-env},
- noting that it contains nested environments.
+ Now let's consider an example when nested code blocks have conflicting poly-switches;
+ we'll use the code in \cref{lst:nested-env}, noting that it contains nested
+ environments.
\cmhlistingsfromfile{demonstrations/nested-env.tex}{\texttt{nested-env.tex}}{lst:nested-env}
- Let's use the YAML settings given in \cref{lst:nested-env-mlb1-yaml}, which upon running the command
+ Let's use the YAML settings given in \cref{lst:nested-env-mlb1-yaml}, which upon running the
+ command
\begin{commandshell}
latexindent.pl -m -l=nested-env-mlb1.yaml nested-env.tex
\end{commandshell}
@@ -76,41 +89,61 @@
\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/nested-env-mlb1.yaml}[MLB-TCB,width=\linewidth]{\texttt{nested-env-mlb1.yaml}}{lst:nested-env-mlb1-yaml}
\end{minipage}
- In \cref{lst:nested-env-mlb1}, let's first of all note that both environments have received the appropriate (default) indentation; secondly,
- note that the poly-switch \texttt{EndStartsOnOwnLine} appears to have won the conflict, as \lstinline!\end{one}! has had its leading line break removed.
+ In \cref{lst:nested-env-mlb1}, let's first of all note that both environments have received
+ the appropriate (default) indentation; secondly, note that the poly-switch
+ \texttt{EndStartsOnOwnLine} appears to have won the conflict, as \lstinline!\end{one}! has
+ had its leading line break removed.
- To understand it, let's talk about the three basic phases \label{page:phases}of \texttt{latexindent.pl}:
+ To understand it, let's talk about the three basic phases \label{page:phases}of
+ \texttt{latexindent.pl}:
\begin{enumerate}
- \item Phase 1: packing, in which code blocks are replaced with unique ids, working from \emph{the inside to the outside}, and then sequentially -- for example, in
- \cref{lst:nested-env}, the \texttt{two} environment is found \emph{before} the \texttt{one} environment; if the -m switch is active, then during this phase:
+ \item Phase 1: packing, in which code blocks are replaced with unique ids, working from
+ \emph{the inside to the outside}, and then sequentially -- for example, in \cref{lst:nested-env},
+ the \texttt{two} environment is found \emph{before} the
+ \texttt{one} environment; if the -m switch is active, then during this phase:
\begin{itemize}
- \item line breaks at the beginning of the \texttt{body} can be added (if \texttt{BodyStartsOnOwnLine} is $1$ or $2$) or removed (if \texttt{BodyStartsOnOwnLine} is $-1$);
- \item line breaks at the end of the body can be added (if \texttt{EndStartsOnOwnLine} is $1$ or $2$) or removed (if \texttt{EndStartsOnOwnLine} is $-1$);
- \item line breaks after the end statement can be added (if \texttt{EndFinishesWithLineBreak} is $1$ or $2$).
+ \item line breaks at the beginning of the \texttt{body} can be added (if
+ \texttt{BodyStartsOnOwnLine} is $1$ or $2$) or removed (if
+ \texttt{BodyStartsOnOwnLine} is $-1$);
+ \item line breaks at the end of the body can be added (if \texttt{EndStartsOnOwnLine} is
+ $1$ or $2$) or removed (if \texttt{EndStartsOnOwnLine} is
+ $-1$);
+ \item line breaks after the end statement can be added (if \texttt{EndFinishesWithLineBreak} is
+ $1$ or $2$).
\end{itemize}
- \item Phase 2: indentation, in which white space is added to the begin, body, and end statements;
- \item Phase 3: unpacking, in which unique ids are replaced by their \emph{indented} code blocks; if the -m switch is active, then during this phase,
+ \item Phase 2: indentation, in which white space is added to the begin, body, and end
+ statements;
+ \item Phase 3: unpacking, in which unique ids are replaced by their \emph{indented} code
+ blocks; if the -m switch is active, then during this phase,
\begin{itemize}
- \item line breaks before \texttt{begin} statements can be added or removed (depending upon \texttt{BeginStartsOnOwnLine});
- \item line breaks after \emph{end} statements can be removed but \emph{NOT} added (see \texttt{EndFinishesWithLineBreak}).
+ \item line breaks before \texttt{begin} statements can be added or removed (depending
+ upon \texttt{BeginStartsOnOwnLine});
+ \item line breaks after \emph{end} statements can be removed but
+ \emph{NOT} added (see \texttt{EndFinishesWithLineBreak}).
\end{itemize}
\end{enumerate}
With reference to \cref{lst:nested-env-mlb1}, this means that during Phase 1:
\begin{itemize}
- \item the \texttt{two} environment is found first, and
- the line break ahead of the \lstinline!\end{two}! statement is removed because \texttt{EndStartsOnOwnLine} is set to $-1$. Importantly,
- because, \emph{at this stage}, \lstinline!\end{two}! \emph{does} finish with a line break, \texttt{EndFinishesWithLineBreak} causes
- no action.
- \item next, the \texttt{one} environment is found; the line break ahead of \lstinline!\end{one}! is removed because \texttt{EndStartsOnOwnLine}
- is set to $-1$.
+ \item the \texttt{two} environment is found first, and the line break ahead of the
+ \lstinline!\end{two}! statement is removed because \texttt{EndStartsOnOwnLine} is set to
+ $-1$. Importantly, because, \emph{at this stage},
+ \lstinline!\end{two}! \emph{does} finish with a line break,
+ \texttt{EndFinishesWithLineBreak} causes no action.
+ \item next, the \texttt{one} environment is found; the line break ahead of
+ \lstinline!\end{one}! is removed because \texttt{EndStartsOnOwnLine} is set to
+ $-1$.
\end{itemize}
- The indentation is done in Phase 2; in Phase 3 \emph{there is no option to add a line break after the \lstinline!end! statements}.
- We can justify this by remembering that during Phase 3, the \texttt{one} environment will be found and processed first, followed
- by the \texttt{two} environment. If the \texttt{two} environment were to add a line break after the \lstinline!\end{two}! statement, then
- \texttt{latexindent.pl} would have no way of knowing how much indentation to add to the subsequent text (in this case, \lstinline!\end{one}!).
+ The indentation is done in Phase 2; in Phase 3 \emph{there is no option to add a line break after the \lstinline!end! statements}. We can justify
+ this by remembering that during Phase 3, the \texttt{one} environment will be
+ found and processed first, followed by the \texttt{two} environment. If the
+ \texttt{two} environment were to add a line break after the
+ \lstinline!\end{two}! statement, then \texttt{latexindent.pl} would have no way of
+ knowing how much indentation to add to the subsequent text (in this case,
+ \lstinline!\end{one}!).
- We can explore this further using the poly-switches in \cref{lst:nested-env-mlb2}; upon running the command
+ We can explore this further using the poly-switches in \cref{lst:nested-env-mlb2}; upon
+ running the command
\begin{commandshell}
latexindent.pl -m -l=nested-env-mlb2.yaml nested-env.tex
\end{commandshell}
@@ -126,12 +159,17 @@
During Phase 1:
\begin{itemize}
- \item the \texttt{two} environment is found first, and
- the line break ahead of the \lstinline!\end{two}! statement is not changed because \texttt{EndStartsOnOwnLine} is set to $1$.
- Importantly, because, \emph{at this stage}, \lstinline!\end{two}! \emph{does} finish with a line break, \texttt{EndFinishesWithLineBreak} causes
- no action.
- \item next, the \texttt{one} environment is found; the line break ahead of \lstinline!\end{one}! is already present, and no action is needed.
+ \item the \texttt{two} environment is found first, and the line break ahead of the
+ \lstinline!\end{two}! statement is not changed because \texttt{EndStartsOnOwnLine} is set to
+ $1$. Importantly, because, \emph{at this stage},
+ \lstinline!\end{two}! \emph{does} finish with a line break,
+ \texttt{EndFinishesWithLineBreak} causes no action.
+ \item next, the \texttt{one} environment is found; the line break ahead of
+ \lstinline!\end{one}! is already present, and no action is needed.
\end{itemize}
- The indentation is done in Phase 2, and then in Phase 3, the \texttt{one} environment is found and processed first, followed by
- the \texttt{two} environment. \emph{At this stage}, the \texttt{two} environment finds \texttt{EndFinishesWithLineBreak} is $-1$, so it removes
- the trailing line break; remember, at this point, \texttt{latexindent.pl} has completely finished with the \texttt{one} environment.
+ The indentation is done in Phase 2, and then in Phase 3, the \texttt{one}
+ environment is found and processed first, followed by the \texttt{two}
+ environment. \emph{At this stage}, the \texttt{two} environment finds
+ \texttt{EndFinishesWithLineBreak} is $-1$, so it removes the trailing line break;
+ remember, at this point, \texttt{latexindent.pl} has completely finished with the
+ \texttt{one} environment.
Modified: trunk/Master/texmf-dist/doc/support/latexindent/subsec-noAdditionalIndent-indentRules.tex
===================================================================
--- trunk/Master/texmf-dist/doc/support/latexindent/subsec-noAdditionalIndent-indentRules.tex 2018-08-14 22:01:02 UTC (rev 48401)
+++ trunk/Master/texmf-dist/doc/support/latexindent/subsec-noAdditionalIndent-indentRules.tex 2018-08-14 22:01:47 UTC (rev 48402)
@@ -1,24 +1,27 @@
% arara: pdflatex: {shell: yes, files: [latexindent]}
% arara: pdflatex: {shell: yes, files: [latexindent]}
\subsection{noAdditionalIndent and indentRules}\label{sec:noadd-indent-rules}
- \texttt{latexindent.pl} operates on files by looking for code blocks, as detailed in \vref{subsubsec:code-blocks};
- for each type of code block in \vref{tab:code-blocks} (which we will call a \emph{$\langle$thing$\rangle$} in what follows)
- it searches YAML fields for information in the following order:
+ \texttt{latexindent.pl} operates on files by looking for code blocks, as detailed in
+ \vref{subsubsec:code-blocks};
+ for each type of code block in \vref{tab:code-blocks} (which we will call a \emph{$\langle$thing$\rangle$} in what follows) it searches YAML fields for
+ information in the following order:
\begin{enumerate}
\item \texttt{noAdditionalIndent} for the \emph{name} of the current \emph{$\langle$thing$\rangle$};
\item \texttt{indentRules} for the \emph{name} of the current \emph{$\langle$thing$\rangle$};
\item \texttt{noAdditionalIndentGlobal} for the \emph{type} of the current \emph{$\langle$thing$\rangle$};
- \item \texttt{indentRulesGlobal} for the \emph{type} of the current \emph{$\langle$thing$\rangle$}.
+ \item \texttt{indentRulesGlobal} for the \emph{type} of the current
+ \emph{$\langle$thing$\rangle$}.
\end{enumerate}
- Using the above list, the first piece of information to be found will be used; failing that,
- the value of \texttt{defaultIndent} is used.
- If information is found in multiple fields, the first one according to the list above will be used; for example,
- if information is present in both \texttt{indentRules} and in \texttt{noAdditionalIndentGlobal}, then the information from \texttt{indentRules}
- takes priority.
+ Using the above list, the first piece of information to be found will be used; failing
+ that, the value of \texttt{defaultIndent} is used. If information is found in multiple
+ fields, the first one according to the list above will be used; for example, if
+ information is present in both \texttt{indentRules} and in \texttt{noAdditionalIndentGlobal}, then
+ the information from \texttt{indentRules} takes priority.
- We now present details for the different type of code blocks known to \texttt{latexindent.pl}, as detailed in \vref{tab:code-blocks}; for
- reference, there follows a list of the code blocks covered.
+ We now present details for the different type of code blocks known to
+ \texttt{latexindent.pl}, as detailed in \vref{tab:code-blocks}; for reference, there
+ follows a list of the code blocks covered.
\startcontents[noAdditionalIndent]
\printcontents[noAdditionalIndent]{}{0}{}
Modified: trunk/Master/texmf-dist/doc/support/latexindent/subsec-partnering-poly-switches.tex
===================================================================
--- trunk/Master/texmf-dist/doc/support/latexindent/subsec-partnering-poly-switches.tex 2018-08-14 22:01:02 UTC (rev 48401)
+++ trunk/Master/texmf-dist/doc/support/latexindent/subsec-partnering-poly-switches.tex 2018-08-14 22:01:47 UTC (rev 48402)
@@ -1,11 +1,13 @@
% arara: pdflatex: {shell: yes, files: [latexindent]}
\subsection{Partnering BodyStartsOnOwnLine with argument-based poly-switches}
- Some poly-switches need to be partnered together; in particular, when line breaks involving the \emph{first} argument
- of a code block need to be accounted for using both \texttt{BodyStartsOnOwnLine} (or its equivalent, see \vref{tab:poly-switch-mapping})
- and \texttt{LCuBStartsOnOwnLine} for mandatory arguments, and \texttt{LSqBStartsOnOwnLine} for optional arguments.
+ Some poly-switches need to be partnered together; in particular, when line breaks
+ involving the \emph{first} argument of a code block need to be accounted for
+ using both \texttt{BodyStartsOnOwnLine} (or its equivalent, see \vref{tab:poly-switch-mapping}) and \texttt{LCuBStartsOnOwnLine} for mandatory arguments, and
+ \texttt{LSqBStartsOnOwnLine} for optional arguments.
- Let's begin with the code in \cref{lst:mycommand1} and the YAML settings in \cref{lst:mycom-mlb1}; with reference
- to \vref{tab:poly-switch-mapping}, the key \texttt{CommandNameFinishesWithLineBreak} is an alias for \texttt{BodyStartsOnOwnLine}.
+ Let's begin with the code in \cref{lst:mycommand1} and the YAML settings in
+ \cref{lst:mycom-mlb1}; with reference to \vref{tab:poly-switch-mapping}, the key
+ \texttt{CommandNameFinishesWithLineBreak} is an alias for \texttt{BodyStartsOnOwnLine}.
\cmhlistingsfromfile{demonstrations/mycommand1.tex}{\texttt{mycommand1.tex}}{lst:mycommand1}
@@ -13,8 +15,9 @@
\begin{commandshell}
latexindent.pl -m -l=mycom-mlb1.yaml mycommand1.tex
\end{commandshell}
- we obtain \cref{lst:mycommand1-mlb1}; note that the \emph{second} mandatory argument beginning brace \lstinline!{! has had
- its leading line break removed, but that the \emph{first} brace has not.
+ we obtain \cref{lst:mycommand1-mlb1}; note that the \emph{second} mandatory argument
+ beginning brace \lstinline!{! has had its leading line break removed, but that
+ the \emph{first} brace has not.
\begin{minipage}{.4\linewidth}
\cmhlistingsfromfile{demonstrations/mycommand1-mlb1.tex}{\texttt{mycommand1.tex} using \cref{lst:mycom-mlb1}}{lst:mycommand1-mlb1}
@@ -24,8 +27,9 @@
\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/mycom-mlb1.yaml}[MLB-TCB,width=\linewidth]{\texttt{mycom-mlb1.yaml}}{lst:mycom-mlb1}
\end{minipage}
- Now let's change the YAML file so that it is as in \cref{lst:mycom-mlb2}; upon running the analogous command to that given above,
- we obtain \cref{lst:mycommand1-mlb2}; both beginning braces \lstinline!{! have had their leading line breaks removed.
+ Now let's change the YAML file so that it is as in \cref{lst:mycom-mlb2}; upon running
+ the analogous command to that given above, we obtain \cref{lst:mycommand1-mlb2}; both
+ beginning braces \lstinline!{! have had their leading line breaks removed.
\begin{minipage}{.4\linewidth}
\cmhlistingsfromfile{demonstrations/mycommand1-mlb2.tex}{\texttt{mycommand1.tex} using \cref{lst:mycom-mlb2}}{lst:mycommand1-mlb2}
@@ -35,8 +39,8 @@
\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/mycom-mlb2.yaml}[MLB-TCB,width=\linewidth]{\texttt{mycom-mlb2.yaml}}{lst:mycom-mlb2}
\end{minipage}
- Now let's change the YAML file so that it is as in \cref{lst:mycom-mlb3}; upon running the analogous command to that given above,
- we obtain \cref{lst:mycommand1-mlb3}.
+ Now let's change the YAML file so that it is as in \cref{lst:mycom-mlb3}; upon running
+ the analogous command to that given above, we obtain \cref{lst:mycommand1-mlb3}.
\begin{minipage}{.4\linewidth}
\cmhlistingsfromfile{demonstrations/mycommand1-mlb3.tex}{\texttt{mycommand1.tex} using \cref{lst:mycom-mlb3}}{lst:mycommand1-mlb3}
Modified: trunk/Master/texmf-dist/doc/support/latexindent/subsubsec-commands-with-arguments.tex
===================================================================
--- trunk/Master/texmf-dist/doc/support/latexindent/subsubsec-commands-with-arguments.tex 2018-08-14 22:01:02 UTC (rev 48401)
+++ trunk/Master/texmf-dist/doc/support/latexindent/subsubsec-commands-with-arguments.tex 2018-08-14 22:01:47 UTC (rev 48402)
@@ -1,7 +1,8 @@
% arara: pdflatex: {shell: yes, files: [latexindent]}
\subsubsection{Commands with arguments}\label{subsubsec:commands-arguments}
- Let's begin with the simple example in \cref{lst:mycommand}; when \texttt{latexindent.pl} operates
- on this file, the default output is shown in \cref{lst:mycommand-default}. \footnote{The command code blocks
+ Let's begin with the simple example in \cref{lst:mycommand}; when
+ \texttt{latexindent.pl} operates on this file, the default output is shown in
+ \cref{lst:mycommand-default}. \footnote{The command code blocks
have quite a few subtleties, described in \vref{subsec:commands-string-between}.}
\begin{minipage}{.45\textwidth}
@@ -12,8 +13,9 @@
\cmhlistingsfromfile{demonstrations/mycommand-default.tex}{\texttt{mycommand.tex} default output}{lst:mycommand-default}
\end{minipage}
- As in the environment-based case (see \vref{lst:myenv-noAdd1,lst:myenv-noAdd2}) we may specify \texttt{noAdditionalIndent}
- either in `scalar' form, or in `field' form, as shown in \cref{lst:mycommand-noAdd1,lst:mycommand-noAdd2}
+ As in the environment-based case (see \vref{lst:myenv-noAdd1,lst:myenv-noAdd2}) we may specify
+ \texttt{noAdditionalIndent} either in `scalar' form, or in `field' form, as shown in
+ \cref{lst:mycommand-noAdd1,lst:mycommand-noAdd2}
\begin{minipage}{.45\textwidth}
\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/mycommand-noAdd1.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{mycommand-noAdd1.yaml}}{lst:mycommand-noAdd1}
@@ -38,12 +40,14 @@
\cmhlistingsfromfile{demonstrations/mycommand-noAdd2.tex}{\texttt{mycommand.tex} using \cref{lst:mycommand-noAdd2}}{lst:mycommand-output-noAdd2}
\end{minipage}
- Note that in \cref{lst:mycommand-output-noAdd1} that the `body', optional argument \emph{and} mandatory argument have \emph{all} received
- no additional indentation, while in \cref{lst:mycommand-output-noAdd2}, only the `body' has not received any additional indentation. We define
- the `body' of a command as any lines following the command name that include its optional or mandatory arguments.
+ Note that in \cref{lst:mycommand-output-noAdd1} that the `body', optional argument
+ \emph{and} mandatory argument have \emph{all} received no
+ additional indentation, while in \cref{lst:mycommand-output-noAdd2}, only the `body' has not received
+ any additional indentation. We define the `body' of a command as any lines following the
+ command name that include its optional or mandatory arguments.
- We may further customise \texttt{noAdditionalIndent} for \texttt{mycommand} as we did in \vref{lst:myenv-noAdd5,lst:myenv-noAdd6}; explicit examples
- are given in \cref{lst:mycommand-noAdd3,lst:mycommand-noAdd4}.
+ We may further customise \texttt{noAdditionalIndent} for \texttt{mycommand} as we did in
+ \vref{lst:myenv-noAdd5,lst:myenv-noAdd6}; explicit examples are given in \cref{lst:mycommand-noAdd3,lst:mycommand-noAdd4}.
\begin{minipage}{.45\textwidth}
\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/mycommand-noAdd3.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{mycommand-noAdd3.yaml}}{lst:mycommand-noAdd3}
@@ -68,9 +72,11 @@
\cmhlistingsfromfile{demonstrations/mycommand-noAdd4.tex}{\texttt{mycommand.tex} using \cref{lst:mycommand-noAdd4}}{lst:mycommand-output-noAdd4}
\end{minipage}
- Attentive readers will note that the body of \texttt{mycommand} in both \cref{lst:mycommand-output-noAdd3,lst:mycommand-output-noAdd4}
- has received no additional indent, even though \texttt{body} is explicitly set to \texttt{0} in both \cref{lst:mycommand-noAdd3,lst:mycommand-noAdd4}.
- This is because, by default, \texttt{noAdditionalIndentGlobal} for \texttt{commands} is set to \texttt{1} by default; this can be easily
+ Attentive readers will note that the body of \texttt{mycommand} in both
+ \cref{lst:mycommand-output-noAdd3,lst:mycommand-output-noAdd4} has received no additional indent, even though
+ \texttt{body} is explicitly set to \texttt{0} in both
+ \cref{lst:mycommand-noAdd3,lst:mycommand-noAdd4}. This is because, by default, \texttt{noAdditionalIndentGlobal} for
+ \texttt{commands} is set to \texttt{1} by default; this can be easily
fixed as in \cref{lst:mycommand-noAdd5,lst:mycommand-noAdd6}.\label{page:command:noAddGlobal}
\begin{minipage}{.45\textwidth}
@@ -96,5 +102,6 @@
\cmhlistingsfromfile{demonstrations/mycommand-noAdd6.tex}{\texttt{mycommand.tex} using \cref{lst:mycommand-noAdd6}}{lst:mycommand-output-noAdd6}
\end{minipage}
- Both \texttt{indentRules} and \texttt{indentRulesGlobal} can be adjusted as they were for \emph{environment} code blocks, as in
- \vref{lst:myenv-rules3,lst:myenv-rules4} and \vref{lst:indentRulesGlobal:environments,lst:opt-args-indent-rules-glob,lst:mand-args-indent-rules-glob}.
+ Both \texttt{indentRules} and \texttt{indentRulesGlobal} can be adjusted as they were for
+ \emph{environment} code blocks, as in \vref{lst:myenv-rules3,lst:myenv-rules4} and
+ \vref{lst:indentRulesGlobal:environments,lst:opt-args-indent-rules-glob,lst:mand-args-indent-rules-glob}.
Modified: trunk/Master/texmf-dist/doc/support/latexindent/subsubsec-environments-and-their-arguments.tex
===================================================================
--- trunk/Master/texmf-dist/doc/support/latexindent/subsubsec-environments-and-their-arguments.tex 2018-08-14 22:01:02 UTC (rev 48401)
+++ trunk/Master/texmf-dist/doc/support/latexindent/subsubsec-environments-and-their-arguments.tex 2018-08-14 22:01:47 UTC (rev 48402)
@@ -1,13 +1,13 @@
% arara: pdflatex: {shell: yes, files: [latexindent]}
\subsubsection{Environments and their arguments}\label{subsubsec:env-and-their-args}
- There are a few different YAML switches governing the indentation of environments; let's start
- with the code shown in \cref{lst:myenvtex}.
+ There are a few different YAML switches governing the indentation of environments; let's
+ start with the code shown in \cref{lst:myenvtex}.
\cmhlistingsfromfile{demonstrations/myenvironment-simple.tex}{\texttt{myenv.tex}}{lst:myenvtex}
\yamltitle{noAdditionalIndent}*{fields}
- If we do not wish \texttt{myenv} to receive any additional indentation, we have a few choices available to us,
- as demonstrated in \cref{lst:myenv-noAdd1,lst:myenv-noAdd2}.
+ If we do not wish \texttt{myenv} to receive any additional indentation, we have a
+ few choices available to us, as demonstrated in \cref{lst:myenv-noAdd1,lst:myenv-noAdd2}.
\begin{minipage}{.45\textwidth}
\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/myenv-noAdd1.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{myenv-noAdd1.yaml}}{lst:myenv-noAdd1}
@@ -22,8 +22,9 @@
latexindent.pl myenv.tex -l myenv-noAdd1.yaml
latexindent.pl myenv.tex -l myenv-noAdd2.yaml
\end{commandshell}
- we obtain the output given in \cref{lst:myenv-output}; note in particular that the environment \texttt{myenv}
- has not received any \emph{additional} indentation, but that the \texttt{outer} environment \emph{has} still
+ we obtain the output given in \cref{lst:myenv-output}; note in particular that the
+ environment \texttt{myenv} has not received any \emph{additional}
+ indentation, but that the \texttt{outer} environment \emph{has} still
received indentation.
\cmhlistingsfromfile{demonstrations/myenvironment-simple-noAdd-body1.tex}{\texttt{myenv.tex} output (using either \cref{lst:myenv-noAdd1} or \cref{lst:myenv-noAdd2})}{lst:myenv-output}
@@ -45,18 +46,20 @@
\cmhlistingsfromfile{demonstrations/myenvironment-simple-noAdd-body4.tex}{\texttt{myenv.tex output} (using either \cref{lst:myenv-noAdd3} or \cref{lst:myenv-noAdd4})}{lst:myenv-output-4}
- Let's now allow \texttt{myenv} to have some optional and mandatory arguments, as in \cref{lst:myenv-args}.
- \cmhlistingsfromfile{demonstrations/myenvironment-args.tex}{\texttt{myenv-args.tex}}{lst:myenv-args}
- Upon running
+ Let's now allow \texttt{myenv} to have some optional and mandatory arguments, as
+ in \cref{lst:myenv-args}. \cmhlistingsfromfile{demonstrations/myenvironment-args.tex}{\texttt{myenv-args.tex}}{lst:myenv-args} Upon running
\begin{commandshell}
latexindent.pl -l=myenv-noAdd1.yaml myenv-args.tex
\end{commandshell}
- we obtain the output shown in \cref{lst:myenv-args-noAdd1}; note that the optional argument, mandatory argument and body \emph{all}
- have received no additional indent. This is because, when \texttt{noAdditionalIndent} is specified in `scalar' form (as in \cref{lst:myenv-noAdd1}),
- then \emph{all} parts of the environment (body, optional and mandatory arguments) are assumed to want no additional indent.
+ we obtain the output shown in \cref{lst:myenv-args-noAdd1}; note that the optional argument,
+ mandatory argument and body \emph{all} have received no additional indent.
+ This is because, when \texttt{noAdditionalIndent} is specified in `scalar' form (as in
+ \cref{lst:myenv-noAdd1}), then \emph{all} parts of the environment (body,
+ optional and mandatory arguments) are assumed to want no additional indent.
\cmhlistingsfromfile{demonstrations/myenvironment-args-noAdd-body1.tex}{\texttt{myenv-args.tex} using \cref{lst:myenv-noAdd1}}{lst:myenv-args-noAdd1}
- We may customise \texttt{noAdditionalIndent} for optional and mandatory arguments of the \texttt{myenv} environment, as shown in, for example, \cref{lst:myenv-noAdd5,lst:myenv-noAdd6}.
+ We may customise \texttt{noAdditionalIndent} for optional and mandatory arguments of the
+ \texttt{myenv} environment, as shown in, for example, \cref{lst:myenv-noAdd5,lst:myenv-noAdd6}.
\begin{minipage}{.49\textwidth}
\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/myenv-noAdd5.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{myenv-noAdd5.yaml}}{lst:myenv-noAdd5}
@@ -71,9 +74,11 @@
latexindent.pl myenv.tex -l myenv-noAdd5.yaml
latexindent.pl myenv.tex -l myenv-noAdd6.yaml
\end{commandshell}
- we obtain the respective outputs given in \cref{lst:myenv-args-noAdd5,lst:myenv-args-noAdd6}. Note that in \cref{lst:myenv-args-noAdd5}
- the text for the \emph{optional} argument has not received any additional indentation, and that in \cref{lst:myenv-args-noAdd6} the
- \emph{mandatory} argument has not received any additional indentation; in both cases, the \emph{body} has not received any additional indentation.
+ we obtain the respective outputs given in \cref{lst:myenv-args-noAdd5,lst:myenv-args-noAdd6}. Note that in
+ \cref{lst:myenv-args-noAdd5} the text for the \emph{optional} argument has not
+ received any additional indentation, and that in \cref{lst:myenv-args-noAdd6} the
+ \emph{mandatory} argument has not received any additional indentation; in both
+ cases, the \emph{body} has not received any additional indentation.
\begin{minipage}{.45\textwidth}
\cmhlistingsfromfile{demonstrations/myenvironment-args-noAdd5.tex}{\texttt{myenv-args.tex} using \cref{lst:myenv-noAdd5}}{lst:myenv-args-noAdd5}
@@ -84,8 +89,8 @@
\end{minipage}
\yamltitle{indentRules}*{fields}
- We may also specify indentation rules for environment code blocks using the \texttt{indentRules} field; see, for example,
- \cref{lst:myenv-rules1,lst:myenv-rules2}.
+ We may also specify indentation rules for environment code blocks using the
+ \texttt{indentRules} field; see, for example, \cref{lst:myenv-rules1,lst:myenv-rules2}.
\begin{minipage}{.45\textwidth}
\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/myenv-rules1.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{myenv-rules1.yaml}}{lst:myenv-rules1}
@@ -100,22 +105,27 @@
latexindent.pl myenv.tex -l myenv-rules1.yaml
latexindent.pl myenv.tex -l myenv-rules2.yaml
\end{commandshell}
- we obtain the output given in \cref{lst:myenv-rules-output}; note in particular that the environment \texttt{myenv}
- has received one tab (from the \texttt{outer} environment) plus three spaces from \cref{lst:myenv-rules1} or \ref{lst:myenv-rules2}.
+ we obtain the output given in \cref{lst:myenv-rules-output}; note in particular that the
+ environment \texttt{myenv} has received one tab (from the
+ \texttt{outer} environment) plus three spaces from \cref{lst:myenv-rules1} or
+ \ref{lst:myenv-rules2}.
\cmhlistingsfromfile[showtabs=true,showspaces=true]{demonstrations/myenv-rules1.tex}{\texttt{myenv.tex} output (using either \cref{lst:myenv-rules1} or \cref{lst:myenv-rules2})}{lst:myenv-rules-output}
- If you specify a field in \texttt{indentRules} using anything other than horizontal space, it will be ignored.
+ If you specify a field in \texttt{indentRules} using anything other than horizontal
+ space, it will be ignored.
- Returning to the example in \cref{lst:myenv-args} that contains optional and mandatory arguments. Upon using \cref{lst:myenv-rules1} as in
+ Returning to the example in \cref{lst:myenv-args} that contains optional and mandatory
+ arguments. Upon using \cref{lst:myenv-rules1} as in
\begin{commandshell}
latexindent.pl myenv-args.tex -l=myenv-rules1.yaml
\end{commandshell}
- we obtain the output in \cref{lst:myenv-args-rules1}; note that the body, optional argument and mandatory argument of \texttt{myenv}
- have \emph{all} received the same customised indentation.
- \cmhlistingsfromfile[showtabs=true,showspaces=true]{demonstrations/myenvironment-args-rules1.tex}{\texttt{myenv-args.tex} using \cref{lst:myenv-rules1}}{lst:myenv-args-rules1}
+ we obtain the output in \cref{lst:myenv-args-rules1}; note that the body, optional argument
+ and mandatory argument of \texttt{myenv} have \emph{all} received
+ the same customised indentation. \cmhlistingsfromfile[showtabs=true,showspaces=true]{demonstrations/myenvironment-args-rules1.tex}{\texttt{myenv-args.tex} using \cref{lst:myenv-rules1}}{lst:myenv-args-rules1}
- You can specify different indentation rules for the different features using, for example, \cref{lst:myenv-rules3,lst:myenv-rules4}
+ You can specify different indentation rules for the different features using, for
+ example, \cref{lst:myenv-rules3,lst:myenv-rules4}
\begin{minipage}{.49\textwidth}
\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/myenv-rules3.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{myenv-rules3.yaml}}{lst:myenv-rules3}
@@ -142,20 +152,23 @@
\end{minipage}
\end{widepage}
- Note that in \cref{lst:myenv-args-rules3}, the optional argument has only received a single space of indentation, while the mandatory argument
- has received the default (tab) indentation; the environment body has received three spaces of indentation.
+ Note that in \cref{lst:myenv-args-rules3}, the optional argument has only received a single
+ space of indentation, while the mandatory argument has received the default (tab)
+ indentation; the environment body has received three spaces of indentation.
- In \cref{lst:myenv-args-rules4}, the optional argument has received the default (tab) indentation, the mandatory argument has received two tabs
- of indentation, and the body has received three spaces of indentation.
+ In \cref{lst:myenv-args-rules4}, the optional argument has received the default (tab)
+ indentation, the mandatory argument has received two tabs of indentation, and the body
+ has received three spaces of indentation.
\yamltitle{noAdditionalIndentGlobal}*{fields}
\begin{wrapfigure}[6]{r}[0pt]{7cm}
\cmhlistingsfromfile[style=noAdditionalIndentGlobalEnv]*{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{noAdditionalIndentGlobal}}{lst:noAdditionalIndentGlobal:environments}
\end{wrapfigure}
- Assuming that your environment name is not found within neither \texttt{noAdditionalIndent} nor \texttt{indentRules}, the next
- place that \texttt{latexindent.pl} will look is \texttt{noAdditionalIndentGlobal}, and in particular \emph{for the environments} key
- (see \cref{lst:noAdditionalIndentGlobal:environments}). Let's say that you change
- the value of \texttt{environments} to \texttt{1} in \cref{lst:noAdditionalIndentGlobal:environments}, and that you run
+ Assuming that your environment name is not found within neither \texttt{noAdditionalIndent}
+ nor \texttt{indentRules}, the next place that \texttt{latexindent.pl} will look is
+ \texttt{noAdditionalIndentGlobal}, and in particular \emph{for the environments} key (see
+ \cref{lst:noAdditionalIndentGlobal:environments}). Let's say that you change the value of \texttt{environments}
+ to \texttt{1} in \cref{lst:noAdditionalIndentGlobal:environments}, and that you run
\begin{widepage}
\begin{commandshell}
@@ -164,10 +177,13 @@
\end{commandshell}
\end{widepage}
- The respective output from these two commands are in \cref{lst:myenv-args-no-add-global1,lst:myenv-args-no-add-global2}; in \cref{lst:myenv-args-no-add-global1} notice that \emph{both}
- environments receive no additional indentation but that the arguments of \texttt{myenv} still \emph{do} receive indentation. In \cref{lst:myenv-args-no-add-global2}
- notice that the \emph{outer} environment does not receive additional indentation, but because of the settings from \texttt{myenv-rules1.yaml} (in \vref{lst:myenv-rules1}), the \texttt{myenv}
- environment still \emph{does} receive indentation.
+ The respective output from these two commands are in \cref{lst:myenv-args-no-add-global1,lst:myenv-args-no-add-global2}; in
+ \cref{lst:myenv-args-no-add-global1} notice that \emph{both} environments receive no
+ additional indentation but that the arguments of \texttt{myenv} still
+ \emph{do} receive indentation. In \cref{lst:myenv-args-no-add-global2} notice that the
+ \emph{outer} environment does not receive additional indentation, but because
+ of the settings from \texttt{myenv-rules1.yaml} (in \vref{lst:myenv-rules1}), the \texttt{myenv} environment
+ still \emph{does} receive indentation.
\begin{minipage}{.45\textwidth}
\cmhlistingsfromfile{demonstrations/myenvironment-args-rules1-noAddGlobal1.tex}{\texttt{myenv-args.tex} using \cref{lst:noAdditionalIndentGlobal:environments}}{lst:myenv-args-no-add-global1}
@@ -177,8 +193,8 @@
\cmhlistingsfromfile{demonstrations/myenvironment-args-rules1-noAddGlobal2.tex}{\texttt{myenv-args.tex} using \cref{lst:noAdditionalIndentGlobal:environments,lst:myenv-rules1}}{lst:myenv-args-no-add-global2}
\end{minipage}
- In fact, \texttt{noAdditionalIndentGlobal} also contains keys that control the indentation of optional and mandatory
- arguments; on referencing \cref{lst:opt-args-no-add-glob,lst:mand-args-no-add-glob}
+ In fact, \texttt{noAdditionalIndentGlobal} also contains keys that control the indentation of
+ optional and mandatory arguments; on referencing \cref{lst:opt-args-no-add-glob,lst:mand-args-no-add-glob}
\begin{minipage}{.49\textwidth}
\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/opt-args-no-add-glob.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{opt-args-no-add-glob.yaml}}{lst:opt-args-no-add-glob}
@@ -193,9 +209,10 @@
latexindent.pl myenv-args.tex -local opt-args-no-add-glob.yaml
latexindent.pl myenv-args.tex -local mand-args-no-add-glob.yaml
\end{commandshell}
- which produces the respective outputs given in \cref{lst:myenv-args-no-add-opt,lst:myenv-args-no-add-mand}. Notice that in \cref{lst:myenv-args-no-add-opt}
- the \emph{optional} argument has not received any additional indentation, and in \cref{lst:myenv-args-no-add-mand} the \emph{mandatory} argument
- has not received any additional indentation.
+ which produces the respective outputs given in \cref{lst:myenv-args-no-add-opt,lst:myenv-args-no-add-mand}. Notice that in
+ \cref{lst:myenv-args-no-add-opt} the \emph{optional} argument has not received any
+ additional indentation, and in \cref{lst:myenv-args-no-add-mand} the \emph{mandatory}
+ argument has not received any additional indentation.
\begin{minipage}{.45\textwidth}
\cmhlistingsfromfile{demonstrations/myenvironment-args-rules1-noAddGlobal3.tex}{\texttt{myenv-args.tex} using \cref{lst:opt-args-no-add-glob}}{lst:myenv-args-no-add-opt}
@@ -209,17 +226,21 @@
\begin{wrapfigure}[4]{r}[0pt]{7cm}
\cmhlistingsfromfile[style=indentRulesGlobalEnv]*{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{indentRulesGlobal}}{lst:indentRulesGlobal:environments}
\end{wrapfigure}
- The final check that \texttt{latexindent.pl} will make is to look for \texttt{indentRulesGlobal} as detailed in \cref{lst:indentRulesGlobal:environments}; if you change the \texttt{environments}
- field to anything involving horizontal space, say \lstinline!" "!, and then run the following commands
+ The final check that \texttt{latexindent.pl} will make is to look for
+ \texttt{indentRulesGlobal} as detailed in \cref{lst:indentRulesGlobal:environments}; if you change the
+ \texttt{environments} field to anything involving horizontal space, say
+ \lstinline!" "!, and then run the following commands
\begin{commandshell}
latexindent.pl myenv-args.tex -l env-indentRules.yaml
latexindent.pl myenv-args.tex -l myenv-rules1.yaml,env-indentRules.yaml
\end{commandshell}
- then the respective output is shown in \cref{lst:myenv-args-indent-rules-global1,lst:myenv-args-indent-rules-global2}. Note that
- in \cref{lst:myenv-args-indent-rules-global1}, both the environment blocks have received a single-space indentation, whereas in
- \cref{lst:myenv-args-indent-rules-global2} the \texttt{outer} environment has received single-space indentation (specified by \texttt{indentRulesGlobal}),
- but \texttt{myenv} has received \lstinline!" "!, as specified by the particular \texttt{indentRules} for \texttt{myenv} \vref{lst:myenv-rules1}.
+ then the respective output is shown in \cref{lst:myenv-args-indent-rules-global1,lst:myenv-args-indent-rules-global2}. Note that in
+ \cref{lst:myenv-args-indent-rules-global1}, both the environment blocks have received a single-space
+ indentation, whereas in \cref{lst:myenv-args-indent-rules-global2} the \texttt{outer} environment
+ has received single-space indentation (specified by \texttt{indentRulesGlobal}), but
+ \texttt{myenv} has received \lstinline!" "!, as specified by the
+ particular \texttt{indentRules} for \texttt{myenv} \vref{lst:myenv-rules1}.
\begin{minipage}{.45\textwidth}
\cmhlistingsfromfile[showspaces=true]{demonstrations/myenvironment-args-global-rules1.tex}{\texttt{myenv-args.tex} using \cref{lst:indentRulesGlobal:environments}}{lst:myenv-args-indent-rules-global1}
@@ -229,7 +250,8 @@
\cmhlistingsfromfile[showspaces=true]{demonstrations/myenvironment-args-global-rules2.tex}{\texttt{myenv-args.tex} using \cref{lst:myenv-rules1,lst:indentRulesGlobal:environments}}{lst:myenv-args-indent-rules-global2}
\end{minipage}
- You can specify \texttt{indentRulesGlobal} for both optional and mandatory arguments, as detailed in \cref{lst:opt-args-indent-rules-glob,lst:mand-args-indent-rules-glob}
+ You can specify \texttt{indentRulesGlobal} for both optional and mandatory arguments, as
+ detailed in \cref{lst:opt-args-indent-rules-glob,lst:mand-args-indent-rules-glob}
\begin{minipage}{.49\textwidth}
\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/opt-args-indent-rules-glob.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{opt-args-indent-rules-glob.yaml}}{lst:opt-args-indent-rules-glob}
@@ -244,9 +266,10 @@
latexindent.pl myenv-args.tex -local opt-args-indent-rules-glob.yaml
latexindent.pl myenv-args.tex -local mand-args-indent-rules-glob.yaml
\end{commandshell}
- we obtain the respective outputs in \cref{lst:myenv-args-indent-rules-global3,lst:myenv-args-indent-rules-global4}. Note that the \emph{optional}
- argument in \cref{lst:myenv-args-indent-rules-global3} has received two tabs worth of indentation, while the \emph{mandatory} argument has
- done so in \cref{lst:myenv-args-indent-rules-global4}.
+ we obtain the respective outputs in \cref{lst:myenv-args-indent-rules-global3,lst:myenv-args-indent-rules-global4}. Note that the
+ \emph{optional} argument in \cref{lst:myenv-args-indent-rules-global3} has received two tabs worth
+ of indentation, while the \emph{mandatory} argument has done so in
+ \cref{lst:myenv-args-indent-rules-global4}.
\begin{widepage}
\begin{minipage}{.55\textwidth}
Modified: trunk/Master/texmf-dist/doc/support/latexindent/subsubsec-environments-with-items.tex
===================================================================
--- trunk/Master/texmf-dist/doc/support/latexindent/subsubsec-environments-with-items.tex 2018-08-14 22:01:02 UTC (rev 48401)
+++ trunk/Master/texmf-dist/doc/support/latexindent/subsubsec-environments-with-items.tex 2018-08-14 22:01:47 UTC (rev 48402)
@@ -1,15 +1,15 @@
% arara: pdflatex: {shell: yes, files: [latexindent]}
\subsubsection{Environments with items}
- With reference to \vref{lst:indentafteritems,lst:itemNames}, some commands
- may contain \texttt{item} commands; for the purposes of this discussion,
- we will use the code from \vref{lst:itemsbefore}.
+ With reference to \vref{lst:indentafteritems,lst:itemNames}, some commands may contain
+ \texttt{item} commands; for the purposes of this discussion, we will use the
+ code from \vref{lst:itemsbefore}.
Assuming that you've populated \texttt{itemNames} with the name of your
- \texttt{item}, you can put the item name into \texttt{noAdditionalIndent}
- as in \cref{lst:item-noAdd1}, although a more efficient approach may be
- to change the relevant field in \texttt{itemNames} to \texttt{0}. Similarly,
- you can customise the indentation that your \texttt{item} receives using
- \texttt{indentRules}, as in \cref{lst:item-rules1}
+ \texttt{item}, you can put the item name into \texttt{noAdditionalIndent} as in
+ \cref{lst:item-noAdd1}, although a more efficient approach may be to change the relevant
+ field in \texttt{itemNames} to \texttt{0}. Similarly, you can customise
+ the indentation that your \texttt{item} receives using \texttt{indentRules},
+ as in \cref{lst:item-rules1}
\begin{minipage}{.45\textwidth}
\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/item-noAdd1.yaml}[yaml-TCB]{\texttt{item-noAdd1.yaml}}{lst:item-noAdd1}
@@ -24,9 +24,11 @@
latexindent.pl items1.tex -local item-noAdd1.yaml
latexindent.pl items1.tex -local item-rules1.yaml
\end{commandshell}
- the respective outputs are given in \cref{lst:items1-noAdd1,lst:items1-rules1}; note that in \cref{lst:items1-noAdd1}
- that the text after each \texttt{item} has not received any additional indentation, and in \cref{lst:items1-rules1},
- the text after each \texttt{item} has received a single space of indentation, specified by \cref{lst:item-rules1}.
+ the respective outputs are given in \cref{lst:items1-noAdd1,lst:items1-rules1}; note that in
+ \cref{lst:items1-noAdd1} that the text after each \texttt{item} has not received
+ any additional indentation, and in \cref{lst:items1-rules1}, the text after each
+ \texttt{item} has received a single space of indentation, specified by
+ \cref{lst:item-rules1}.
\begin{minipage}{.45\textwidth}
\cmhlistingsfromfile{demonstrations/items1-noAdd1.tex}{\texttt{items1.tex} using \cref{lst:item-noAdd1}}{lst:items1-noAdd1}
@@ -36,10 +38,12 @@
\cmhlistingsfromfile[showtabs=true,showspaces=true]{demonstrations/items1-rules1.tex}{\texttt{items1.tex} using \cref{lst:item-rules1}}{lst:items1-rules1}
\end{minipage}
- Alternatively, you might like to populate \texttt{noAdditionalIndentGlobal} or \texttt{indentRulesGlobal} using the \texttt{items}
- key, as demonstrated in \cref{lst:items-noAdditionalGlobal,lst:items-indentRulesGlobal}. Note that there is a need to
- `reset/remove' the \texttt{item} field from \texttt{indentRules} in both cases (see the hierarchy description given on \cpageref{sec:noadd-indent-rules})
- as the \texttt{item} command is a member of \texttt{indentRules} by default.
+ Alternatively, you might like to populate \texttt{noAdditionalIndentGlobal} or
+ \texttt{indentRulesGlobal} using the \texttt{items} key, as demonstrated in
+ \cref{lst:items-noAdditionalGlobal,lst:items-indentRulesGlobal}. Note that there is a need to `reset/remove' the
+ \texttt{item} field from \texttt{indentRules} in both cases (see the hierarchy
+ description given on \cpageref{sec:noadd-indent-rules}) as the \texttt{item} command is a
+ member of \texttt{indentRules} by default.
\begin{minipage}{.45\textwidth}
\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/items-noAdditionalGlobal.yaml}[yaml-TCB]{\texttt{items-noAdditionalGlobal.yaml}}{lst:items-noAdditionalGlobal}
@@ -55,5 +59,6 @@
latexindent.pl items1.tex -local items-indentRulesGlobal.yaml
\end{commandshell}
the respective outputs from \cref{lst:items1-noAdd1,lst:items1-rules1} are obtained; note, however, that
- \emph{all} such \texttt{item} commands without their own individual \texttt{noAdditionalIndent} or \texttt{indentRules}
- settings would behave as in these listings.
+ \emph{all} such \texttt{item} commands without their own individual
+ \texttt{noAdditionalIndent} or \texttt{indentRules} settings would behave as in these
+ listings.
Modified: trunk/Master/texmf-dist/doc/support/latexindent/subsubsec-headings.tex
===================================================================
--- trunk/Master/texmf-dist/doc/support/latexindent/subsubsec-headings.tex 2018-08-14 22:01:02 UTC (rev 48401)
+++ trunk/Master/texmf-dist/doc/support/latexindent/subsubsec-headings.tex 2018-08-14 22:01:47 UTC (rev 48402)
@@ -1,7 +1,8 @@
% arara: pdflatex: {shell: yes, files: [latexindent]}
\subsubsection{afterHeading code blocks}\label{subsubsec-headings-no-add-indent-rules}
- Let's use the example \cref{lst:headings2} for demonstration throughout this \namecref{subsubsec-headings-no-add-indent-rules}.
- As discussed on \cpageref{lst:headings1}, by default \texttt{latexindent.pl} will not add indentation after headings.
+ Let's use the example \cref{lst:headings2} for demonstration throughout this
+ \namecref{subsubsec-headings-no-add-indent-rules}. As discussed on \cpageref{lst:headings1}, by default
+ \texttt{latexindent.pl} will not add indentation after headings.
\cmhlistingsfromfile{demonstrations/headings2.tex}{\texttt{headings2.tex}}{lst:headings2}
@@ -9,8 +10,9 @@
\begin{commandshell}
latexindent.pl headings2.tex -l headings3.yaml
\end{commandshell}
- we obtain the output in \cref{lst:headings2-mod3}. Note that the argument of \texttt{paragraph} has received (default) indentation,
- and that the body after the heading statement has received (default) indentation.
+ we obtain the output in \cref{lst:headings2-mod3}. Note that the argument of
+ \texttt{paragraph} has received (default) indentation, and that the body after the
+ heading statement has received (default) indentation.
\begin{minipage}{.45\textwidth}
\cmhlistingsfromfile{demonstrations/headings2-mod3.tex}{\texttt{headings2.tex} using \cref{lst:headings3yaml}}{lst:headings2-mod3}
@@ -24,8 +26,10 @@
\begin{commandshell}
latexindent.pl headings2.tex -l headings4.yaml
\end{commandshell}
- then we receive the output in \cref{lst:headings2-mod4}. Note that the arguments \emph{and} the body after the heading
- of \texttt{paragraph} has received no additional indentation, because we have specified \texttt{noAdditionalIndent} in scalar form.
+ then we receive the output in \cref{lst:headings2-mod4}. Note that the arguments
+ \emph{and} the body after the heading of \texttt{paragraph} has received
+ no additional indentation, because we have specified \texttt{noAdditionalIndent} in scalar
+ form.
\begin{minipage}{.45\textwidth}
\cmhlistingsfromfile{demonstrations/headings2-mod4.tex}{\texttt{headings2.tex} using \cref{lst:headings4yaml}}{lst:headings2-mod4}
@@ -35,9 +39,11 @@
\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/headings4.yaml}[yaml-TCB]{\texttt{headings4.yaml}}{lst:headings4yaml}
\end{minipage}
- Similarly, if we specify \texttt{indentRules} as in \cref{lst:headings5yaml} and run analogous commands to those above,
- we receive the output in \cref{lst:headings2-mod5}; note that the \emph{body}, \emph{mandatory argument} and content
- \emph{after the heading} of \texttt{paragraph} have \emph{all} received three tabs worth of indentation.
+ Similarly, if we specify \texttt{indentRules} as in \cref{lst:headings5yaml} and run
+ analogous commands to those above, we receive the output in \cref{lst:headings2-mod5}; note
+ that the \emph{body}, \emph{mandatory argument} and content
+ \emph{after the heading} of \texttt{paragraph} have \emph{all} received
+ three tabs worth of indentation.
\begin{minipage}{.55\textwidth}
\cmhlistingsfromfile[showtabs=true]{demonstrations/headings2-mod5.tex}{\texttt{headings2.tex} using \cref{lst:headings5yaml}}{lst:headings2-mod5}
@@ -47,7 +53,8 @@
\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/headings5.yaml}[yaml-TCB]{\texttt{headings5.yaml}}{lst:headings5yaml}
\end{minipage}
- We may, instead, specify \texttt{noAdditionalIndent} in `field' form, as in \cref{lst:headings6yaml} which gives the output in \cref{lst:headings2-mod6}.
+ We may, instead, specify \texttt{noAdditionalIndent} in `field' form, as in
+ \cref{lst:headings6yaml} which gives the output in \cref{lst:headings2-mod6}.
\begin{minipage}{.45\textwidth}
\cmhlistingsfromfile{demonstrations/headings2-mod6.tex}{\texttt{headings2.tex} using \cref{lst:headings6yaml}}{lst:headings2-mod6}
@@ -57,9 +64,10 @@
\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/headings6.yaml}[yaml-TCB]{\texttt{headings6.yaml}}{lst:headings6yaml}
\end{minipage}
- Analogously, we may specify \texttt{indentRules} as in \cref{lst:headings7yaml} which gives the output in \cref{lst:headings2-mod7};
- note that mandatory argument text has only received a single space of indentation, while the body after the heading has
- received three tabs worth of indentation.
+ Analogously, we may specify \texttt{indentRules} as in \cref{lst:headings7yaml} which
+ gives the output in \cref{lst:headings2-mod7}; note that mandatory argument text has only
+ received a single space of indentation, while the body after the heading has received
+ three tabs worth of indentation.
\begin{minipage}{.45\textwidth}
\cmhlistingsfromfile[showtabs=true]{demonstrations/headings2-mod7.tex}{\texttt{headings2.tex} using \cref{lst:headings7yaml}}{lst:headings2-mod7}
@@ -69,12 +77,14 @@
\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/headings7.yaml}[yaml-TCB]{\texttt{headings7.yaml}}{lst:headings7yaml}
\end{minipage}
- Finally, let's consider \texttt{noAdditionalIndentGlobal} and \texttt{indentRulesGlobal} shown in \cref{lst:headings8yaml,lst:headings9yaml}
- respectively, with respective output in \cref{lst:headings2-mod8,lst:headings2-mod9}. Note that in \cref{lst:headings8yaml} the
- \emph{mandatory argument} of \texttt{paragraph} has received a (default) tab's worth of indentation, while the body after the
- heading has received \emph{no additional indentation}. Similarly, in \cref{lst:headings2-mod9}, the \emph{argument} has received both a
- (default) tab plus two spaces of indentation (from the global rule specified in \cref{lst:headings9yaml}), and the remaining body
- after \texttt{paragraph} has received just two spaces of indentation.
+ Finally, let's consider \texttt{noAdditionalIndentGlobal} and \texttt{indentRulesGlobal} shown in
+ \cref{lst:headings8yaml,lst:headings9yaml} respectively, with respective output in \cref{lst:headings2-mod8,lst:headings2-mod9}.
+ Note that in \cref{lst:headings8yaml} the \emph{mandatory argument} of \texttt{paragraph}
+ has received a (default) tab's worth of indentation, while the body after the heading has
+ received \emph{no additional indentation}. Similarly, in \cref{lst:headings2-mod9}, the
+ \emph{argument} has received both a (default) tab plus two spaces of indentation
+ (from the global rule specified in \cref{lst:headings9yaml}), and the remaining body after
+ \texttt{paragraph} has received just two spaces of indentation.
\begin{minipage}{.45\textwidth}
\cmhlistingsfromfile{demonstrations/headings2-mod8.tex}{\texttt{headings2.tex} using \cref{lst:headings8yaml}}{lst:headings2-mod8}
Modified: trunk/Master/texmf-dist/doc/support/latexindent/subsubsec-ifelsefi.tex
===================================================================
--- trunk/Master/texmf-dist/doc/support/latexindent/subsubsec-ifelsefi.tex 2018-08-14 22:01:02 UTC (rev 48401)
+++ trunk/Master/texmf-dist/doc/support/latexindent/subsubsec-ifelsefi.tex 2018-08-14 22:01:47 UTC (rev 48402)
@@ -1,9 +1,9 @@
% arara: pdflatex: {shell: yes, files: [latexindent]}
\subsubsection{ifelsefi code blocks}
- Let's use the simple example shown in \cref{lst:ifelsefi1}; when
- \texttt{latexindent.pl} operates on this file, the output as in \cref{lst:ifelsefi1-default};
- note that the body of each of the \lstinline!\if! statements have been indented,
- and that the \lstinline!\else! statement has been accounted for correctly.
+ Let's use the simple example shown in \cref{lst:ifelsefi1}; when \texttt{latexindent.pl}
+ operates on this file, the output as in \cref{lst:ifelsefi1-default}; note that the body of
+ each of the \lstinline!\if! statements have been indented, and that the
+ \lstinline!\else! statement has been accounted for correctly.
\begin{minipage}{.45\textwidth}
\cmhlistingsfromfile{demonstrations/ifelsefi1.tex}{\texttt{ifelsefi1.tex}}{lst:ifelsefi1}
@@ -13,9 +13,10 @@
\cmhlistingsfromfile{demonstrations/ifelsefi1-default.tex}{\texttt{ifelsefi1.tex} default output}{lst:ifelsefi1-default}
\end{minipage}
- It is recommended to specify \texttt{noAdditionalIndent} and \texttt{indentRules} in the `scalar' form only
- for these type of code blocks, although the `field' form would work, assuming that \texttt{body} was specified.
- Examples are shown in \cref{lst:ifnum-noAdd,lst:ifnum-indent-rules}.
+ It is recommended to specify \texttt{noAdditionalIndent} and \texttt{indentRules} in the
+ `scalar' form only for these type of code blocks, although the `field' form would work,
+ assuming that \texttt{body} was specified. Examples are shown in
+ \cref{lst:ifnum-noAdd,lst:ifnum-indent-rules}.
\begin{minipage}{.45\textwidth}
\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/ifnum-noAdd.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{ifnum-noAdd.yaml}}{lst:ifnum-noAdd}
@@ -30,9 +31,10 @@
latexindent.pl ifelsefi1.tex -local ifnum-noAdd.yaml
latexindent.pl ifelsefi1.tex -l ifnum-indent-rules.yaml
\end{commandshell}
- we receive the respective output given in \cref{lst:ifelsefi1-output-noAdd,lst:ifelsefi1-output-indent-rules}; note that
- in \cref{lst:ifelsefi1-output-noAdd}, the \texttt{ifnum} code block has \emph{not} received any additional indentation,
- while in \cref{lst:ifelsefi1-output-indent-rules}, the \texttt{ifnum} code block has received one tab and two spaces of indentation.
+ we receive the respective output given in \cref{lst:ifelsefi1-output-noAdd,lst:ifelsefi1-output-indent-rules}; note that in
+ \cref{lst:ifelsefi1-output-noAdd}, the \texttt{ifnum} code block has \emph{not}
+ received any additional indentation, while in \cref{lst:ifelsefi1-output-indent-rules}, the
+ \texttt{ifnum} code block has received one tab and two spaces of indentation.
\begin{minipage}{.45\textwidth}
\cmhlistingsfromfile{demonstrations/ifelsefi1-noAdd.tex}{\texttt{ifelsefi1.tex} using \cref{lst:ifnum-noAdd}}{lst:ifelsefi1-output-noAdd}
@@ -42,7 +44,8 @@
\cmhlistingsfromfile[showspaces=true,showtabs=true]{demonstrations/ifelsefi1-indent-rules.tex}{\texttt{ifelsefi1.tex} using \cref{lst:ifnum-indent-rules}}{lst:ifelsefi1-output-indent-rules}
\end{minipage}
- We may specify \texttt{noAdditionalIndentGlobal} and \texttt{indentRulesGlobal} as in \cref{lst:ifelsefi-noAdd-glob,lst:ifelsefi-indent-rules-global}.
+ We may specify \texttt{noAdditionalIndentGlobal} and \texttt{indentRulesGlobal} as in
+ \cref{lst:ifelsefi-noAdd-glob,lst:ifelsefi-indent-rules-global}.
\begin{minipage}{.49\textwidth}
\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/ifelsefi-noAdd-glob.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{ifelsefi-noAdd-glob.yaml}}{lst:ifelsefi-noAdd-glob}
@@ -57,8 +60,8 @@
latexindent.pl ifelsefi1.tex -local ifelsefi-noAdd-glob.yaml
latexindent.pl ifelsefi1.tex -l ifelsefi-indent-rules-global.yaml
\end{commandshell}
- we receive the outputs in \cref{lst:ifelsefi1-output-noAdd-glob,lst:ifelsefi1-output-indent-rules-global}; notice that in
- \cref{lst:ifelsefi1-output-noAdd-glob} neither of the \texttt{ifelsefi} code blocks have received indentation, while in
+ we receive the outputs in \cref{lst:ifelsefi1-output-noAdd-glob,lst:ifelsefi1-output-indent-rules-global}; notice that in \cref{lst:ifelsefi1-output-noAdd-glob}
+ neither of the \texttt{ifelsefi} code blocks have received indentation, while in
\cref{lst:ifelsefi1-output-indent-rules-global} both code blocks have received a single space of indentation.
\begin{minipage}{.45\textwidth}
@@ -69,15 +72,16 @@
\cmhlistingsfromfile[showspaces=true]{demonstrations/ifelsefi1-indent-rules-global.tex}{\texttt{ifelsefi1.tex} using \cref{lst:ifelsefi-indent-rules-global}}{lst:ifelsefi1-output-indent-rules-global}
\end{minipage}
- We can further explore the treatment of \texttt{ifElseFi} code blocks%
- \announce*{2018-04-27}*{updates to ifElseFi code blocks} in \cref{lst:ifelsefi2},
- and the associated default output given in \cref{lst:ifelsefi2-default}; note, in particular, that the bodies of each of the `or statements'
- have been indented.
+ We can further explore the treatment of \texttt{ifElseFi} code
+ blocks%%%%
+ \announce{2018-04-27}*{updates to ifElseFi code blocks} in \cref{lst:ifelsefi2},
+ and the associated default output given in \cref{lst:ifelsefi2-default}; note, in particular,
+ that the bodies of each of the `or statements' have been indented.
\begin{minipage}{.45\textwidth}
- \cmhlistingsfromfile*{demonstrations/ifelsefi2.tex}{\texttt{ifelsefi2.tex}}{lst:ifelsefi2}
+ \cmhlistingsfromfile{demonstrations/ifelsefi2.tex}{\texttt{ifelsefi2.tex}}{lst:ifelsefi2}
\end{minipage}%
\hfill
\begin{minipage}{.54\textwidth}
- \cmhlistingsfromfile*{demonstrations/ifelsefi2-default.tex}{\texttt{ifelsefi2.tex} default output}{lst:ifelsefi2-default}
+ \cmhlistingsfromfile{demonstrations/ifelsefi2-default.tex}{\texttt{ifelsefi2.tex} default output}{lst:ifelsefi2-default}
\end{minipage}
Modified: trunk/Master/texmf-dist/doc/support/latexindent/subsubsec-no-add-remaining-code-blocks.tex
===================================================================
--- trunk/Master/texmf-dist/doc/support/latexindent/subsubsec-no-add-remaining-code-blocks.tex 2018-08-14 22:01:02 UTC (rev 48401)
+++ trunk/Master/texmf-dist/doc/support/latexindent/subsubsec-no-add-remaining-code-blocks.tex 2018-08-14 22:01:47 UTC (rev 48402)
@@ -1,21 +1,23 @@
% arara: pdflatex: {shell: yes, files: [latexindent]}
\subsubsection{The remaining code blocks}
Referencing the different types of code blocks in \vref{tab:code-blocks}, we have a few
- code blocks yet to cover; these are very similar to the \texttt{commands} code block type
- covered comprehensively in \vref{subsubsec:commands-arguments}, but a small discussion
- defining these remaining code blocks is necessary.
+ code blocks yet to cover; these are very similar to the \texttt{commands} code block
+ type covered comprehensively in \vref{subsubsec:commands-arguments}, but a small discussion defining
+ these remaining code blocks is necessary.
\paragraph{keyEqualsValuesBracesBrackets}
\texttt{latexindent.pl} defines this type of code block by the following criteria:
\begin{itemize}
- \item it must immediately follow either \lstinline!{! OR \lstinline![! OR \lstinline!,! with comments
- and blank lines allowed;
+ \item it must immediately follow either \lstinline!{! OR \lstinline![! OR
+ \lstinline!,! with comments and blank lines allowed;
\item then it has a name made up of the characters detailed in \vref{tab:code-blocks};
\item then an $=$ symbol;
- \item then at least one set of curly braces or square brackets (comments and line breaks allowed throughout).
+ \item then at least one set of curly braces or square brackets (comments and line breaks
+ allowed throughout).
\end{itemize}
- An example is shown in \cref{lst:pgfkeysbefore}, with the default output given in \cref{lst:pgfkeys1:default}.
+ An example is shown in \cref{lst:pgfkeysbefore}, with the default output given in
+ \cref{lst:pgfkeys1:default}.
\begin{minipage}{.45\textwidth}
\cmhlistingsfromfile{demonstrations/pgfkeys1.tex}{\texttt{pgfkeys1.tex}}{lst:pgfkeysbefore}
@@ -25,23 +27,29 @@
\cmhlistingsfromfile[showtabs=true]{demonstrations/pgfkeys1-default.tex}{\texttt{pgfkeys1.tex} default output}{lst:pgfkeys1:default}
\end{minipage}%
- In \cref{lst:pgfkeys1:default}, note that the maximum indentation is three tabs, and these come from:
+ In \cref{lst:pgfkeys1:default}, note that the maximum indentation is three tabs, and these
+ come from:
\begin{itemize}
\item the \lstinline!\pgfkeys! command's mandatory argument;
\item the \lstinline!start coordinate/.initial! key's mandatory argument;
- \item the \lstinline!start coordinate/.initial! key's body, which is defined as any lines following the name of the
- key that include its arguments. This is the part controlled by the \emph{body} field for \texttt{noAdditionalIndent}
- and friends from \cpageref{sec:noadd-indent-rules}.
+ \item the \lstinline!start coordinate/.initial! key's body, which is defined as any lines following the name
+ of the key that include its arguments. This is the part controlled by the
+ \emph{body} field for \texttt{noAdditionalIndent} and friends from
+ \cpageref{sec:noadd-indent-rules}.
\end{itemize}
\paragraph{namedGroupingBracesBrackets}
- This type of code block is mostly motivated by tikz-based code; we define this code block as follows:
+ This type of code block is mostly motivated by tikz-based code; we define this code block
+ as follows:
\begin{itemize}
- \item it must immediately follow either \emph{horizontal space} OR \emph{one or more line breaks} OR \lstinline!{! OR \lstinline![!
- OR \lstinline!$! OR \lstinline!)! OR \lstinline!(!;
+ \item it must immediately follow either \emph{horizontal space} OR \emph{one or more line breaks} OR
+ \lstinline!{! OR \lstinline![! OR \lstinline!$! OR
+ \lstinline!)! OR \lstinline!(!;
\item the name may contain the characters detailed in \vref{tab:code-blocks};
- \item then at least one set of curly braces or square brackets (comments and line breaks allowed throughout).
+ \item then at least one set of curly braces or square brackets (comments and line breaks
+ allowed throughout).
\end{itemize}
- A simple example is given in \cref{lst:child1}, with default output in \cref{lst:child1:default}.
+ A simple example is given in \cref{lst:child1}, with default output in
+ \cref{lst:child1:default}.
\begin{minipage}{.45\textwidth}
\cmhlistingsfromfile{demonstrations/child1.tex}{\texttt{child1.tex}}{lst:child1}
@@ -51,26 +59,31 @@
\cmhlistingsfromfile[showtabs=true]{demonstrations/child1-default.tex}{\texttt{child1.tex} default output}{lst:child1:default}
\end{minipage}%
- In particular, \texttt{latexindent.pl} considers \texttt{child}, \texttt{parent} and \texttt{node} all to be \texttt{namedGroupingBracesBrackets}\footnote{
- You may like to verify this by using the \texttt{-tt} option and checking \texttt{indent.log}! }.
- Referencing \cref{lst:child1:default},
- note that the maximum indentation is two tabs, and these come from:
+ In particular, \texttt{latexindent.pl} considers \texttt{child},
+ \texttt{parent} and \texttt{node} all to be
+ \texttt{namedGroupingBracesBrackets}\footnote{
+ You may like to verify this by using the \texttt{-tt} option and checking \texttt{indent.log}! }. Referencing \cref{lst:child1:default}, note
+ that the maximum indentation is two tabs, and these come from:
\begin{itemize}
\item the \lstinline!child!'s mandatory argument;
- \item the \lstinline!child!'s body, which is defined as any lines following the name of the \texttt{namedGroupingBracesBrackets}
- that include its arguments. This is the part controlled by the \emph{body} field for \texttt{noAdditionalIndent}
- and friends from \cpageref{sec:noadd-indent-rules}.
+ \item the \lstinline!child!'s body, which is defined as any lines following the name of
+ the \texttt{namedGroupingBracesBrackets} that include its arguments. This is the part controlled by the
+ \emph{body} field for \texttt{noAdditionalIndent} and friends from
+ \cpageref{sec:noadd-indent-rules}.
\end{itemize}
\paragraph{UnNamedGroupingBracesBrackets} occur in a variety of situations; specifically, we define
this type of code block as satisfying the following criteria:
\begin{itemize}
- \item it must immediately follow either \lstinline!{! OR \lstinline![! OR \lstinline!,! OR \lstinline!&! OR \lstinline!)! OR \lstinline!(!
- OR \lstinline!$!;
- \item then at least one set of curly braces or square brackets (comments and line breaks allowed throughout).
+ \item it must immediately follow either \lstinline!{! OR \lstinline![! OR
+ \lstinline!,! OR \lstinline!&! OR \lstinline!)! OR
+ \lstinline!(! OR \lstinline!$!;
+ \item then at least one set of curly braces or square brackets (comments and line breaks
+ allowed throughout).
\end{itemize}
- An example is shown in \cref{lst:psforeach1} with default output give in \cref{lst:psforeach:default}.
+ An example is shown in \cref{lst:psforeach1} with default output give in
+ \cref{lst:psforeach:default}.
\begin{minipage}{.45\textwidth}
\cmhlistingsfromfile{demonstrations/psforeach1.tex}{\texttt{psforeach1.tex}}{lst:psforeach1}
@@ -80,23 +93,27 @@
\cmhlistingsfromfile[showtabs=true]{demonstrations/psforeach1-default.tex}{\texttt{psforeach1.tex} default output}{lst:psforeach:default}
\end{minipage}%
- Referencing \cref{lst:psforeach:default}, there are \emph{three} sets of unnamed braces. Note also that the maximum value
- of indentation is three tabs, and these come from:
+ Referencing \cref{lst:psforeach:default}, there are \emph{three} sets of unnamed
+ braces. Note also that the maximum value of indentation is three tabs, and these come
+ from:
\begin{itemize}
\item the \lstinline!\psforeach! command's mandatory argument;
\item the \emph{first} un-named braces mandatory argument;
- \item the \emph{first} un-named braces \emph{body}, which we define as any lines following the first opening \lstinline!{! or \lstinline![!
- that defined the code block. This is the part controlled by the \emph{body} field for \texttt{noAdditionalIndent}
- and friends from \cpageref{sec:noadd-indent-rules}.
+ \item the \emph{first} un-named braces \emph{body}, which we define as any
+ lines following the first opening \lstinline!{! or \lstinline![! that
+ defined the code block. This is the part controlled by the \emph{body} field
+ for \texttt{noAdditionalIndent} and friends from \cpageref{sec:noadd-indent-rules}.
\end{itemize}
- Users wishing to customise the mandatory and/or optional arguments on a \emph{per-name} basis for the \texttt{UnNamedGroupingBracesBrackets}
- should use \texttt{always-un-named}.
+ Users wishing to customise the mandatory and/or optional arguments on a
+ \emph{per-name} basis for the \texttt{UnNamedGroupingBracesBrackets} should use
+ \texttt{always-un-named}.
- \paragraph{filecontents} code blocks behave just as \texttt{environments}, except that neither arguments nor items are sought.
+ \paragraph{filecontents} code blocks behave just as \texttt{environments}, except that
+ neither arguments nor items are sought.
\subsubsection{Summary}
- Having considered all of the different types of code blocks, the functions of the fields given in
- \cref{lst:noAdditionalIndentGlobal,lst:indentRulesGlobal} should now make sense.
+ Having considered all of the different types of code blocks, the functions of the fields
+ given in \cref{lst:noAdditionalIndentGlobal,lst:indentRulesGlobal} should now make sense.
\begin{widepage}
\begin{minipage}{.47\linewidth}
Modified: trunk/Master/texmf-dist/doc/support/latexindent/subsubsec-special.tex
===================================================================
--- trunk/Master/texmf-dist/doc/support/latexindent/subsubsec-special.tex 2018-08-14 22:01:02 UTC (rev 48401)
+++ trunk/Master/texmf-dist/doc/support/latexindent/subsubsec-special.tex 2018-08-14 22:01:47 UTC (rev 48402)
@@ -3,9 +3,10 @@
Let's use the example from \vref{lst:specialbefore} which has default output shown in
\vref{lst:specialafter}.
- It is recommended to specify \texttt{noAdditionalIndent} and \texttt{indentRules} in the `scalar' form
- for these type of code blocks, although the `field' form would work, assuming that \texttt{body} was specified.
- Examples are shown in \cref{lst:displayMath-noAdd,lst:displayMath-indent-rules}.
+ It is recommended to specify \texttt{noAdditionalIndent} and \texttt{indentRules} in the
+ `scalar' form for these type of code blocks, although the `field' form would work,
+ assuming that \texttt{body} was specified. Examples are shown in
+ \cref{lst:displayMath-noAdd,lst:displayMath-indent-rules}.
\begin{minipage}{.49\textwidth}
\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/displayMath-noAdd.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{displayMath-noAdd.yaml}}{lst:displayMath-noAdd}
@@ -20,9 +21,10 @@
latexindent.pl special1.tex -local displayMath-noAdd.yaml
latexindent.pl special1.tex -l displayMath-indent-rules.yaml
\end{commandshell}
- we receive the respective output given in \cref{lst:special1-output-noAdd,lst:special1-output-indent-rules}; note that
- in \cref{lst:special1-output-noAdd}, the \texttt{displayMath} code block has \emph{not} received any additional indentation,
- while in \cref{lst:special1-output-indent-rules}, the \texttt{displayMath} code block has received three tabs worth of indentation.
+ we receive the respective output given in \cref{lst:special1-output-noAdd,lst:special1-output-indent-rules}; note that in
+ \cref{lst:special1-output-noAdd}, the \texttt{displayMath} code block has \emph{not}
+ received any additional indentation, while in \cref{lst:special1-output-indent-rules}, the
+ \texttt{displayMath} code block has received three tabs worth of indentation.
\begin{minipage}{.45\textwidth}
\cmhlistingsfromfile{demonstrations/special1-noAdd.tex}{\texttt{special1.tex} using \cref{lst:displayMath-noAdd}}{lst:special1-output-noAdd}
@@ -32,7 +34,8 @@
\cmhlistingsfromfile[showtabs=true]{demonstrations/special1-indent-rules.tex}{\texttt{special1.tex} using \cref{lst:displayMath-indent-rules}}{lst:special1-output-indent-rules}
\end{minipage}
- We may specify \texttt{noAdditionalIndentGlobal} and \texttt{indentRulesGlobal} as in \cref{lst:special-noAdd-glob,lst:special-indent-rules-global}.
+ We may specify \texttt{noAdditionalIndentGlobal} and \texttt{indentRulesGlobal} as in
+ \cref{lst:special-noAdd-glob,lst:special-indent-rules-global}.
\begin{minipage}{.49\textwidth}
\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/special-noAdd-glob.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{special-noAdd-glob.yaml}}{lst:special-noAdd-glob}
@@ -47,8 +50,8 @@
latexindent.pl special1.tex -local special-noAdd-glob.yaml
latexindent.pl special1.tex -l special-indent-rules-global.yaml
\end{commandshell}
- we receive the outputs in \cref{lst:special1-output-noAdd-glob,lst:special1-output-indent-rules-global}; notice that in
- \cref{lst:special1-output-noAdd-glob} neither of the \texttt{special} code blocks have received indentation, while in
+ we receive the outputs in \cref{lst:special1-output-noAdd-glob,lst:special1-output-indent-rules-global}; notice that in \cref{lst:special1-output-noAdd-glob}
+ neither of the \texttt{special} code blocks have received indentation, while in
\cref{lst:special1-output-indent-rules-global} both code blocks have received a single space of indentation.
\begin{minipage}{.45\textwidth}
Modified: trunk/Master/texmf-dist/doc/support/latexindent/title.tex
===================================================================
--- trunk/Master/texmf-dist/doc/support/latexindent/title.tex 2018-08-14 22:01:02 UTC (rev 48401)
+++ trunk/Master/texmf-dist/doc/support/latexindent/title.tex 2018-08-14 22:01:47 UTC (rev 48402)
@@ -8,7 +8,7 @@
sharp corners,
enhanced,
overlay={\node[anchor=north east,outer sep=2pt] at ([xshift=3cm,yshift=4mm]frame.north east) {\includegraphics[width=3cm]{logo}}; }]
- \centering\ttfamily\bfseries latexindent.pl\\[1cm] Version 3.4.3
+ \centering\ttfamily\bfseries latexindent.pl\\[1cm] Version 3.5
\end{tcolorbox}
}
\author{Chris Hughes \thanks{and contributors!
Modified: trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/AlignmentAtAmpersand.pm
===================================================================
--- trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/AlignmentAtAmpersand.pm 2018-08-14 22:01:02 UTC (rev 48401)
+++ trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/AlignmentAtAmpersand.pm 2018-08-14 22:01:47 UTC (rev 48402)
@@ -107,7 +107,7 @@
return;
}
-sub modify_line_breaks_settings{
+sub yaml_modify_line_breaks_settings{
return;
}
Modified: trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/Arguments.pm
===================================================================
--- trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/Arguments.pm 2018-08-14 22:01:02 UTC (rev 48401)
+++ trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/Arguments.pm 2018-08-14 22:01:47 UTC (rev 48402)
@@ -78,7 +78,15 @@
# give unique id
$arguments->create_unique_id;
+
+ # text wrapping can make the ID split across lines
+ ${$arguments}{idRegExp} = ${$arguments}{id};
+ if($is_m_switch_active){
+ my $IDwithLineBreaks = join("\\R?\\h*",split(//,${$arguments}{id}));
+ ${$arguments}{idRegExp} = qr/$IDwithLineBreaks/s;
+ }
+
# determine which comes first, optional or mandatory
if(${$arguments}{body} =~ m/.*?((?<!\\)\{|\[)/s){
@@ -98,6 +106,12 @@
$arguments->find_optional_arguments;
}
+ # it's possible not to have any mandatory or optional arguments, see
+ # https://github.com/cmhughes/latexindent.pl/issues/123
+ if( !(defined ${$arguments}{children}) ){
+ $logger->trace("No optional or mandatory arguments found; searching for matching round parenthesis") if $is_t_switch_active;
+ $arguments->find_round_brackets;
+ }
} else {
$logger->trace("Searching for round brackets ONLY") if $is_t_switch_active;
# look for round brackets
Modified: trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/BlankLines.pm
===================================================================
--- trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/BlankLines.pm 2018-08-14 22:01:02 UTC (rev 48401)
+++ trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/BlankLines.pm 2018-08-14 22:01:47 UTC (rev 48402)
@@ -26,7 +26,19 @@
sub protect_blank_lines{
return unless $is_m_switch_active;
my $self = shift;
+
+ # the text wrap routine, under some circumstances, can
+ # cause new blank lines that haven't been awarded a token; see, for example,
+ # test-cases/maxLineChars/multi-object-all.tex -l=multi-object2.yaml -m
+ # we can circumvent this by forcing blank lines to be protected if
+ # the text wrap option is active, which allows us to remove blank
+ # lines from wrapped text
+ if(ref ${$masterSettings{modifyLineBreaks}{textWrapOptions}}{columns} eq "HASH"
+ or ${$masterSettings{modifyLineBreaks}{textWrapOptions}}{columns}>0 ){
+ ${$masterSettings{modifyLineBreaks}}{preserveBlankLines} = 1;
+ }
+
unless(${$masterSettings{modifyLineBreaks}}{preserveBlankLines}){
$logger->trace("*Blank lines will not be protected (preserveBlankLines=0)") if $is_t_switch_active;
return
@@ -43,7 +55,7 @@
return unless ${$masterSettings{modifyLineBreaks}}{condenseMultipleBlankLinesInto}>0;
my $self = shift;
-
+
$logger->trace("*condense blank lines routine") if $is_t_switch_active;
# if preserveBlankLines is set to 0, then the blank-line-token will not be present
# in the document -- we change that here
@@ -84,9 +96,13 @@
return unless ${$masterSettings{modifyLineBreaks}}{preserveBlankLines};
my $self = shift;
+
+ # remove any empty lines that might have been added by the text_wrap routine; see, for example,
+ # test-cases/maxLineChars/multi-object-all.tex -l=multi-object2.yaml -m
+ ${$self}{body} =~ s/^\h*\R//mg;
$logger->trace("Unprotecting blank lines (see preserveBlankLines)") if $is_t_switch_active;
- my $blankLineToken = $tokens{blanklines};
+ my $blankLineToken = join("(?:\\h|\\R)*",split(//,$tokens{blanklines}));
# loop through the body, looking for the blank line token
while(${$self}{body} =~ m/$blankLineToken/s){
Modified: trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/Document.pm
===================================================================
--- trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/Document.pm 2018-08-14 22:01:02 UTC (rev 48401)
+++ trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/Document.pm 2018-08-14 22:01:47 UTC (rev 48402)
@@ -23,11 +23,11 @@
# gain access to subroutines in the following modules
use LatexIndent::Switches qw/storeSwitches %switches $is_m_switch_active $is_t_switch_active $is_tt_switch_active/;
use LatexIndent::LogFile qw/processSwitches $logger/;
-use LatexIndent::GetYamlSettings qw/readSettings modify_line_breaks_settings get_indentation_settings_for_this_object get_every_or_custom_value get_indentation_information get_object_attribute_for_indentation_settings alignment_at_ampersand_settings %masterSettings/;
+use LatexIndent::GetYamlSettings qw/yaml_read_settings yaml_modify_line_breaks_settings yaml_get_indentation_settings_for_this_object yaml_poly_switch_get_every_or_custom_value yaml_get_indentation_information yaml_get_object_attribute_for_indentation_settings yaml_alignment_at_ampersand_settings yaml_get_textwrap_removeparagraphline_breaks %masterSettings yaml_get_columns/;
use LatexIndent::FileExtension qw/file_extension_check/;
use LatexIndent::BackUpFileProcedure qw/create_back_up_file/;
use LatexIndent::BlankLines qw/protect_blank_lines unprotect_blank_lines condense_blank_lines/;
-use LatexIndent::ModifyLineBreaks qw/modify_line_breaks_body modify_line_breaks_end remove_line_breaks_begin adjust_line_breaks_end_parent max_char_per_line paragraphs_on_one_line construct_paragraph_reg_exp one_sentence_per_line/;
+use LatexIndent::ModifyLineBreaks qw/modify_line_breaks_body modify_line_breaks_end remove_line_breaks_begin adjust_line_breaks_end_parent text_wrap remove_paragraph_line_breaks construct_paragraph_reg_exp one_sentence_per_line text_wrap_remove_paragraph_line_breaks/;
use LatexIndent::TrailingComments qw/remove_trailing_comments put_trailing_comments_back_in add_comment_symbol construct_trailing_comment_regexp/;
use LatexIndent::HorizontalWhiteSpace qw/remove_trailing_whitespace remove_leading_space/;
use LatexIndent::Indent qw/indent wrap_up_statement determine_total_indentation indent_begin indent_body indent_end_statement final_indentation_check get_surrounding_indentation indent_children_recursively check_for_blank_lines_at_beginning put_blank_lines_back_in_at_beginning add_surrounding_indentation_to_begin_statement post_indentation_check/;
@@ -37,7 +37,7 @@
use LatexIndent::DoubleBackSlash qw/dodge_double_backslash un_dodge_double_backslash/;
# code blocks
-use LatexIndent::Verbatim qw/put_verbatim_back_in find_verbatim_environments find_noindent_block find_verbatim_commands put_verbatim_commands_back_in/;
+use LatexIndent::Verbatim qw/put_verbatim_back_in find_verbatim_environments find_noindent_block find_verbatim_commands put_verbatim_commands_back_in find_verbatim_special/;
use LatexIndent::Environment qw/find_environments $environmentBasicRegExp/;
use LatexIndent::IfElseFi qw/find_ifelsefi construct_ifelsefi_regexp $ifElseFiBasicRegExp/;
use LatexIndent::Else qw/check_for_else_statement/;
@@ -88,7 +88,8 @@
$self->find_aligned_block;
$self->remove_trailing_comments;
$self->find_verbatim_environments;
- $self->max_char_per_line;
+ $self->find_verbatim_special;
+ $self->text_wrap if ($is_m_switch_active and !${$masterSettings{modifyLineBreaks}{textWrapOptions}}{perCodeBlockBasis} and ${$masterSettings{modifyLineBreaks}{textWrapOptions}}{columns}>1);
$self->protect_blank_lines;
$self->remove_trailing_whitespace(when=>"before");
$self->find_file_contents_environments_and_preamble;
@@ -196,8 +197,16 @@
# documents without preamble need a manual call to the paragraph_one_line routine
if ($is_m_switch_active and !${$self}{preamblePresent}){
- ${$self}{removeParagraphLineBreaks} = ${$masterSettings{modifyLineBreaks}{removeParagraphLineBreaks}}{all}||${$masterSettings{modifyLineBreaks}{removeParagraphLineBreaks}}{masterDocument}||0;
- $self->paragraphs_on_one_line ;
+ $self->yaml_get_textwrap_removeparagraphline_breaks;
+
+ # call the remove_paragraph_line_breaks and text_wrap routines
+ if(${$masterSettings{modifyLineBreaks}{removeParagraphLineBreaks}}{beforeTextWrap}){
+ $self->remove_paragraph_line_breaks if ${$self}{removeParagraphLineBreaks};
+ $self->text_wrap if (${$self}{textWrapOptions} and ${$masterSettings{modifyLineBreaks}{textWrapOptions}}{perCodeBlockBasis});
+ } else {
+ $self->text_wrap if (${$self}{textWrapOptions} and ${$masterSettings{modifyLineBreaks}{textWrapOptions}}{perCodeBlockBasis});
+ $self->remove_paragraph_line_breaks if ${$self}{removeParagraphLineBreaks};
+ }
}
# if there are no children, return
@@ -255,6 +264,9 @@
# tasks particular to each object
$latexIndentObject->tasks_particular_to_each_object;
+
+ # removeParagraphLineBreaks and textWrapping fun!
+ $latexIndentObject->text_wrap_remove_paragraph_line_breaks if($is_m_switch_active);
# store children in special hash
push(@{${$self}{children}},$latexIndentObject);
@@ -295,7 +307,7 @@
${$self}{bodyLineBreaks} = $bodyLineBreaks;
# get settings for this object
- $self->get_indentation_settings_for_this_object;
+ $self->yaml_get_indentation_settings_for_this_object;
# give unique id
$self->create_unique_id;
@@ -303,6 +315,14 @@
# add trailing text to the id to stop, e.g LATEX-INDENT-ENVIRONMENT1 matching LATEX-INDENT-ENVIRONMENT10
${$self}{id} .= $tokens{endOfToken};
+ # text wrapping can make the ID split across lines
+ ${$self}{idRegExp} = ${$self}{id};
+
+ if($is_m_switch_active){
+ my $IDwithLineBreaks = join("\\R?\\h*",split(//,${$self}{id}));
+ ${$self}{idRegExp} = qr/$IDwithLineBreaks/s;
+ }
+
# the replacement text can be just the ID, but the ID might have a line break at the end of it
$self->get_replacement_text;
@@ -362,7 +382,7 @@
my $child = @{${$self}{children}}[-1];
# check if the last object was the last thing in the body, and if it has adjusted linebreaks
- $self->adjust_line_breaks_end_parent;
+ $self->adjust_line_breaks_end_parent if $is_m_switch_active;
$logger->trace(Dumper(\%{$child})) if($is_tt_switch_active);
$logger->trace("replaced with ID: ${$child}{id}") if $is_t_switch_active;
Modified: trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/Else.pm
===================================================================
--- trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/Else.pm 2018-08-14 22:01:02 UTC (rev 48401)
+++ trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/Else.pm 2018-08-14 22:01:47 UTC (rev 48402)
@@ -113,7 +113,7 @@
return;
}
-sub get_indentation_information{
+sub yaml_get_indentation_information{
return q();
}
Modified: trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/Environment.pm
===================================================================
--- trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/Environment.pm 2018-08-14 22:01:02 UTC (rev 48401)
+++ trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/Environment.pm 2018-08-14 22:01:47 UTC (rev 48402)
@@ -19,7 +19,7 @@
use LatexIndent::Tokens qw/%tokens/;
use LatexIndent::TrailingComments qw/$trailingCommentRegExp/;
use LatexIndent::GetYamlSettings qw/%masterSettings/;
-use LatexIndent::Switches qw/$is_t_switch_active $is_tt_switch_active/;
+use LatexIndent::Switches qw/$is_t_switch_active $is_tt_switch_active $is_m_switch_active/;
use LatexIndent::LogFile qw/$logger/;
use LatexIndent::Braces qw/$braceBracketRegExpBasic/;
use LatexIndent::IfElseFi qw/$ifElseFiBasicRegExp/;
@@ -90,7 +90,7 @@
$self->get_settings_and_store_new_object($env);
${@{${$self}{children}}[-1]}{replacementText}.($9?$9:q()).($10?$10:q());
/xseg;
- $self->adjust_line_breaks_end_parent;
+ $self->adjust_line_breaks_end_parent if $is_m_switch_active;
}
return;
}
Modified: trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/FileContents.pm
===================================================================
--- trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/FileContents.pm 2018-08-14 22:01:02 UTC (rev 48401)
+++ trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/FileContents.pm 2018-08-14 22:01:47 UTC (rev 48402)
@@ -18,7 +18,7 @@
use warnings;
use LatexIndent::Tokens qw/%tokens/;
use LatexIndent::GetYamlSettings qw/%masterSettings/;
-use LatexIndent::Switches qw/$is_t_switch_active $is_tt_switch_active/;
+use LatexIndent::Switches qw/$is_t_switch_active $is_tt_switch_active $is_m_switch_active/;
use LatexIndent::LogFile qw/$logger/;
use LatexIndent::Environment qw/$environmentBasicRegExp/;
use LatexIndent::IfElseFi qw/$ifElseFiBasicRegExp/;
@@ -83,7 +83,15 @@
);
# give unique id
$fileContentsBlock->create_unique_id;
+
+ # text wrapping can make the ID split across lines
+ ${$fileContentsBlock}{idRegExp} = ${$fileContentsBlock}{id};
+ if($is_m_switch_active){
+ my $IDwithLineBreaks = join("\\R?\\h*",split(//,${$fileContentsBlock}{id}));
+ ${$fileContentsBlock}{idRegExp} = qr/$IDwithLineBreaks/s;
+ }
+
# the replacement text can be just the ID, but the ID might have a line break at the end of it
$fileContentsBlock->get_replacement_text;
@@ -142,7 +150,15 @@
# give unique id
$preamble->create_unique_id;
+
+ # text wrapping can make the ID split across lines
+ ${$preamble}{idRegExp} = ${$preamble}{id};
+ if($is_m_switch_active){
+ my $IDwithLineBreaks = join("\\R?\\h*",split(//,${$preamble}{id}));
+ ${$preamble}{idRegExp} = qr/$IDwithLineBreaks/s;
+ }
+
# get the replacement_text
$preamble->get_replacement_text;
@@ -189,7 +205,7 @@
# store the child, if necessary
if($indentThisChild){
$_->remove_leading_space;
- $_->get_indentation_settings_for_this_object;
+ $_->yaml_get_indentation_settings_for_this_object;
$_->tasks_particular_to_each_object;
push(@{${$self}{children}},$_);
@@ -230,6 +246,20 @@
# search for commands and special code blocks
$self->find_commands_or_key_equals_values_braces_and_special if ${$self}{body} =~ m/$specialBeginAndBracesBracketsBasicRegExp/s;
+
+ # text wrapping, remove paragraph line breaks
+ if ($is_m_switch_active){
+ $self->yaml_get_textwrap_removeparagraphline_breaks;
+
+ # call the remove_paragraph_line_breaks and text_wrap routines
+ if(${$masterSettings{modifyLineBreaks}{removeParagraphLineBreaks}}{beforeTextWrap}){
+ $self->remove_paragraph_line_breaks if ${$self}{removeParagraphLineBreaks};
+ $self->text_wrap if (${$self}{textWrapOptions} and ${$masterSettings{modifyLineBreaks}{textWrapOptions}}{perCodeBlockBasis});
+ } else {
+ $self->text_wrap if (${$self}{textWrapOptions} and ${$masterSettings{modifyLineBreaks}{textWrapOptions}}{perCodeBlockBasis});
+ $self->remove_paragraph_line_breaks if ${$self}{removeParagraphLineBreaks};
+ }
+ }
}
1;
Modified: trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/GetYamlSettings.pm
===================================================================
--- trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/GetYamlSettings.pm 2018-08-14 22:01:02 UTC (rev 48401)
+++ trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/GetYamlSettings.pm 2018-08-14 22:01:47 UTC (rev 48402)
@@ -22,7 +22,7 @@
use File::HomeDir;
use Log::Log4perl qw(get_logger :levels);
use Exporter qw/import/;
-our @EXPORT_OK = qw/readSettings modify_line_breaks_settings get_indentation_settings_for_this_object get_every_or_custom_value get_indentation_information get_object_attribute_for_indentation_settings alignment_at_ampersand_settings %masterSettings/;
+our @EXPORT_OK = qw/yaml_read_settings yaml_modify_line_breaks_settings yaml_get_indentation_settings_for_this_object yaml_poly_switch_get_every_or_custom_value yaml_get_indentation_information yaml_get_object_attribute_for_indentation_settings yaml_alignment_at_ampersand_settings yaml_get_textwrap_removeparagraphline_breaks %masterSettings yaml_get_columns/;
# Read in defaultSettings.YAML file
our $defaultSettings;
@@ -44,7 +44,7 @@
{name=>"justification",default=>"left"},
);
-sub readSettings{
+sub yaml_read_settings{
my $self = shift;
# read the default settings
@@ -431,7 +431,7 @@
return;
}
-sub get_indentation_settings_for_this_object{
+sub yaml_get_indentation_settings_for_this_object{
my $self = shift;
# create a name for previously found settings
@@ -449,13 +449,13 @@
# check for noAdditionalIndent and indentRules
# otherwise use defaultIndent
- my $indentation = $self->get_indentation_information;
+ my $indentation = $self->yaml_get_indentation_information;
# check for alignment at ampersand settings
- $self->alignment_at_ampersand_settings;
+ $self->yaml_alignment_at_ampersand_settings;
# check for line break settings
- $self->modify_line_breaks_settings if $is_m_switch_active;
+ $self->yaml_modify_line_breaks_settings if $is_m_switch_active;
# store the settings
%{${previouslyFoundSettings}{$storageName}} = (
@@ -465,6 +465,8 @@
EndStartsOnOwnLine=>${$self}{EndStartsOnOwnLine},
EndFinishesWithLineBreak=>${$self}{EndFinishesWithLineBreak},
removeParagraphLineBreaks=>${$self}{removeParagraphLineBreaks},
+ textWrapOptions=>${$self}{textWrapOptions},
+ columns=>${$self}{columns},
);
# don't forget alignment settings!
@@ -492,7 +494,7 @@
return;
}
-sub alignment_at_ampersand_settings{
+sub yaml_alignment_at_ampersand_settings{
my $self = shift;
# if the YamlName is, for example, optionalArguments, mandatoryArguments, heading, then we'll be looking for information about the *parent*
@@ -534,7 +536,7 @@
return;
}
-sub modify_line_breaks_settings{
+sub yaml_modify_line_breaks_settings{
my $self = shift;
# grab the logging object
@@ -541,7 +543,8 @@
my $logger = get_logger("Document");
# details to the log file
- $logger->trace("*-m modifylinebreaks switch active, looking for settings for ${$self}{name} ") if $is_t_switch_active;
+ $logger->trace("*-m modifylinebreaks switch active") if $is_t_switch_active;
+ $logger->trace("looking for polyswitch, textWrapOptions, removeParagraphLineBreaks, oneSentencePerLine settings for ${$self}{name} ") if $is_t_switch_active;
# some objects, e.g ifElseFi, can have extra assignments, e.g ElseStartsOnOwnLine
my @toBeAssignedTo = ${$self}{additionalAssignments} ? @{${$self}{additionalAssignments}} : ();
@@ -551,47 +554,201 @@
# we can efficiently loop through the following
foreach (@toBeAssignedTo){
- $self->get_every_or_custom_value(
+ $self->yaml_poly_switch_get_every_or_custom_value(
toBeAssignedTo=>$_,
toBeAssignedToAlias=> ${$self}{aliases}{$_} ? ${$self}{aliases}{$_} : $_,
);
- }
+ };
- # paragraph line break settings
- ${$self}{removeParagraphLineBreaks} = ${$masterSettings{modifyLineBreaks}{removeParagraphLineBreaks}}{all};
+ $self->yaml_get_textwrap_removeparagraphline_breaks;
+ return;
+}
- return if(${$self}{removeParagraphLineBreaks});
+sub yaml_get_textwrap_removeparagraphline_breaks{
+ my $self = shift;
+
+ # grab the logging object
+ my $logger = get_logger("Document");
- # the removeParagraphLineBreaks can contain fields that are hashes or scalar, for example:
- #
- # removeParagraphLineBreaks:
- # all: 0
- # environments: 0
- # or
- # removeParagraphLineBreaks:
- # all: 0
- # environments:
- # quotation: 0
+ # textWrap and removeParagraphLineBreaks settings
+ foreach ("textWrapOptions","removeParagraphLineBreaks"){
- # name of the object in the modifyLineBreaks yaml (e.g environments, ifElseFi, etc)
+ # first check for either
+ #
+ # textWrapOptions:
+ # all: 0
+ #
+ # or
+ #
+ # removeParagraphLineBreaks:
+ # all: 0
+ #
+ # *IMPORTANT*
+ # even if all is set to 1, then it can still be disabled on either a
+ #
+ # per-object:
+ #
+ # for example
+ #
+ # textWrapOptions:
+ # all:
+ # except:
+ # - environments
+ #
+ # will disable textWrapOptions for *all* environments
+ #
+ # per-name
+ #
+ # for example
+ #
+ # textWrapOptions:
+ # all:
+ # except:
+ # - itemize
+ #
+ # will disable textWrapOptions for itemize
+
+ # if 'all' is set as a hash, then the default value is 1, to be turned off (possibly) later
+ ${$self}{$_} = ( ref ${$masterSettings{modifyLineBreaks}{$_}}{all} eq "HASH" ? 1 : ${$masterSettings{modifyLineBreaks}{$_}}{all});
+
+ # get the columns
+ if($_ eq "textWrapOptions" and ${$masterSettings{modifyLineBreaks}{textWrapOptions}}{perCodeBlockBasis}){
+ $self->yaml_get_columns;
+ }
+
+ # name of the object in the modifyLineBreaks yaml (e.g environments, ifElseFi, etc)
+ my $YamlName = ${$self}{modifyLineBreaksYamlName};
+
+ # if the YamlName is either optionalArguments or mandatoryArguments, then we'll be looking for information about the *parent*
+ my $name = ($YamlName =~ m/Arguments/) ? ${$self}{parent} : ${$self}{name};
+
+ # move to the next <thing> if
+ #
+ # textWrapOptions/removeParagraphLineBreaks::
+ # all: 1
+ #
+ if(${$self}{$_}
+ and
+ ref ${$masterSettings{modifyLineBreaks}{$_}}{all} ne "HASH"
+ and
+ ${$masterSettings{modifyLineBreaks}{$_}}{all}){
+ $logger->trace("$_ for $name is ${$self}{$_}") if $is_t_switch_active;
+ next;
+ };
+
+ # otherwise, look for exceptions, either through
+ #
+ # textWrapOptions/removeParagraphLineBreaks:
+ # all:
+ # except:
+ # - <*type* of thing or *name* of thing>
+ #
+ # so, for example, the following (per code-block) is acceptable
+ # which makes an exception for all *environments*
+ #
+ # all:
+ # except:
+ # - 'environments'
+ #
+ # the following (per-name) is acceptable
+ # which only makes an exception for things called itemize
+ #
+ # all:
+ # except:
+ # - 'itemize'
+ #
+ if(${$self}{$_}
+ and
+ defined ${${$masterSettings{modifyLineBreaks}{$_}}{all}}{except}
+ and
+ ref ${${$masterSettings{modifyLineBreaks}{$_}}{all}}{except} eq "ARRAY"
+ ){
+ my %except = map { $_ => 1 } @{${${$masterSettings{modifyLineBreaks}}{$_}}{all}{except}};
+ if( $except{$name} or $except{$YamlName}){
+ ${$self}{$_} = 0;
+ my $detail = ($except{$name} ? "per-name" : "per-code-block-type");
+ $logger->trace("$_ for $name is ${$self}{$_} (found as exception $detail, see $_:all:except)") if $is_t_switch_active;
+ next;
+ }
+ } else {
+ # or otherwise through, for example
+ #
+ # all: 0
+ # ifElseFi: 1
+ #
+ # the textWrapOptions/removeParagraphLineBreaks can contain fields that are hashes or scalar
+ #
+ if(ref ${$masterSettings{modifyLineBreaks}{$_}}{$YamlName} eq "HASH"){
+ # textWrapOptions/removeParagraphLineBreaks:
+ # all: 0
+ # environments:
+ # quotation: 0
+ $logger->trace("*$YamlName specified with fields in $_, looking for $name") if $is_t_switch_active;
+ ${$self}{$_} = ${${$masterSettings{modifyLineBreaks}{$_}}{$YamlName}}{$name} if (defined ${${$masterSettings{modifyLineBreaks}{$_}}{$YamlName}}{$name});
+ } elsif(defined ${$masterSettings{modifyLineBreaks}{$_}}{$YamlName}){
+ # textWrapOptions/removeParagraphLineBreaks:
+ # all: 0
+ # environments: 0
+ $logger->trace("*$YamlName specified with just a number in $_ ${$masterSettings{modifyLineBreaks}{$_}}{$YamlName}") if $is_t_switch_active;
+ ${$self}{$_} = ${$masterSettings{modifyLineBreaks}{$_}}{$YamlName} if (defined ${$masterSettings{modifyLineBreaks}{$_}}{$YamlName});
+ }
+ }
+
+ # summary to log file
+ $logger->trace("$_ for $name is ${$self}{$_}") if $is_t_switch_active;
+ }
+
+ return;
+}
+
+sub yaml_get_columns{
+ my $self = shift;
+
my $YamlName = ${$self}{modifyLineBreaksYamlName};
- # if the YamlName is either optionalArguments or mandatoryArguments, then we'll be looking for information about the *parent*
- my $name = ($YamlName =~ m/Arguments/) ? ${$self}{parent} : ${$self}{name};
+ # the columns settings can have a variety of different ways of being specified
+ if(ref ${$masterSettings{modifyLineBreaks}{textWrapOptions}}{columns} eq "HASH"){
+ # assign default value of $columns
+ my $columns;
+ if(defined ${${$masterSettings{modifyLineBreaks}{textWrapOptions}}{columns}}{default}){
+ $columns = ${${$masterSettings{modifyLineBreaks}{textWrapOptions}}{columns}}{default};
+ } else {
+ $columns = 80;
+ }
- if(ref ${$masterSettings{modifyLineBreaks}{removeParagraphLineBreaks}}{$YamlName} eq "HASH"){
- $logger->trace("*$YamlName specified with fields in removeParagraphLineBreaks, looking for $name") if $is_t_switch_active;
- ${$self}{removeParagraphLineBreaks} = ${${$masterSettings{modifyLineBreaks}{removeParagraphLineBreaks}}{$YamlName}}{$name}||0;
+ # possibly specify object wrapping on a per-name basis
+ if(ref ${${$masterSettings{modifyLineBreaks}{textWrapOptions}}{columns}}{$YamlName} eq "HASH"){
+ # for example:
+ # modifyLineBreaks:
+ # textWrapOptions:
+ # columns:
+ # default: 80
+ # environments:
+ # default: 80
+ # something: 10
+ # another: 20
+ if(defined ${${${$masterSettings{modifyLineBreaks}{textWrapOptions}}{columns}}{$YamlName}}{${$self}{name}}){
+ $columns = ${${${$masterSettings{modifyLineBreaks}{textWrapOptions}}{columns}}{$YamlName}}{${$self}{name}};
+ } elsif (${${${$masterSettings{modifyLineBreaks}{textWrapOptions}}{columns}}{$YamlName}}{default}){
+ $columns = ${${${$masterSettings{modifyLineBreaks}{textWrapOptions}}{columns}}{$YamlName}}{default};
+ }
+ } else {
+ # for example:
+ # modifyLineBreaks:
+ # textWrapOptions:
+ # columns:
+ # default: 80
+ # environments: 10
+ $columns = ${${$masterSettings{modifyLineBreaks}{textWrapOptions}}{columns}}{$YamlName};
+ }
+ ${$self}{columns} = $columns;
} else {
- if(defined ${$masterSettings{modifyLineBreaks}{removeParagraphLineBreaks}}{$YamlName}){
- $logger->trace("*$YamlName specified with just a number in removeParagraphLineBreaks ${$masterSettings{modifyLineBreaks}{removeParagraphLineBreaks}}{$YamlName}") if $is_t_switch_active;
- ${$self}{removeParagraphLineBreaks} = ${$masterSettings{modifyLineBreaks}{removeParagraphLineBreaks}}{$YamlName};
- }
+ ${$self}{columns} = ${$masterSettings{modifyLineBreaks}{textWrapOptions}}{columns};
}
return;
}
-sub get_every_or_custom_value{
+sub yaml_poly_switch_get_every_or_custom_value{
my $self = shift;
my %input = @_;
@@ -630,7 +787,7 @@
return;
}
-sub get_indentation_information{
+sub yaml_get_indentation_information{
my $self = shift;
#**************************************
@@ -678,7 +835,7 @@
my $name = (defined ${$self}{nameForIndentationSettings}) ? ${$self}{nameForIndentationSettings} : ${$self}{name};
# if the YamlName is not optionalArguments, mandatoryArguments, heading (possibly others) then assume we're looking for 'body'
- my $YamlName = $self->get_object_attribute_for_indentation_settings;
+ my $YamlName = $self->yaml_get_object_attribute_for_indentation_settings;
# grab the logging object
my $logger = get_logger("Document");
@@ -732,7 +889,7 @@
return $masterSettings{defaultIndent};
}
-sub get_object_attribute_for_indentation_settings{
+sub yaml_get_object_attribute_for_indentation_settings{
# when looking for noAdditionalIndent or indentRules, we may need to determine
# which thing we're looking for, e.g
#
Modified: trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/Heading.pm
===================================================================
--- trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/Heading.pm 2018-08-14 22:01:02 UTC (rev 48401)
+++ trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/Heading.pm 2018-08-14 22:01:47 UTC (rev 48402)
@@ -174,7 +174,7 @@
return;
}
-sub get_object_attribute_for_indentation_settings{
+sub yaml_get_object_attribute_for_indentation_settings{
# when looking for noAdditionalIndent or indentRules, we may need to determine
# which thing we're looking for, e.g
#
Modified: trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/HiddenChildren.pm
===================================================================
--- trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/HiddenChildren.pm 2018-08-14 22:01:02 UTC (rev 48401)
+++ trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/HiddenChildren.pm 2018-08-14 22:01:47 UTC (rev 48402)
@@ -16,7 +16,7 @@
# For all communication, please visit: https://github.com/cmhughes/latexindent.pl
use strict;
use warnings;
-use LatexIndent::Switches qw/$is_t_switch_active $is_tt_switch_active/;
+use LatexIndent::Switches qw/$is_t_switch_active $is_tt_switch_active $is_m_switch_active /;
use LatexIndent::Tokens qw/%tokens/;
use LatexIndent::LogFile qw/$logger/;
use Data::Dumper;
@@ -156,9 +156,22 @@
my $self = shift;
+ my @matched;
# grab the matches
- my @matched = (${$self}{body} =~ /((?:$tokens{ifelsefiSpecial})?$tokens{beginOfToken}.[-a-z0-9]+?$tokens{endOfToken})/ig);
+ if($is_m_switch_active){
+ # if modifyLineBreaks is active, then the IDS can be split across lines
+ my $ifElseFiSpecialBegin = join("\\R?\\h*",split(//,$tokens{ifelsefiSpecial}));
+ my $BeginwithLineBreaks = join("\\R?\\h*",split(//,$tokens{beginOfToken}));
+ my $EndwithLineBreaks = join("\\R?\\h*",split(//,$tokens{endOfToken}));
+ my $BlankLinesWithLineBreaks = join("\\R?\\h*",split(//,$tokens{blanklines}));
+ @matched = (${$self}{body} =~ /(?!$BlankLinesWithLineBreaks)((?:$ifElseFiSpecialBegin)?$BeginwithLineBreaks[-a-z0-9\n]+?$EndwithLineBreaks)/ig);
+ # remove line breaks and horizontal space from matches
+ $_ =~ s/\R|\h//gs foreach (@matched);
+ } else {
+ @matched = (${$self}{body} =~ /((?:$tokens{ifelsefiSpecial})?$tokens{beginOfToken}.[-a-z0-9]+?$tokens{endOfToken})/igs);
+ }
+
# log file
$logger->trace("*Hidden children check") if $is_t_switch_active;
$logger->trace(join("|", at matched)) if $is_t_switch_active;
Modified: trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/Indent.pm
===================================================================
--- trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/Indent.pm 2018-08-14 22:01:02 UTC (rev 48401)
+++ trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/Indent.pm 2018-08-14 22:01:47 UTC (rev 48402)
@@ -124,7 +124,7 @@
$self->align_at_ampersand if ${$self}{lookForAlignDelims};
# possibly remove paragraph line breaks
- $self->paragraphs_on_one_line if $is_m_switch_active;
+ $self->remove_paragraph_line_breaks if ($is_m_switch_active and ${$self}{removeParagraphLineBreaks} and !${$masterSettings{modifyLineBreaks}{removeParagraphLineBreaks}}{beforeTextWrap});
# body indendation
if(${$self}{linebreaksAtEnd}{begin}==1){
@@ -279,7 +279,7 @@
# we work through the array *in order*
foreach my $child (@{${$self}{children}}){
$logger->trace("Searching ${$self}{name} for ${$child}{id}...") if $is_t_switch_active;
- if(${$self}{body} =~ m/${$child}{id}/s){
+ if(${$self}{body} =~ m/${$child}{idRegExp}/s){
# we only care if id is first non-white space character
# and if followed by line break
# if m switch is active
@@ -288,11 +288,11 @@
# update the above two, if necessary
if ($is_m_switch_active){
- $IDFirstNonWhiteSpaceCharacter = (${$self}{body} =~ m/^${$child}{id}/m
+ $IDFirstNonWhiteSpaceCharacter = (${$self}{body} =~ m/^${$child}{idRegExp}/m
or
- ${$self}{body} =~ m/^\h\h*${$child}{id}/m
+ ${$self}{body} =~ m/^\h\h*${$child}{idRegExp}/m
) ?1:0;
- $IDFollowedImmediatelyByLineBreak = (${$self}{body} =~ m/${$child}{id}\h*\R+/m) ?1:0;
+ $IDFollowedImmediatelyByLineBreak = (${$self}{body} =~ m/${$child}{idRegExp}\h*\R+/m) ?1:0;
${$child}{IDFollowedImmediatelyByLineBreak} = $IDFollowedImmediatelyByLineBreak;
}
@@ -308,7 +308,7 @@
# remove line break *after* <end statement>, if appropriate
my $EndStringLogFile = ${$child}{aliases}{EndFinishesWithLineBreak}||"EndFinishesWithLineBreak";
$logger->trace("Removing linebreak after ${$child}{end} (see $EndStringLogFile)") if $is_t_switch_active;
- ${$self}{body} =~ s/${$child}{id}(\h*)?(\R|\h)*/${$child}{id}$1/s;
+ ${$self}{body} =~ s/${$child}{idRegExp}(\h*)?(\R|\h)*/${$child}{id}$1/s;
${$child}{linebreaksAtEnd}{end} = 0;
}
@@ -332,7 +332,7 @@
my $trailingCharacterToken = q();
if(${$child}{BeginStartsOnOwnLine}==2){
$logger->trace("Removing space immediately before ${$child}{id}, in preparation for adding % ($BeginStringLogFile == 2)") if $is_t_switch_active;
- ${$self}{body} =~ s/\h*${$child}{id}/${$child}{id}/s;
+ ${$self}{body} =~ s/\h*${$child}{idRegExp}/${$child}{id}/s;
$logger->trace("Adding a % at the end of the line that ${$child}{begin} is on, then a linebreak ($BeginStringLogFile == 2)") if $is_t_switch_active;
$trailingCharacterToken = "%".$self->add_comment_symbol;
} elsif (${$child}{BeginStartsOnOwnLine}==3){
@@ -352,9 +352,9 @@
# finally, if BeginStartsOnOwnLine == -1 then we might need to *remove* a blank line(s)
# important to check we don't move the begin statement next to a blank-line-token
my $blankLineToken = $tokens{blanklines};
- if(${$self}{body} !~ m/$blankLineToken\R*\h*${$child}{id}/s){
+ if(${$self}{body} !~ m/$blankLineToken\R*\h*${$child}{idRegExp}/s){
$logger->trace("Removing linebreak before ${$child}{begin} (see $BeginStringLogFile in ${$child}{modifyLineBreaksYamlName} YAML)") if $is_t_switch_active;
- ${$self}{body} =~ s/(\h*)(?:\R*|\h*)+${$child}{id}/$1${$child}{id}/s;
+ ${$self}{body} =~ s/(\h*)(?:\R*|\h*)+${$child}{idRegExp}/$1${$child}{id}/s;
} else {
$logger->trace("Not removing linebreak ahead of ${$child}{begin}, as blank-line-token present (see preserveBlankLines)") if $is_t_switch_active;
}
@@ -364,7 +364,7 @@
$logger->trace(Dumper(\%{$child})) if($is_tt_switch_active);
# replace ids with body
- ${$self}{body} =~ s/${$child}{id}/${$child}{begin}${$child}{body}${$child}{end}/;
+ ${$self}{body} =~ s/${$child}{idRegExp}/${$child}{begin}${$child}{body}${$child}{end}/;
# log file info
$logger->trace("Body (${$self}{name}) now looks like:") if $is_tt_switch_active;
Modified: trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/LogFile.pm
===================================================================
--- trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/LogFile.pm 2018-08-14 22:01:02 UTC (rev 48401)
+++ trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/LogFile.pm 2018-08-14 22:01:47 UTC (rev 48402)
@@ -140,7 +140,7 @@
if($switches{screenlog}){
$appender_screen = Log::Log4perl::Appender->new(
"Log::Log4perl::Appender::Screen",
- stderr => 0,
+ stderr => 1,
utf8 => 1,
);
@@ -160,7 +160,7 @@
} else {
$logger->info("Reading input from STDIN");
my $buttonText = ($FindBin::Script eq 'latexindent.exe') ? 'CTRL+Z followed by ENTER':'CTRL+D';
- print "Please enter text to be indented: (press $buttonText when finished)\n";
+ print STDERR "Please enter text to be indented: (press $buttonText when finished)\n";
}
# log the switches from the user
@@ -205,7 +205,7 @@
}
# read the YAML settings
- $self->readSettings;
+ $self->yaml_read_settings;
# the user may have specified their own settings for the rest of the log file,
# for example:
Modified: trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/MandatoryArgument.pm
===================================================================
--- trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/MandatoryArgument.pm 2018-08-14 22:01:02 UTC (rev 48401)
+++ trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/MandatoryArgument.pm 2018-08-14 22:01:47 UTC (rev 48402)
@@ -113,7 +113,7 @@
return $mandArgRegExp;
}
-sub get_object_attribute_for_indentation_settings{
+sub yaml_get_object_attribute_for_indentation_settings{
my $self = shift;
return ${$self}{modifyLineBreaksYamlName};
Modified: trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/ModifyLineBreaks.pm
===================================================================
--- trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/ModifyLineBreaks.pm 2018-08-14 22:01:02 UTC (rev 48401)
+++ trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/ModifyLineBreaks.pm 2018-08-14 22:01:47 UTC (rev 48402)
@@ -25,13 +25,13 @@
use LatexIndent::Switches qw/$is_m_switch_active $is_t_switch_active $is_tt_switch_active/;
use LatexIndent::Item qw/$listOfItems/;
use LatexIndent::LogFile qw/$logger/;
-our @EXPORT_OK = qw/modify_line_breaks_body modify_line_breaks_end adjust_line_breaks_end_parent remove_line_breaks_begin max_char_per_line paragraphs_on_one_line construct_paragraph_reg_exp one_sentence_per_line/;
+our @EXPORT_OK = qw/modify_line_breaks_body modify_line_breaks_end adjust_line_breaks_end_parent remove_line_breaks_begin text_wrap remove_paragraph_line_breaks construct_paragraph_reg_exp one_sentence_per_line text_wrap_remove_paragraph_line_breaks/;
our $paragraphRegExp = q();
sub modify_line_breaks_body{
my $self = shift;
-
+
# add a line break after \begin{statement} if appropriate
if(defined ${$self}{BodyStartsOnOwnLine}){
my $BodyStringLogFile = ${$self}{aliases}{BodyStartsOnOwnLine}||"BodyStartsOnOwnLine";
@@ -177,7 +177,6 @@
sub adjust_line_breaks_end_parent{
# when a parent object contains a child object, the line break
# at the end of the parent object can become messy
- return unless $is_m_switch_active;
my $self = shift;
@@ -208,14 +207,44 @@
}
-sub max_char_per_line{
- return unless $is_m_switch_active;
+sub text_wrap_remove_paragraph_line_breaks{
+ my $self = shift;
+ if(${$masterSettings{modifyLineBreaks}{removeParagraphLineBreaks}}{beforeTextWrap}){
+ $self->remove_paragraph_line_breaks if ${$self}{removeParagraphLineBreaks};
+ $self->text_wrap if (${$self}{textWrapOptions} and ${$masterSettings{modifyLineBreaks}{textWrapOptions}}{perCodeBlockBasis});
+ } else {
+ $self->text_wrap if (${$self}{textWrapOptions} and ${$masterSettings{modifyLineBreaks}{textWrapOptions}}{perCodeBlockBasis});
+ }
+
+}
+
+sub text_wrap{
+
my $self = shift;
- return unless ${$masterSettings{modifyLineBreaks}{textWrapOptions}}{columns}>1;
+
+ # alignment at ampersand can take priority
+ return if(${$self}{lookForAlignDelims} and ${$masterSettings{modifyLineBreaks}{textWrapOptions}}{alignAtAmpersandTakesPriority});
# call the text wrapping routine
- $Text::Wrap::columns=${$masterSettings{modifyLineBreaks}{textWrapOptions}}{columns};
+ my $columns;
+
+ # columns might have been defined by the user
+ if(defined ${$self}{columns}){
+ $columns = ${$self}{columns};
+ } elsif(ref ${$masterSettings{modifyLineBreaks}{textWrapOptions}}{columns} eq "HASH"){
+ if(defined ${${$masterSettings{modifyLineBreaks}{textWrapOptions}}{columns}}{default}){
+ $columns = ${${$masterSettings{modifyLineBreaks}{textWrapOptions}}{columns}}{default};
+ } else {
+ $columns = 80;
+ }
+ } elsif (defined ${$masterSettings{modifyLineBreaks}{textWrapOptions}}{columns}){
+ $columns = ${$masterSettings{modifyLineBreaks}{textWrapOptions}}{columns} ;
+ } else {
+ $columns = 80;
+ }
+
+ $Text::Wrap::columns=$columns;
if(${$masterSettings{modifyLineBreaks}{textWrapOptions}}{separator} ne ''){
$Text::Wrap::separator=${$masterSettings{modifyLineBreaks}{textWrapOptions}}{separator};
}
@@ -271,7 +300,7 @@
$logger->trace($paragraphRegExp) if $is_tt_switch_active ;
}
-sub paragraphs_on_one_line{
+sub remove_paragraph_line_breaks{
my $self = shift;
return unless ${$self}{removeParagraphLineBreaks};
@@ -481,6 +510,39 @@
while( my $sentence = pop @sentenceStorage){
my $sentenceStorageID = ${$sentence}{id};
my $sentenceStorageValue = ${$sentence}{value};
+
+ # option to text wrap (and option to indent) sentences
+ if(${$masterSettings{modifyLineBreaks}{oneSentencePerLine}}{textWrapSentences}){
+ my $sentenceObj = LatexIndent::Document->new(body=>$sentenceStorageValue,
+ name=>"sentence",
+ modifyLineBreaksYamlName=>"sentence",
+ );
+
+ # text wrapping
+ $sentenceObj->yaml_get_columns;
+ $sentenceObj->text_wrap;
+
+ # indentation of sentences
+ if(${$sentenceObj}{body} =~ m/
+ (.*?) # content of first line
+ \R # first line break
+ (.*$) # rest of body
+ /sx){
+ my $bodyFirstLine = $1;
+ my $remainingBody = $2;
+ my $indentation = ${$masterSettings{modifyLineBreaks}{oneSentencePerLine}}{sentenceIndent};
+ $logger->trace("first line of sencent: $bodyFirstLine") if $is_tt_switch_active;
+ $logger->trace("remaining body (before indentation):\n'$remainingBody'") if($is_tt_switch_active);
+
+ # add the indentation to all the body except first line
+ $remainingBody =~ s/^/$indentation/mg unless($remainingBody eq ''); # add indentation
+ $logger->trace("remaining body (after indentation):\n$remainingBody'") if($is_tt_switch_active);
+
+ # put the body back together
+ ${$sentenceObj}{body} = $bodyFirstLine."\n".$remainingBody;
+ }
+ $sentenceStorageValue = ${$sentenceObj}{body};
+ };
# sentence at the very END
${$self}{body} =~ s/\h*$sentenceStorageID\h*$/$sentenceStorageValue/s;
# sentence at the very BEGINNING
Modified: trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/OptionalArgument.pm
===================================================================
--- trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/OptionalArgument.pm 2018-08-14 22:01:02 UTC (rev 48401)
+++ trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/OptionalArgument.pm 2018-08-14 22:01:47 UTC (rev 48402)
@@ -90,7 +90,7 @@
}
}
-sub get_object_attribute_for_indentation_settings{
+sub yaml_get_object_attribute_for_indentation_settings{
my $self = shift;
return ${$self}{modifyLineBreaksYamlName};
Modified: trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/Preamble.pm
===================================================================
--- trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/Preamble.pm 2018-08-14 22:01:02 UTC (rev 48401)
+++ trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/Preamble.pm 2018-08-14 22:01:47 UTC (rev 48402)
@@ -17,7 +17,7 @@
use strict;
use warnings;
use LatexIndent::Tokens qw/%tokens/;
-use LatexIndent::Switches qw/$is_t_switch_active/;
+use LatexIndent::Switches qw/$is_t_switch_active $is_m_switch_active/;
use LatexIndent::GetYamlSettings qw/%masterSettings/;
use LatexIndent::LogFile qw/$logger/;
use LatexIndent::Environment qw/$environmentBasicRegExp/;
@@ -69,8 +69,22 @@
# search for special begin/end
$self->find_special if ${$self}{body} =~ m/$specialBeginBasicRegExp/s;
- }
+ }
+ # text wrapping, remove paragraph line breaks
+ if ($is_m_switch_active){
+ $self->yaml_get_textwrap_removeparagraphline_breaks;
+
+ # call the remove_paragraph_line_breaks and text_wrap routines
+ if(${$masterSettings{modifyLineBreaks}{removeParagraphLineBreaks}}{beforeTextWrap}){
+ $self->remove_paragraph_line_breaks if ${$self}{removeParagraphLineBreaks};
+ $self->text_wrap if (${$self}{textWrapOptions} and ${$masterSettings{modifyLineBreaks}{textWrapOptions}}{perCodeBlockBasis});
+ } else {
+ $self->text_wrap if (${$self}{textWrapOptions} and ${$masterSettings{modifyLineBreaks}{textWrapOptions}}{perCodeBlockBasis});
+ $self->remove_paragraph_line_breaks if ${$self}{removeParagraphLineBreaks};
+ }
+ }
+
}
1;
Modified: trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/RoundBrackets.pm
===================================================================
--- trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/RoundBrackets.pm 2018-08-14 22:01:02 UTC (rev 48401)
+++ trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/RoundBrackets.pm 2018-08-14 22:01:47 UTC (rev 48402)
@@ -79,7 +79,7 @@
}
}
-sub get_object_attribute_for_indentation_settings{
+sub yaml_get_object_attribute_for_indentation_settings{
my $self = shift;
return ${$self}{modifyLineBreaksYamlName};
Modified: trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/Special.pm
===================================================================
--- trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/Special.pm 2018-08-14 22:01:02 UTC (rev 48401)
+++ trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/Special.pm 2018-08-14 22:01:47 UTC (rev 48402)
@@ -40,7 +40,7 @@
while( my ($specialName,$BeginEnd)= each %{$masterSettings{specialBeginEnd}}){
if(ref($BeginEnd) eq "HASH"){
# only append the regexps if lookForThis is 1
- $specialBegins .= ($specialBegins eq ""?q():"|").${$BeginEnd}{begin} if(${$BeginEnd}{lookForThis});
+ $specialBegins .= ($specialBegins eq ""?q():"|").${$BeginEnd}{begin} if(${$BeginEnd}{lookForThis}=~m/\d/s and ${$BeginEnd}{lookForThis} == 1);
}
}
@@ -48,9 +48,7 @@
while( my ($specialName,$BeginEnd)= each %{$masterSettings{specialBeginEnd}}){
# only append the regexps if lookForThis is 1
- if( (ref($BeginEnd) eq "HASH") and ${$BeginEnd}{lookForThis}){
- # the beginning parts
- $specialBegins .= ($specialBegins eq ""?q():"|").${$BeginEnd}{begin};
+ if( (ref($BeginEnd) eq "HASH") and ${$BeginEnd}{lookForThis}=~m/\d/s and ${$BeginEnd}{lookForThis} == 1){
# the overall regexp
$specialAllMatchesRegExp .= ($specialAllMatchesRegExp eq ""?q():"|")
@@ -128,7 +126,7 @@
while( my ($specialName,$BeginEnd)= each %{$masterSettings{specialBeginEnd}}){
# log file
- if((ref($BeginEnd) eq "HASH") and ${$BeginEnd}{lookForThis}){
+ if((ref($BeginEnd) eq "HASH") and ${$BeginEnd}{lookForThis}=~m/\d/s and ${$BeginEnd}{lookForThis} == 1){
$logger->trace("Looking for $specialName") if $is_t_switch_active ;
} else {
$logger->trace("Not looking for $specialName (see lookForThis)") if ($is_t_switch_active and (ref($BeginEnd) eq "HASH"));
Modified: trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/TrailingComments.pm
===================================================================
--- trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/TrailingComments.pm 2018-08-14 22:01:02 UTC (rev 48401)
+++ trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/TrailingComments.pm 2018-08-14 22:01:47 UTC (rev 48402)
@@ -103,7 +103,7 @@
if(${$masterSettings{modifyLineBreaks}{textWrapOptions}}{separator} ne ''){
$trailingcommentIDwithLineBreaks = join("\\".${$masterSettings{modifyLineBreaks}{textWrapOptions}}{separator}."?",split(//,$trailingcommentID));
} else {
- $trailingcommentIDwithLineBreaks = join("\\R?",split(//,$trailingcommentID));
+ $trailingcommentIDwithLineBreaks = join("(?:\\h|\\R)*",split(//,$trailingcommentID));
}
my $trailingcommentIDwithLineBreaksRegExp = qr/$trailingcommentIDwithLineBreaks/s;
Modified: trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/Verbatim.pm
===================================================================
--- trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/Verbatim.pm 2018-08-14 22:01:02 UTC (rev 48401)
+++ trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/Verbatim.pm 2018-08-14 22:01:47 UTC (rev 48402)
@@ -22,7 +22,7 @@
use LatexIndent::GetYamlSettings qw/%masterSettings/;
use LatexIndent::Switches qw/$is_t_switch_active $is_tt_switch_active $is_m_switch_active/;
use LatexIndent::LogFile qw/$logger/;
-our @EXPORT_OK = qw/put_verbatim_back_in find_verbatim_environments find_noindent_block find_verbatim_commands put_verbatim_commands_back_in/;
+our @EXPORT_OK = qw/put_verbatim_back_in find_verbatim_environments find_noindent_block find_verbatim_commands put_verbatim_commands_back_in find_verbatim_special/;
our @ISA = "LatexIndent::Document"; # class inheritance, Programming Perl, pg 321
our $verbatimCounter;
@@ -307,6 +307,57 @@
return;
}
+sub find_verbatim_special{
+ my $self = shift;
+
+ # loop through specialBeginEnd
+ while( my ($specialName,$BeginEnd)= each %{$masterSettings{specialBeginEnd}}){
+
+ # only classify special Verbatim if lookForThis is 'verbatim'
+ if( (ref($BeginEnd) eq "HASH") and ${$BeginEnd}{lookForThis}=~m/v/s and ${$BeginEnd}{lookForThis} eq 'verbatim'){
+ $logger->trace('*Searching for VERBATIM special (see specialBeginEnd)') if $is_t_switch_active;
+
+ my $verbatimRegExp = qr/
+ (
+ ${$BeginEnd}{begin}
+ )
+ (
+ .*?
+ )
+ (
+ ${$BeginEnd}{end}
+ )
+ /sx;
+
+ while( ${$self}{body} =~ m/$verbatimRegExp/sx){
+
+ # create a new Environment object
+ my $verbatimBlock = LatexIndent::Verbatim->new( begin=>$1,
+ body=>$2,
+ end=>$3,
+ name=>$specialName,
+ );
+ # give unique id
+ $verbatimBlock->create_unique_id;
+
+ # verbatim children go in special hash
+ ${$self}{verbatim}{${$verbatimBlock}{id}}=$verbatimBlock;
+
+ # log file output
+ $logger->trace("*VERBATIM special found: $specialName") if $is_t_switch_active;
+
+ # remove the special block, and replace with unique ID
+ ${$self}{body} =~ s/$verbatimRegExp/${$verbatimBlock}{id}/sx;
+
+ $logger->trace("replaced with ID: ${$verbatimBlock}{id}") if $is_t_switch_active;
+
+ # possible decoration in log file
+ $logger->trace(${$masterSettings{logFilePreferences}}{showDecorationFinishCodeBlockTrace}) if ${$masterSettings{logFilePreferences}}{showDecorationFinishCodeBlockTrace};
+ }
+ }
+ }
+}
+
sub create_unique_id{
my $self = shift;
Modified: trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/Version.pm
===================================================================
--- trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/Version.pm 2018-08-14 22:01:02 UTC (rev 48401)
+++ trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/Version.pm 2018-08-14 22:01:47 UTC (rev 48402)
@@ -19,6 +19,6 @@
use Exporter qw/import/;
our @EXPORT_OK = qw/$versionNumber $versionDate/;
-our $versionNumber = '3.4.3';
-our $versionDate = '2018-06-08';
+our $versionNumber = '3.5';
+our $versionDate = '2018-08-13';
1
Modified: trunk/Master/texmf-dist/scripts/latexindent/defaultSettings.yaml
===================================================================
--- trunk/Master/texmf-dist/scripts/latexindent/defaultSettings.yaml 2018-08-14 22:01:02 UTC (rev 48401)
+++ trunk/Master/texmf-dist/scripts/latexindent/defaultSettings.yaml 2018-08-14 22:01:47 UTC (rev 48402)
@@ -1,4 +1,4 @@
-# defaultSettings.yaml for latexindent.pl, version 3.4.3, 2018-06-08
+# defaultSettings.yaml for latexindent.pl, version 3.5, 2018-08-13
# a script that aims to
# beautify .tex, .sty, .cls files
#
@@ -394,12 +394,11 @@
modifyLineBreaks:
preserveBlankLines: 1
condenseMultipleBlankLinesInto: 1
- textWrapOptions:
- columns: 0
- separator: ""
oneSentencePerLine:
manipulateSentences: 0
removeSentenceLineBreaks: 1
+ textWrapSentences: 0
+ sentenceIndent: ""
sentencesFollow:
par: 1
blankLine: 1
@@ -419,8 +418,26 @@
exclamationMark: 1
questionMark: 1
other: 0
+ textWrapOptions:
+ columns: 0
+ separator: ""
+ perCodeBlockBasis: 0
+ all: 0
+ alignAtAmpersandTakesPriority: 1
+ environments:
+ quotation: 0
+ ifElseFi: 0
+ optionalArguments: 0
+ mandatoryArguments: 0
+ items: 0
+ specialBeginEnd: 0
+ afterHeading: 0
+ preamble: 0
+ filecontents: 0
+ masterDocument: 0
removeParagraphLineBreaks:
all: 0
+ beforeTextWrap: 0
alignAtAmpersandTakesPriority: 1
environments:
quotation: 0
@@ -430,10 +447,12 @@
items: 0
specialBeginEnd: 0
afterHeading: 0
+ preamble: 0
filecontents: 0
masterDocument: 0
paragraphsStopAt:
environments: 1
+ verbatim: 1
commands: 0
ifElseFi: 0
items: 0
Modified: trunk/Master/texmf-dist/scripts/latexindent/latexindent.pl
===================================================================
(Binary files differ)
More information about the tex-live-commits
mailing list