diff options
Diffstat (limited to 'Master/texmf-dist/doc/support/latexindent/sec-introduction.tex')
-rw-r--r-- | Master/texmf-dist/doc/support/latexindent/sec-introduction.tex | 216 |
1 files changed, 108 insertions, 108 deletions
diff --git a/Master/texmf-dist/doc/support/latexindent/sec-introduction.tex b/Master/texmf-dist/doc/support/latexindent/sec-introduction.tex index 8812e106b93..d0b0e2012f5 100644 --- a/Master/texmf-dist/doc/support/latexindent/sec-introduction.tex +++ b/Master/texmf-dist/doc/support/latexindent/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}. |