summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/support/latexindent/sec-introduction.tex
blob: 154ea633fe5279ec25873e82e36deb60e83bc921 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
% 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.

	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}.

\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:
	\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}.
	\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}.

\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.

	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*[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}%

	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