summaryrefslogtreecommitdiff
path: root/support/latexindent/documentation/sec-appendices.tex
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2022-03-26 03:00:32 +0000
committerNorbert Preining <norbert@preining.info>2022-03-26 03:00:32 +0000
commitc441617a2cd82c0b0907d0106dbf047987ffd97d (patch)
tree6e98859c2dabc00a6413a5f217b93a2f9b902dfa /support/latexindent/documentation/sec-appendices.tex
parentd636f5360c4ea795ed5560ea0a7524da61c01491 (diff)
CTAN sync 202203260300
Diffstat (limited to 'support/latexindent/documentation/sec-appendices.tex')
-rw-r--r--support/latexindent/documentation/sec-appendices.tex131
1 files changed, 120 insertions, 11 deletions
diff --git a/support/latexindent/documentation/sec-appendices.tex b/support/latexindent/documentation/sec-appendices.tex
index 64f49180e9..2b3c9ecccc 100644
--- a/support/latexindent/documentation/sec-appendices.tex
+++ b/support/latexindent/documentation/sec-appendices.tex
@@ -12,9 +12,7 @@
use strict;
use warnings;
-use utf8;
use PerlIO::encoding;
-use Unicode::GCString;
use open ':std', ':encoding(UTF-8)';
use Text::Wrap;
use Text::Tabs;
@@ -63,7 +61,6 @@ sudo apt-get install curl
curl -L http://cpanmin.us | perl - App::cpanminus
cpanm YAML::Tiny
cpanm File::HomeDir
-cpanm Unicode::GCString
\end{commandshell}
\index{cpan}
@@ -74,7 +71,6 @@ sudo apt install perl
sudo cpan -i App::cpanminus
sudo cpanm YAML::Tiny
sudo cpanm File::HomeDir
-sudo cpanm Unicode::GCString
\end{commandshell}
or else by running, for example,
\begin{commandshell}
@@ -91,6 +87,12 @@ sudo apt install texlive-latex-recommended
\begin{commandshell}
sudo apt install texlive-extra-utils
\end{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/
\paragraph{Alpine}
If you are using Alpine, some \texttt{Perl} modules are not build-compatible with Alpine,
@@ -99,6 +101,7 @@ sudo apt install texlive-extra-utils
these details.
\begin{cmhlistings}[style=tcblatex,language=Bash]{\texttt{alpine-install.sh}}{lst:alpine-install}
+
# Installing perl
apk --no-cache add miniperl perl-utils
@@ -119,7 +122,6 @@ cpanm -n App::cpanminus
cpanm -n File::HomeDir
cpanm -n Params::ValidationCompiler
cpanm -n YAML::Tiny
-cpanm -n Unicode::GCString
\end{cmhlistings}
Users of NixOS might like to see
@@ -134,7 +136,6 @@ brew install cpanm
cpanm YAML::Tiny
cpanm File::HomeDir
-cpanm Unicode::GCString
\end{commandshell}
\subsubsection{Windows}
@@ -150,6 +151,28 @@ cpanm Unicode::GCString
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}
+
+ 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}
+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
@@ -208,6 +231,93 @@ echo %path%
To \emph{remove} the directory from your \lstinline!%path%!, run
\texttt{remove-from-path.bat} as administrator.
+ \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}
+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}.
+
+ \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.
+
+ \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.
+
+ \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.
+
+ 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}
+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}
+
+ Similarly,
+ \begin{commandshell}
+latexindent.pl myfile*.tex -o=++
+\end{commandshell}
+ \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 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}
+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}
@@ -279,7 +389,7 @@ conda run latexindent.pl -vv
\section{pre-commit}
- Users of \texttt{.git} may be interested \announce*{2022-01-21}{pre-commit for
+ 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.
@@ -296,7 +406,7 @@ 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}
+ \begin{cmhlistings}[style=tcblatex,language=Bash]{\texttt{.bashrc} update}{lst:bashrc-update}
...
export PATH=$PATH:/home/cmhughes/.local/bin
\end{cmhlistings}
@@ -362,7 +472,7 @@ conda run latexindent.pl -s myfile.tex
\begin{example}
We use the local settings given in \cref{lst:.latexindent.yaml}.
- \begin{cmhlistings}*[style=tcblatex]{\texttt{.latexindent.yaml}}{lst:.latexindent.yaml}
+ \begin{cmhlistings}[style=tcblatex]{\texttt{.latexindent.yaml}}{lst:.latexindent.yaml}
onlyOneBackUp: 1
modifyLineBreaks:
@@ -389,8 +499,7 @@ latexindent.pl -l -m -s -w myfile.tex
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.
+ output, and \texttt{-w} to format files in place.
\end{itemize}
\end{example}