summaryrefslogtreecommitdiff
path: root/support/latexindent/documentation/sec-introduction.tex
diff options
context:
space:
mode:
Diffstat (limited to 'support/latexindent/documentation/sec-introduction.tex')
-rw-r--r--support/latexindent/documentation/sec-introduction.tex216
1 files changed, 108 insertions, 108 deletions
diff --git a/support/latexindent/documentation/sec-introduction.tex b/support/latexindent/documentation/sec-introduction.tex
index 8812e106b9..d0b0e2012f 100644
--- a/support/latexindent/documentation/sec-introduction.tex
+++ b/support/latexindent/documentation/sec-introduction.tex
@@ -1,137 +1,137 @@
% arara: pdflatex: { 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.
+ \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:
- \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
- 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
- complete minimum working example as I would like to improve the code as much as possible.
+ 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
+ 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
+ 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 out on the
- sample files in the \texttt{test-case} directory \cite{latexindent-home}.
- \index{warning!be sure to test before use}
- \end{warning}
+ \begin{warning}
+ Before you try the script on anything important (like your thesis), test it out on the
+ sample files in the \texttt{test-case} directory \cite{latexindent-home}.
+ \index{warning!be sure to test before use}
+ \end{warning}
- \emph{If you have used any version 2.* of \texttt{latexindent.pl}, there
- are a few changes to the interface; see \vref{app:differences} and the comments
- throughout this document for details}.
+ \emph{If you have used any version 2.* of \texttt{latexindent.pl}, there
+ are a few changes to the interface; see \vref{app:differences} and the comments
+ 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:
+ The different listings are presented using different styles:
- \begin{minipage}{.4\textwidth}
- \cmhlistingsfromfile{demonstrations/demo-tex.tex}{\texttt{demo-tex.tex}}{lst:demo-tex}
- \end{minipage}%
- \hfill
- \begin{minipage}{.4\textwidth}
- This type of listing is a \texttt{.tex} file.
- \end{minipage}%
+ \begin{minipage}{.4\textwidth}
+ \cmhlistingsfromfile{demonstrations/demo-tex.tex}{\texttt{demo-tex.tex}}{lst:demo-tex}
+ \end{minipage}%
+ \hfill
+ \begin{minipage}{.4\textwidth}
+ This type of listing is a \texttt{.tex} file.
+ \end{minipage}%
- \begin{minipage}{.4\textwidth}
- \cmhlistingsfromfile[style=fileExtensionPreference]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{fileExtensionPreference}}{lst:fileExtensionPreference-demo}
- \end{minipage}%
- \hfill
- \begin{minipage}{.4\textwidth}
- This type of listing is a \texttt{.yaml} file; when you see line numbers given (as here)
- it means that the snippet is taken directly from \texttt{defaultSettings.yaml}, discussed in
- detail in \vref{sec:defuseloc}.
- \end{minipage}%
+ \begin{minipage}{.4\textwidth}
+ \cmhlistingsfromfile[style=fileExtensionPreference]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{fileExtensionPreference}}{lst:fileExtensionPreference-demo}
+ \end{minipage}%
+ \hfill
+ \begin{minipage}{.4\textwidth}
+ This type of listing is a \texttt{.yaml} file; when you see line numbers given (as here)
+ it means that the snippet is taken directly from \texttt{defaultSettings.yaml}, discussed in
+ detail in \vref{sec:defuseloc}.
+ \end{minipage}%
- \begin{minipage}{.55\textwidth}
- \cmhlistingsfromfile[style=modifylinebreaks]{../defaultSettings.yaml}[MLB-TCB,width=.85\linewidth,before=\centering]{\texttt{modifyLineBreaks}}{lst:modifylinebreaks-demo}
- \end{minipage}%
- \hfill
- \begin{minipage}{.4\textwidth}
- This type of listing is a \texttt{.yaml} file, but it will only
- be relevant when the \texttt{-m} switch is active; see \vref{sec:modifylinebreaks}
- for more details.
- \end{minipage}%
+ \begin{minipage}{.55\textwidth}
+ \cmhlistingsfromfile[style=modifylinebreaks]{../defaultSettings.yaml}[MLB-TCB,width=.85\linewidth,before=\centering]{\texttt{modifyLineBreaks}}{lst:modifylinebreaks-demo}
+ \end{minipage}%
+ \hfill
+ \begin{minipage}{.4\textwidth}
+ This type of listing is a \texttt{.yaml} file, but it will only
+ be relevant when the \texttt{-m} switch is active; see \vref{sec:modifylinebreaks}
+ for more details.
+ \end{minipage}%
- \begin{minipage}{.55\textwidth}
- \cmhlistingsfromfile[style=replacements]{../defaultSettings.yaml}[replace-TCB,width=.85\linewidth,before=\centering]{\texttt{replacements}}{lst:replacements-demo}
- \end{minipage}%
- \hfill
- \begin{minipage}{.4\textwidth}
- This type of listing is a \texttt{.yaml} file, but it will only
- be relevant when the \texttt{-r} switch is active; see \vref{sec:replacements}
- for more details.
- \end{minipage}%
+ \begin{minipage}{.55\textwidth}
+ \cmhlistingsfromfile[style=replacements]{../defaultSettings.yaml}[replace-TCB,width=.85\linewidth,before=\centering]{\texttt{replacements}}{lst:replacements-demo}
+ \end{minipage}%
+ \hfill
+ \begin{minipage}{.4\textwidth}
+ This type of listing is a \texttt{.yaml} file, but it will only
+ be relevant when the \texttt{-r} switch is active; see \vref{sec:replacements}
+ for more details.
+ \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% % \end{latexonly}
+ % \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% % \end{latexonly}
\subsection{Quick start}\label{sec:quickstart}
- If you'd like to get started with \texttt{latexindent.pl} then simply type
- \begin{commandshell}
+ If you'd like to get started with \texttt{latexindent.pl} then simply type
+ \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.
- \begin{cmhlistings}[style=tcblatex,language=Perl]{Possible error messages}{lst:poss-errors}
+ 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.
- \begin{commandshell}
+ \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}.
\subsection{A word about regular expressions}
- \index{regular expressions!a word about}
- As you read this documentation, you may encounter the term \emph{regular expressions}.
- I've tried to write this documentation in such a way so as to allow you to engage with
- them or not, as you prefer. This documentation is not designed to be a guide to regular
- expressions, and if you'd like to read about them, I recommend \cite{masteringregexp}.
+ \index{regular expressions!a word about}
+ As you read this documentation, you may encounter the term \emph{regular expressions}.
+ I've tried to write this documentation in such a way so as to allow you to engage with
+ them or not, as you prefer. This documentation is not designed to be a guide to regular
+ expressions, and if you'd like to read about them, I recommend \cite{masteringregexp}.