summaryrefslogtreecommitdiff
path: root/support/latexindent/documentation/sec-appendices.tex
diff options
context:
space:
mode:
Diffstat (limited to 'support/latexindent/documentation/sec-appendices.tex')
-rw-r--r--support/latexindent/documentation/sec-appendices.tex837
1 files changed, 428 insertions, 409 deletions
diff --git a/support/latexindent/documentation/sec-appendices.tex b/support/latexindent/documentation/sec-appendices.tex
index 2b3c9ecccc..9238c242a0 100644
--- a/support/latexindent/documentation/sec-appendices.tex
+++ b/support/latexindent/documentation/sec-appendices.tex
@@ -1,13 +1,13 @@
% arara: pdflatex: { 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}.
-
- \begin{cmhlistings}[style=tcblatex,language=Perl]{\texttt{helloworld.pl}}{lst:helloworld}
+ \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}.
+
+ \begin{cmhlistings}[style=tcblatex,language=Perl]{\texttt{helloworld.pl}}{lst:helloworld}
#!/usr/bin/perl
use strict;
@@ -30,29 +30,29 @@ print "hello world";
exit;
\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
- \begin{commandshell}
+ \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
+ \begin{commandshell}
perl latexindent-module-installer.pl
\end{commandshell}
- or
- \begin{dosprompt}
+ or
+ \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.
-
- \subsection{Manually installing 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.
-
- \subsubsection{Linux}
- \paragraph{perlbrew}
- Linux users may be interested in exploring Perlbrew \cite{perlbrew}; an example
- installation would be:
- \begin{commandshell}
+ then, once you have answered \texttt{Y}, the appropriate modules will be installed onto
+ your distribution.
+
+ \subsection{Manually installing 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.
+
+ \subsubsection{Linux}
+ \paragraph{perlbrew}
+ Linux users may be interested in exploring Perlbrew \cite{perlbrew}; an example
+ installation would be:
+ \begin{commandshell}
sudo apt-get install perlbrew
perlbrew init
perlbrew install perl-5.28.1
@@ -62,45 +62,45 @@ curl -L http://cpanmin.us | perl - App::cpanminus
cpanm YAML::Tiny
cpanm File::HomeDir
\end{commandshell}
- \index{cpan}
+ \index{cpan}
- \paragraph{Ubuntu/Debian}
- For other distributions, the Ubuntu/Debian approach may work as follows
- \begin{commandshell}
+ \paragraph{Ubuntu/Debian}
+ For other distributions, the Ubuntu/Debian approach may work as follows
+ \begin{commandshell}
sudo apt install perl
sudo cpan -i App::cpanminus
sudo cpanm YAML::Tiny
sudo cpanm File::HomeDir
\end{commandshell}
- or else by running, for example,
- \begin{commandshell}
+ or else by running, for example,
+ \begin{commandshell}
sudo perl -MCPAN -e'install "File::HomeDir"'
\end{commandshell}
- \paragraph{Ubuntu: using the texlive from apt-get}
- Ubuntu users that install texlive using \texttt{apt-get} as in the following
- \begin{commandshell}
+ \paragraph{Ubuntu: using the texlive from apt-get}
+ Ubuntu users that install texlive using \texttt{apt-get} as in the following
+ \begin{commandshell}
sudo apt install texlive
sudo apt install texlive-latex-recommended
\end{commandshell}
- may need the following additional command to work with \texttt{latexindent.pl}
- \begin{commandshell}
+ may need the following additional command to work with \texttt{latexindent.pl}
+ \begin{commandshell}
sudo apt install texlive-extra-utils
\end{commandshell}
- \paragraph{Arch-based distributions}
- First install the dependencies
- \begin{commandshell}
+ \paragraph{Arch-based distributions}
+ First install the dependencies
+ \begin{commandshell}
sudo pacman -S perl cpanminus
\end{commandshell}
- then run the latexindent-module-installer.pl file located at helper-scripts/
+ then run the latexindent-module-installer.pl file located at helper-scripts/
- \paragraph{Alpine}
- If you are using Alpine, some \texttt{Perl} modules are not build-compatible with Alpine,
- but replacements are available through \texttt{apk}. For example, you might use the
- commands given in \cref{lst:alpine-install}; thanks to \cite{jun-sheaf} for providing
- these details.
+ \paragraph{Alpine}
+ If you are using Alpine, some \texttt{Perl} modules are not build-compatible with Alpine,
+ but replacements are available through \texttt{apk}. For example, you might use the
+ commands given in \cref{lst:alpine-install}; thanks to \cite{jun-sheaf} for providing
+ these details.
- \begin{cmhlistings}[style=tcblatex,language=Bash]{\texttt{alpine-install.sh}}{lst:alpine-install}
+ \begin{cmhlistings}[style=tcblatex,language=Bash]{\texttt{alpine-install.sh}}{lst:alpine-install}
# Installing perl
apk --no-cache add miniperl perl-utils
@@ -124,13 +124,13 @@ cpanm -n Params::ValidationCompiler
cpanm -n YAML::Tiny
\end{cmhlistings}
- Users of NixOS might like to see
- \href{https://github.com/cmhughes/latexindent.pl/issues/222}{https://github.com/cmhughes/latexindent.pl/issues/222}
- for tips.
- \subsubsection{Mac}
- Users of the Macintosh operating system might like to explore the following commands, for
- example:
- \begin{commandshell}
+ Users of NixOS might like to see
+ \href{https://github.com/cmhughes/latexindent.pl/issues/222}{https://github.com/cmhughes/latexindent.pl/issues/222}
+ for tips.
+ \subsubsection{Mac}
+ Users of the Macintosh operating system might like to explore the following commands, for
+ example:
+ \begin{commandshell}
brew install perl
brew install cpanm
@@ -138,246 +138,246 @@ cpanm YAML::Tiny
cpanm File::HomeDir
\end{commandshell}
- \subsubsection{Windows}
- Strawberry Perl users on Windows might use \texttt{CPAN client}. All of the modules are
- readily available on CPAN \cite{cpan}.
+ \subsubsection{Windows}
+ 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
- \begin{dosprompt}
+ \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
+ \begin{dosprompt}
latexindent.exe -t myfile.tex
\end{dosprompt}
- \subsection{The GCString switch}\label{subsec:the-GCString}
- If you find that the \texttt{lookForAlignDelims} (as in \cref{subsec:align-at-delimiters}) does not work correctly
- for your language, then you may with to use the \texttt{Unicode::GCString} module \announce*{2022-03-25}{Unicode::GCString}.
- \index{perl!Unicode GCString module}
- \index{switches!--GCString demonstration}
+ \subsection{The GCString switch}\label{subsec:the-GCString}
+ If you find that the \texttt{lookForAlignDelims} (as in \cref{subsec:align-at-delimiters}) does not work correctly
+ for your language, then you may with to use the \texttt{Unicode::GCString} module \announce*{2022-03-25}{Unicode::GCString}.
+ \index{perl!Unicode GCString module}
+ \index{switches!--GCString demonstration}
- This can be loaded by calling \texttt{latexindent.pl} with the \texttt{GCString} switch
- as in
- \begin{commandshell}
+ This can be loaded by calling \texttt{latexindent.pl} with the \texttt{GCString} switch
+ as in
+ \begin{commandshell}
latexindent.pl --GCString myfile.tex
\end{commandshell}
- In this case, you will need to have the \texttt{Unicode::GCString} installed in your
- \texttt{perl} distribution by using, for example,
- \begin{commandshell}
+ In this case, you will need to have the \texttt{Unicode::GCString} installed in your
+ \texttt{perl} distribution by using, for example,
+ \begin{commandshell}
cpanm YAML::Tiny
\end{commandshell}
- Note: this switch does \emph{nothing} for \texttt{latexindent.exe} which loads the module
- by default. Users of \texttt{latexindent.exe} should not see any difference in behaviour
- whether they use this switch or not, as \texttt{latexindent.exe} loads the
- \texttt{Unicode::GCString} module.
-
- \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}.
- \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 run
- \begin{commandshell}
+ Note: this switch does \emph{nothing} for \texttt{latexindent.exe} which loads the module
+ by default. Users of \texttt{latexindent.exe} should not see any difference in behaviour
+ whether they use this switch or not, as \texttt{latexindent.exe} loads the
+ \texttt{Unicode::GCString} module.
+
+ \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}.
+ \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 run
+ \begin{commandshell}
ls /usr/local/bin
\end{commandshell}
- to see what is \emph{currently} in there;
- \item run the following commands
- \begin{commandshell}
+ to see what is \emph{currently} in there;
+ \item run the following commands
+ \begin{commandshell}
sudo apt-get update
sudo apt-get install --no-install-recommends cmake make # or any other generator
mkdir build && cd build
cmake ../path-helper-files
sudo make install
\end{commandshell}
- \item run
- \begin{commandshell}
+ \item run
+ \begin{commandshell}
ls /usr/local/bin
\end{commandshell}
- 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}
+ 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}
sudo make uninstall
\end{commandshell}
- \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;
- \begin{dosprompt}
+ \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;
+ \begin{dosprompt}
echo %path%
\end{dosprompt}
- \item right click on \texttt{add-to-path.bat} and \emph{Run as administrator};
- \item log out, and log back in;
- \item open a command prompt and run
- \begin{dosprompt}
+ \item right click on \texttt{add-to-path.bat} and \emph{Run as administrator};
+ \item log out, and log back in;
+ \item open a command prompt and run
+ \begin{dosprompt}
echo %path%
\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 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.
- \section{Batches of files}\label{sec:batches}
+ \section{Batches of files}\label{sec:batches}
- You can \announce*{2022-03-25}{batches of files details} instruct \texttt{latexindent.pl}
- to operate on multiple files. For example, the following calls are all valid
- \begin{commandshell}
+ You can \announce*{2022-03-25}{batches of files details} instruct \texttt{latexindent.pl}
+ to operate on multiple files. For example, the following calls are all valid
+ \begin{commandshell}
latexindent.pl myfile1.tex
latexindent.pl myfile1.tex myfile2.tex
latexindent.pl myfile*.tex
\end{commandshell}
- We note the following features of the script in relation to the switches detailed in
- \cref{sec:how:to:use}.
+ We note the following features of the script in relation to the switches detailed in
+ \cref{sec:how:to:use}.
- \subsection{location of indent.log}
- If the \texttt{-c} switch is \emph{not} active, then \texttt{indent.log} goes to the directory of the final file called.
+ \subsection{location of indent.log}
+ If the \texttt{-c} switch is \emph{not} active, then \texttt{indent.log} goes to the directory of the final file called.
- If the \texttt{-c} switch \emph{is} active, then \texttt{indent.log} goes to the
- specified directory.
+ If the \texttt{-c} switch \emph{is} active, then \texttt{indent.log} goes to the
+ specified directory.
- \subsection{interaction with -w switch}
- If the \texttt{-w} switch is active, as in
- \begin{commandshell}
+ \subsection{interaction with -w switch}
+ If the \texttt{-w} switch is active, as in
+ \begin{commandshell}
latexindent.pl -w myfile*.tex
\end{commandshell}
- then files will be overwritten individually. Back-up files can be re-directed via the
- \texttt{-c} switch.
+ then files will be overwritten individually. Back-up files can be re-directed via the
+ \texttt{-c} switch.
- \subsection{interaction with -o switch}
- If \texttt{latexindent.pl} is called using the \texttt{-o} switch as in
- \begin{commandshell}
+ \subsection{interaction with -o switch}
+ If \texttt{latexindent.pl} is called using the \texttt{-o} switch as in
+ \begin{commandshell}
latexindent.pl myfile*.tex -o=my-output-file.tex
\end{commandshell}
- and there are multiple files to operate upon, then the \texttt{-o} switch is ignored
- because there is only \emph{one} output file specified.
+ and there are multiple files to operate upon, then the \texttt{-o} switch is ignored
+ because there is only \emph{one} output file specified.
- More generally, if the \texttt{-o} switch does \emph{not} have a \texttt{+} symbol at the
- beginning, then the \texttt{-o} switch will be ignored, and is turned it off.
+ More generally, if the \texttt{-o} switch does \emph{not} have a \texttt{+} symbol at the
+ beginning, then the \texttt{-o} switch will be ignored, and is turned it off.
- For example
- \begin{commandshell}
+ For example
+ \begin{commandshell}
latexindent.pl myfile*.tex -o=+myfile
\end{commandshell}
- \emph{will} work fine because \emph{each} \texttt{.tex} file will output to
- \texttt{<basename>myfile.tex}
+ \emph{will} work fine because \emph{each} \texttt{.tex} file will output to
+ \texttt{<basename>myfile.tex}
- Similarly,
- \begin{commandshell}
+ Similarly,
+ \begin{commandshell}
latexindent.pl myfile*.tex -o=++
\end{commandshell}
- \emph{will} work because the `existence check/incrementation' routine will be applied.
+ \emph{will} work because the `existence check/incrementation' routine will be applied.
- \subsection{interaction with lines switch}
- This behaves as expected by attempting to operate on the line numbers specified for each file. See
- the examples in \cref{sec:line-switch}.
+ \subsection{interaction with lines switch}
+ This behaves as expected by attempting to operate on the line numbers specified for each file. See
+ the examples in \cref{sec:line-switch}.
- \subsection{interaction with check switches}
- The exit codes for \texttt{latexindent.pl} are given in \vref{tab:exit-codes}.
+ \subsection{interaction with check switches}
+ The exit codes for \texttt{latexindent.pl} are given in \vref{tab:exit-codes}.
- When operating on multiple files with the check switch active, as in
- \begin{commandshell}
+ When operating on multiple files with the check switch active, as in
+ \begin{commandshell}
latexindent.pl myfile*.tex --check
\end{commandshell}
- then
- \begin{itemize}
- \item exit code 0 means that the text from \emph{none} of the files has been changed;
- \item exit code 1 means that the text from \emph{at least one} of the files been file changed.
- \end{itemize}
-
- The interaction with \texttt{checkv} switch is as in the check switch, but with verbose
- output.
-
- \subsection{when a file does not exist}
- What happens if one of the files can not be operated upon?
- \begin{itemize}
- \item if at least one of the files does not exist and \texttt{latexindent.pl} has been called
- to act upon multiple files, then the exit code is 3; note that \texttt{latexindent.pl}
- will try to operate on each file that it is called upon, and will not exit with a fatal
- message in this case;
- \item if at least one of the files can not be read and \texttt{latexindent.pl} has been called
- to act upon multiple files, then the exit code is 4; note that \texttt{latexindent.pl}
- will try to operate on each file that it is called upon, and will not exit with a fatal
- message in this case;
- \item if \texttt{latexindent.pl} has been told to operate on multiple files, and some do not
- exist and some cannot be read, then the exit code will be either 3 or 4, depending upon
- which it scenario it encountered most recently.
- \end{itemize}
-
- \section{latexindent-yaml-schema.json}
-
- \texttt{latexindent.pl}
- \announce{2022-01-02}{latexindent-yaml-schema.json} ships with
- \texttt{latexindent-yaml-schema.json}
- which might help you when constructing your YAML files.
- \index{json!schema for YAML files}
-
- \subsection{VSCode demonstration}
- To use \texttt{latexindent-yaml-schema.json} with \texttt{VSCode}, you can use the
- following steps: \index{VSCode} \index{json!VSCode}
- \begin{enumerate}
- \item download \texttt{latexindent-yaml-schema.json} from the \texttt{documentation} folder of
- \cite{latexindent-home}, save it in whichever directory you would like, noting it for
- reference;
- \item following the instructions from \cite{vscode-yaml-demo}, for example, you should install
- the VSCode YAML extension \cite{vscode-yaml-extentions};
- \item set up your \texttt{settings.json} file using the directory you saved the file by
- adapting \cref{lst:settings.json}; on my Ubuntu laptop this file lives at
- \texttt{/home/cmhughes/.config/Code/User/settings.json}.
- \end{enumerate}
-
- \begin{widepage}
- \cmhlistingsfromfile{demonstrations/settings.json}[yaml-TCB]{\texttt{settings.json}}{lst:settings.json}
- \end{widepage}
-
- Alternatively, if you would prefer not to download the json file, you might be able to
- use an adapted version of \cref{lst:settings-alt.json}.
-
- \begin{widepage}
- \cmhlistingsfromfile{demonstrations/settings-alt.json}[yaml-TCB]{\texttt{settings-alt.json}}{lst:settings-alt.json}
- \end{widepage}
-
- Finally, if your TeX distribution is up to date, then
- \texttt{latexindent-yaml-schema.json} \emph{should} be in the documentation folder of
- your installation, so an adapted version of \cref{lst:settings-alt1.json} may work.
-
- \begin{widepage}
- \cmhlistingsfromfile{demonstrations/settings-alt1.json}[yaml-TCB]{\texttt{settings-alt1.json}}{lst:settings-alt1.json}
- \end{widepage}
-
- If you have details of how to implement this schema in other editors, please feel
- encouraged to contribute to this documentation.
-
- \section{Using conda}\label{sec:app:conda}
- If you use conda you'll only need
- \begin{commandshell}
+ then
+ \begin{itemize}
+ \item exit code 0 means that the text from \emph{none} of the files has been changed;
+ \item exit code 1 means that the text from \emph{at least one} of the files been file changed.
+ \end{itemize}
+
+ The interaction with \texttt{checkv} switch is as in the check switch, but with verbose
+ output.
+
+ \subsection{when a file does not exist}
+ What happens if one of the files can not be operated upon?
+ \begin{itemize}
+ \item if at least one of the files does not exist and \texttt{latexindent.pl} has been called
+ to act upon multiple files, then the exit code is 3; note that \texttt{latexindent.pl}
+ will try to operate on each file that it is called upon, and will not exit with a fatal
+ message in this case;
+ \item if at least one of the files can not be read and \texttt{latexindent.pl} has been called
+ to act upon multiple files, then the exit code is 4; note that \texttt{latexindent.pl}
+ will try to operate on each file that it is called upon, and will not exit with a fatal
+ message in this case;
+ \item if \texttt{latexindent.pl} has been told to operate on multiple files, and some do not
+ exist and some cannot be read, then the exit code will be either 3 or 4, depending upon
+ which it scenario it encountered most recently.
+ \end{itemize}
+
+ \section{latexindent-yaml-schema.json}
+
+ \texttt{latexindent.pl}
+ \announce{2022-01-02}{latexindent-yaml-schema.json} ships with
+ \texttt{latexindent-yaml-schema.json}
+ which might help you when constructing your YAML files.
+ \index{json!schema for YAML files}
+
+ \subsection{VSCode demonstration}
+ To use \texttt{latexindent-yaml-schema.json} with \texttt{VSCode}, you can use the
+ following steps: \index{VSCode} \index{json!VSCode}
+ \begin{enumerate}
+ \item download \texttt{latexindent-yaml-schema.json} from the \texttt{documentation} folder of
+ \cite{latexindent-home}, save it in whichever directory you would like, noting it for
+ reference;
+ \item following the instructions from \cite{vscode-yaml-demo}, for example, you should install
+ the VSCode YAML extension \cite{vscode-yaml-extentions};
+ \item set up your \texttt{settings.json} file using the directory you saved the file by
+ adapting \cref{lst:settings.json}; on my Ubuntu laptop this file lives at
+ \texttt{/home/cmhughes/.config/Code/User/settings.json}.
+ \end{enumerate}
+
+ \begin{widepage}
+ \cmhlistingsfromfile{demonstrations/settings.json}[yaml-TCB]{\texttt{settings.json}}{lst:settings.json}
+ \end{widepage}
+
+ Alternatively, if you would prefer not to download the json file, you might be able to
+ use an adapted version of \cref{lst:settings-alt.json}.
+
+ \begin{widepage}
+ \cmhlistingsfromfile{demonstrations/settings-alt.json}[yaml-TCB]{\texttt{settings-alt.json}}{lst:settings-alt.json}
+ \end{widepage}
+
+ Finally, if your TeX distribution is up to date, then
+ \texttt{latexindent-yaml-schema.json} \emph{should} be in the documentation folder of
+ your installation, so an adapted version of \cref{lst:settings-alt1.json} may work.
+
+ \begin{widepage}
+ \cmhlistingsfromfile{demonstrations/settings-alt1.json}[yaml-TCB]{\texttt{settings-alt1.json}}{lst:settings-alt1.json}
+ \end{widepage}
+
+ If you have details of how to implement this schema in other editors, please feel
+ encouraged to contribute to this documentation.
+
+ \section{Using conda}\label{sec:app:conda}
+ If you use conda you'll only need
+ \begin{commandshell}
conda install latexindent.pl -c conda-forge
\end{commandshell}
- this will install the executable and all its dependencies (including perl) in the
- activate environment. You don't even have to worry about \texttt{defaultSettings.yaml} as
- it included too, you can thus skip \cref{sec:requiredmodules,sec:updating-path}.
- \index{conda}
+ this will install the executable and all its dependencies (including perl) in the
+ activate environment. You don't even have to worry about \texttt{defaultSettings.yaml} as
+ it included too, you can thus skip \cref{sec:requiredmodules,sec:updating-path}.
+ \index{conda}
- You can get a conda installation for example from \cite{conda} or from \cite{anacoda}.
+ You can get a conda installation for example from \cite{conda} or from \cite{anacoda}.
- \subsection{Sample conda installation on Ubuntu}
- On Ubuntu I followed the 64-bit installation instructions at \cite{condainstallubuntu}
- and then I ran the following commands:
- \begin{commandshell}
+ \subsection{Sample conda installation on Ubuntu}
+ On Ubuntu I followed the 64-bit installation instructions at \cite{condainstallubuntu}
+ and then I ran the following commands:
+ \begin{commandshell}
conda create -n latexindent.pl
conda activate latexindent.pl
conda install latexindent.pl -c conda-forge
@@ -385,94 +385,113 @@ conda info --envs
conda list
conda run latexindent.pl -vv
\end{commandshell}
- I found the details given at \cite{condainstallhelp} to be helpful.
+ I found the details given at \cite{condainstallhelp} to be helpful.
- \section{pre-commit}
+ \section{pre-commit}
- Users of \texttt{.git} may be interested \announce{2022-01-21}{pre-commit for
- latexindent.pl} in exploring the \texttt{pre-commit} tool \cite{pre-commithome}, which is
- supported by \texttt{latexindent.pl}. Thank you to \cite{tdegeusprecommit} for
- contributing this feature.
+ Users of \texttt{.git} may be interested \announce{2022-01-21}{pre-commit for
+ latexindent.pl} in exploring the \texttt{pre-commit} tool \cite{pre-commithome}, which is
+ supported by \texttt{latexindent.pl}. Thank you to \cite{tdegeusprecommit} for
+ contributing this feature, and to \cite{holzhausprecommit} for their contribution to it.
- To use the \texttt{pre-commit} tool, you will need to install \texttt{pre-commit}; sample
- instructions for Ubuntu are given in \cref{sec:pre-commit-ubuntu}. Once installed, there
- are two ways to use \texttt{pre-commit}: using \texttt{CPAN} or using \texttt{conda},
- detailed in \cref{sec:pre-commit-cpan} and \cref{sec:pre-commit-conda} respectively.
+ To use the \texttt{pre-commit} tool, you will need to install \texttt{pre-commit}; sample
+ instructions for Ubuntu are given in \cref{sec:pre-commit-ubuntu}. Once installed, there
+ are two ways to use \texttt{pre-commit}: using \texttt{CPAN} or using \texttt{conda},
+ detailed in \cref{sec:pre-commit-cpan} and \cref{sec:pre-commit-conda} respectively.
- \subsection{Sample pre-commit installation on Ubuntu}\label{sec:pre-commit-ubuntu}
- On Ubuntu I ran the following command:
- \begin{commandshell}
+ \subsection{Sample pre-commit installation on Ubuntu}\label{sec:pre-commit-ubuntu}
+ On Ubuntu I ran the following command:
+ \begin{commandshell}
python3 -m pip install pre-commit
\end{commandshell}
- I then updated my path via .bashrc so that it includes the line in
- \cref{lst:bashrc-update}.
- \begin{cmhlistings}[style=tcblatex,language=Bash]{\texttt{.bashrc} update}{lst:bashrc-update}
+ I then updated my path via .bashrc so that it includes the line in
+ \cref{lst:bashrc-update}.
+ \begin{cmhlistings}[style=tcblatex,language=Bash]{\texttt{.bashrc} update}{lst:bashrc-update}
...
export PATH=$PATH:/home/cmhughes/.local/bin
\end{cmhlistings}
- \subsection{pre-commit using CPAN}\label{sec:pre-commit-cpan}
+ \subsection{pre-commit defaults}
+ The default values that are employed by \texttt{pre-commit} are shown in \cref{lst:.pre-commit-yaml-default}.
+ \index{pre-commit!default}
- To use \texttt{latexindent.pl} with \texttt{pre-commit}, create the file
- \texttt{.pre-commit-config.yaml} given in \cref{lst:.pre-commit-config.yaml-cpan} in your
- git-repository. \index{cpan} \index{git} \index{pre-commit!cpan}
+ \cmhlistingsfromfile{../.pre-commit-hooks.yaml}[yaml-TCB]{\texttt{.pre-commit-hooks.yaml} (default)}{lst:.pre-commit-yaml-default}
- \cmhlistingsfromfile{demonstrations/pre-commit-config-cpan.yaml}[yaml-TCB]{\texttt{.pre-commit-config.yaml} (cpan)}{lst:.pre-commit-config.yaml-cpan}
- Once created, you should then be able to run the following command:
- \begin{commandshell}
+ In particular, the decision has deliberately been made (in collaboration with
+ \cite{holzhausprecommit}) to have the default to employ the following switches:
+ \texttt{overwriteIfDifferent}, \texttt{silent}, \texttt{local}; this is detailed in the
+ lines that specify \texttt{args} in \cref{lst:.pre-commit-yaml-default}.
+
+ \index{pre-commit!warning}
+ \index{warning!pre-commit}
+ \begin{warning}
+ Users of \texttt{pre-commit} will, by default, have the \texttt{overwriteIfDifferent}
+ switch employed. It is assumed that such users have version control in place, and are
+ intending to overwrite their files.
+ \end{warning}
+
+ \subsection{pre-commit using CPAN}\label{sec:pre-commit-cpan}
+
+ To use \texttt{latexindent.pl} with \texttt{pre-commit}, create the file
+ \texttt{.pre-commit-config.yaml} given in \cref{lst:.pre-commit-config.yaml-cpan} in your
+ git-repository. \index{cpan} \index{git} \index{pre-commit!cpan}
+
+ \cmhlistingsfromfile{demonstrations/pre-commit-config-cpan.yaml}[yaml-TCB]{\texttt{.pre-commit-config.yaml} (cpan)}{lst:.pre-commit-config.yaml-cpan}
+ Once created, you should then be able to run the following command:
+ \begin{commandshell}
pre-commit run --all-files
\end{commandshell}
- A few notes about \cref{lst:.pre-commit-config.yaml-cpan}:
- \begin{itemize}
- \item the settings given in \cref{lst:.pre-commit-config.yaml-cpan} instruct
- \texttt{pre-commit} to use \texttt{CPAN} to get dependencies;
- \item this requires \texttt{pre-commit} and \texttt{perl} to be installed on your system;
- \item the \texttt{args} lists selected command-line options; the settings in
- \cref{lst:.pre-commit-config.yaml-cpan} are equivalent to calling
- \begin{commandshell}
+ A few notes about \cref{lst:.pre-commit-config.yaml-cpan}:
+ \begin{itemize}
+ \item the settings given in \cref{lst:.pre-commit-config.yaml-cpan} instruct
+ \texttt{pre-commit} to use \texttt{CPAN} to get dependencies;
+ \item this requires \texttt{pre-commit} and \texttt{perl} to be installed on your system;
+ \item the \texttt{args} lists selected command-line options; the settings in
+ \cref{lst:.pre-commit-config.yaml-cpan} are equivalent to calling
+ \begin{commandshell}
latexindent.pl -s myfile.tex
\end{commandshell}
- for each \texttt{.tex} file in your repository;
- \item to instruct \texttt{latexindent.pl} to overwrite the files in your repository, then you
- can update \cref{lst:.pre-commit-config.yaml-cpan} so that \texttt{args: [-s, -w]}.
- \end{itemize}
+ for each \texttt{.tex} file in your repository;
+ \item to instruct \texttt{latexindent.pl} to overwrite the files in your repository, then you
+ can update \cref{lst:.pre-commit-config.yaml-cpan} so that \texttt{args: [-s, -w]}.
+ \end{itemize}
- Naturally you can add options, or omit \texttt{-s} and \texttt{-w}, according to your
- preference.
+ Naturally you can add options, or omit \texttt{-s} and \texttt{-w}, according to your
+ preference.
- \subsection{pre-commit using conda}\label{sec:pre-commit-conda}
+ \subsection{pre-commit using conda}\label{sec:pre-commit-conda}
- You can also rely on \texttt{conda} (detailed in \cref{sec:app:conda}) instead of
- \texttt{CPAN} for all dependencies, including \texttt{latexindent.pl} itself.
- \index{conda} \index{git} \index{pre-commit!conda}
+ You can also rely on \texttt{conda} (detailed in \cref{sec:app:conda}) instead of
+ \texttt{CPAN} for all dependencies, including \texttt{latexindent.pl} itself.
+ \index{conda} \index{git} \index{pre-commit!conda}
- \cmhlistingsfromfile{demonstrations/pre-commit-config-conda.yaml}[yaml-TCB]{\texttt{.pre-commit-config.yaml} (conda)}{lst:.pre-commit-config.yaml-conda}
- Once created, you should then be able to run the following command:
- \begin{commandshell}
+ \cmhlistingsfromfile{demonstrations/pre-commit-config-conda.yaml}[yaml-TCB]{\texttt{.pre-commit-config.yaml} (conda)}{lst:.pre-commit-config.yaml-conda}
+ Once created, you should then be able to run the following command:
+ \begin{commandshell}
pre-commit run --all-files
\end{commandshell}
- A few notes about \cref{lst:.pre-commit-config.yaml-cpan}:
- \begin{itemize}
- \item the settings given in \cref{lst:.pre-commit-config.yaml-conda} instruct
- \texttt{pre-commit} to use \texttt{conda} to get dependencies;
- \item this requires \texttt{pre-commit} and \texttt{conda} to be installed on your system;
- \item the \texttt{args} lists selected command-line options; the settings in
- \cref{lst:.pre-commit-config.yaml-cpan} are equivalent to calling
- \begin{commandshell}
+ A few notes about \cref{lst:.pre-commit-config.yaml-cpan}:
+ \begin{itemize}
+ \item the settings given in \cref{lst:.pre-commit-config.yaml-conda} instruct
+ \texttt{pre-commit} to use \texttt{conda} to get dependencies;
+ \item this requires \texttt{pre-commit} and \texttt{conda} to be installed on your system;
+ \item the \texttt{args} lists selected command-line options; the settings in
+ \cref{lst:.pre-commit-config.yaml-cpan} are equivalent to calling
+ \begin{commandshell}
conda run latexindent.pl -s myfile.tex
\end{commandshell}
- for each \texttt{.tex} file in your repository;
- \item to instruct \texttt{latexindent.pl} to overwrite the files in your repository, then you
- can update \cref{lst:.pre-commit-config.yaml-cpan} so that \texttt{args: [-s, -w]}.
- \end{itemize}
-
- \subsection{pre-commit example using -l, -m switches}
- Let's consider a small example, with local \texttt{latexindent.pl} settings in
- \texttt{.latexindent.yaml}.
-
- \begin{example}
- We use the local settings given in \cref{lst:.latexindent.yaml}.
- \begin{cmhlistings}[style=tcblatex]{\texttt{.latexindent.yaml}}{lst:.latexindent.yaml}
+ for each \texttt{.tex} file in your repository;
+ \item to instruct \texttt{latexindent.pl} to overwrite the files in your repository, then you
+ can update \cref{lst:.pre-commit-config.yaml-cpan} so that \texttt{args: [-s, -w]}.
+ \end{itemize}
+
+ \subsection{pre-commit example using -l, -m switches}
+ Let's consider a small example, with local \texttt{latexindent.pl} settings in
+ \texttt{.latexindent.yaml}.
+
+ \begin{example}
+ We use the local settings given in \cref{lst:.latexindent.yaml}.
+ \begin{cmhlistings}[style=tcblatex]{\texttt{.latexindent.yaml}}{lst:.latexindent.yaml}
onlyOneBackUp: 1
modifyLineBreaks:
@@ -480,50 +499,50 @@ modifyLineBreaks:
manipulateSentences: 1
\end{cmhlistings}
- and \texttt{.pre-commit-config.yaml} as in \cref{lst:.latexindent.yaml-switches}:
+ and \texttt{.pre-commit-config.yaml} as in \cref{lst:.latexindent.yaml-switches}:
- \cmhlistingsfromfile{demonstrations/pre-commit-config-demo.yaml}[yaml-TCB]{\texttt{.pre-commit-config.yaml} (demo)}{lst:.latexindent.yaml-switches}
- Now running
- \begin{commandshell}
+ \cmhlistingsfromfile{demonstrations/pre-commit-config-demo.yaml}[yaml-TCB]{\texttt{.pre-commit-config.yaml} (demo)}{lst:.latexindent.yaml-switches}
+ Now running
+ \begin{commandshell}
pre-commit run --all-files
\end{commandshell}
- is equivalent to running
- \begin{commandshell}
+ is equivalent to running
+ \begin{commandshell}
latexindent.pl -l -m -s -w myfile.tex
\end{commandshell}
- for each \texttt{.tex} file in your repository.
-
- A few notes about \cref{lst:.latexindent.yaml-switches}:
- \begin{itemize}
- \item the \texttt{-l} option was added to use the local \texttt{.latexindent.yaml} (where it
- was specified to only create one back-up file, as \texttt{git} typically takes care of
- this when you use \texttt{pre-commit});
- \item \texttt{-m} to modify line breaks; in addition to \texttt{-s} to suppress command-line
- output, and \texttt{-w} to format files in place.
- \end{itemize}
- \end{example}
-
- \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}.
-
- \begin{minipage}{.35\linewidth}
- \cmhlistingsfromfile{demonstrations/simple.tex}{\texttt{simple.tex}}{lst:simple}
- \end{minipage}
- \hfill
- \begin{minipage}{.6\linewidth}
- \cmhlistingsfromfile{demonstrations/logfile-prefs1.yaml}[yaml-TCB]{\texttt{logfile-prefs1.yaml}}{lst:logfile-prefs1-yaml}
- \end{minipage}
-
- If we run the following command (noting that \texttt{-t} is active)
- \begin{commandshell}
+ for each \texttt{.tex} file in your repository.
+
+ A few notes about \cref{lst:.latexindent.yaml-switches}:
+ \begin{itemize}
+ \item the \texttt{-l} option was added to use the local \texttt{.latexindent.yaml} (where it
+ was specified to only create one back-up file, as \texttt{git} typically takes care of
+ this when you use \texttt{pre-commit});
+ \item \texttt{-m} to modify line breaks; in addition to \texttt{-s} to suppress command-line
+ output, and \texttt{-w} to format files in place.
+ \end{itemize}
+ \end{example}
+
+ \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}.
+
+ \begin{minipage}{.35\linewidth}
+ \cmhlistingsfromfile{demonstrations/simple.tex}{\texttt{simple.tex}}{lst:simple}
+ \end{minipage}
+ \hfill
+ \begin{minipage}{.6\linewidth}
+ \cmhlistingsfromfile{demonstrations/logfile-prefs1.yaml}[yaml-TCB]{\texttt{logfile-prefs1.yaml}}{lst:logfile-prefs1-yaml}
+ \end{minipage}
+
+ If we run the following command (noting that \texttt{-t} is active)
+ \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}.
- \begin{cmhlistings}[style=tcblatex,morekeywords={TRACE}]{\texttt{indent.log}}{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
No ancestors found for myenv
@@ -539,51 +558,51 @@ TRACE: Searching myenv for optional and mandatory arguments
... no arguments found
-----
\end{cmhlistings}
- Notice that the information given about \texttt{myenv} is `framed' using \texttt{+++++}
- and \lstinline!-----! respectively.
-
- \section{Encoding indentconfig.yaml}\label{app:encoding}
- In relation to \vref{sec:indentconfig}, Windows users that encounter encoding issues with
- \texttt{indentconfig.yaml}, may wish to run the following command in either
- \texttt{cmd.exe} or \texttt{powershell.exe}:
- \begin{dosprompt}
+ Notice that the information given about \texttt{myenv} is `framed' using \texttt{+++++}
+ and \lstinline!-----! respectively.
+
+ \section{Encoding indentconfig.yaml}\label{app:encoding}
+ In relation to \vref{sec:indentconfig}, Windows users that encounter encoding issues with
+ \texttt{indentconfig.yaml}, may wish to run the following command in either
+ \texttt{cmd.exe} or \texttt{powershell.exe}:
+ \begin{dosprompt}
chcp
\end{dosprompt}
- They may receive the following result
- \begin{dosprompt}
+ They may receive the following result
+ \begin{dosprompt}
Active code page: 936
\end{dosprompt}
- and can then use the settings given in \cref{lst:indentconfig-encoding1} within their
- \texttt{indentconfig.yaml}, where 936 is the result of the \texttt{chcp} command.
+ and can then use the settings given in \cref{lst:indentconfig-encoding1} within their
+ \texttt{indentconfig.yaml}, where 936 is the result of the \texttt{chcp} command.
- \cmhlistingsfromfile{demonstrations/encoding1.yaml}[yaml-TCB]{\texttt{encoding} demonstration for \texttt{indentconfig.yaml}}{lst:indentconfig-encoding1}
+ \cmhlistingsfromfile{demonstrations/encoding1.yaml}[yaml-TCB]{\texttt{encoding} demonstration for \texttt{indentconfig.yaml}}{lst:indentconfig-encoding1}
- \section{dos2unix linebreak adjustment}
+ \section{dos2unix linebreak adjustment}
- \yamltitle{dos2unixlinebreaks}*{integer}
- If you use \texttt{latexindent.pl} on a dos-based Windows file on Linux
- \announce{2021-06-19}{dos2unix linebreaks} then you may find that trailing horizontal
- space is not removed as you hope.
+ \yamltitle{dos2unixlinebreaks}*{integer}
+ If you use \texttt{latexindent.pl} on a dos-based Windows file on Linux
+ \announce{2021-06-19}{dos2unix linebreaks} then you may find that trailing horizontal
+ space is not removed as you hope.
- In such a case, you may wish to try setting \texttt{dos2unixlinebreaks} to 1 and
- employing, for example, the following command.
+ In such a case, you may wish to try setting \texttt{dos2unixlinebreaks} to 1 and
+ employing, for example, the following command.
- \begin{commandshell}
+ \begin{commandshell}
latexindent.pl -y="dos2unixlinebreaks:1" myfile.tex
\end{commandshell}
- See \cite{bersbersbers} for further dertails.
+ See \cite{bersbersbers} for further dertails.
- \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,
- \index{switches!-o demonstration}
- \begin{commandshell}
+ \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,
+ \index{switches!-o demonstration}
+ \begin{commandshell}
latexindent.pl -o myfile.tex outputfile.tex
\end{commandshell}
- whereas in Version 3.0 you would run any of the following, for example,
- \index{switches!-o demonstration}
- \begin{commandshell}
+ whereas in Version 3.0 you would run any of the following, for example,
+ \index{switches!-o demonstration}
+ \begin{commandshell}
latexindent.pl -o=outputfile.tex myfile.tex
latexindent.pl -o outputfile.tex myfile.tex
latexindent.pl myfile.tex -o outputfile.tex
@@ -591,43 +610,43 @@ latexindent.pl myfile.tex -o=outputfile.tex
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.
-
- 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}
-
- 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}
- \end{minipage}%
- \hfill
- \begin{minipage}{.45\textwidth}
- \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}. \index{specialBeginEnd!update to
- displaymath V3.0}
-
- \begin{minipage}{.45\textwidth}
- \cmhlistingsfromfile{demonstrations/noAddtionalIndentOld.yaml}[yaml-TCB]{\texttt{noAdditionalIndent} in Version 2.2}{lst:noAdditionalIndentOld}
- \end{minipage}%
- \hfill
- \begin{minipage}{.45\textwidth}
- \cmhlistingsfromfile{demonstrations/noAddtionalIndentNew.yaml}[yaml-TCB]{\texttt{noAdditionalIndent} for \texttt{displayMath} in Version 3.0}{lst:indentAfterThisHeadingNew1}
-
- \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}
- \hrule
-
- \hfill\itshape End\\\mbox{}\hfill\mbox{}\rlap{\hfill\includegraphics{logo}}
-
- \end{minipage}
+ 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}
+
+ 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}
+ \end{minipage}%
+ \hfill
+ \begin{minipage}{.45\textwidth}
+ \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}. \index{specialBeginEnd!update to
+ displaymath V3.0}
+
+ \begin{minipage}{.45\textwidth}
+ \cmhlistingsfromfile{demonstrations/noAddtionalIndentOld.yaml}[yaml-TCB]{\texttt{noAdditionalIndent} in Version 2.2}{lst:noAdditionalIndentOld}
+ \end{minipage}%
+ \hfill
+ \begin{minipage}{.45\textwidth}
+ \cmhlistingsfromfile{demonstrations/noAddtionalIndentNew.yaml}[yaml-TCB]{\texttt{noAdditionalIndent} for \texttt{displayMath} in Version 3.0}{lst:indentAfterThisHeadingNew1}
+
+ \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}
+ \hrule
+
+ \hfill\itshape End\\\mbox{}\hfill\mbox{}\rlap{\hfill\includegraphics{logo}}
+
+ \end{minipage}