summaryrefslogtreecommitdiff
path: root/support/latexindent/documentation/sec-fine-tuning.tex
diff options
context:
space:
mode:
Diffstat (limited to 'support/latexindent/documentation/sec-fine-tuning.tex')
-rw-r--r--support/latexindent/documentation/sec-fine-tuning.tex81
1 files changed, 81 insertions, 0 deletions
diff --git a/support/latexindent/documentation/sec-fine-tuning.tex b/support/latexindent/documentation/sec-fine-tuning.tex
index 669bff5737..47c186eabb 100644
--- a/support/latexindent/documentation/sec-fine-tuning.tex
+++ b/support/latexindent/documentation/sec-fine-tuning.tex
@@ -230,3 +230,84 @@ latexindent.pl -m finetuning4.tex -o=+-mod3 -l=href3
is an example of character class.
\index{regular expressions!character class demonstration}
\end{example}
+
+ \begin{example}
+ We can use the \texttt{fineTuning} field to assist in the formatting of bibliography files.
+ \index{bibliography files}
+ \index{regular expressions!delimiterRegEx}
+ \index{regular expressions!capturing parenthesis}
+ \index{regular expressions!ampersand alignment}
+ \index{delimiters!delimiterRegEx}
+
+ Starting with the file in \cref{lst:bib1} and running the command
+ \begin{commandshell}
+latexindent.pl bib1.tex -o=+-mod1
+ \end{commandshell}
+ gives the output in \cref{lst:bib1-mod1}.
+
+ \begin{widepage}
+ \begin{cmhtcbraster}[raster column skip=.01\linewidth]
+ \cmhlistingsfromfile{demonstrations/bib1.bib}{\texttt{bib1.bib}}{lst:bib1}
+ \cmhlistingsfromfile{demonstrations/bib1-mod1.bib}{\texttt{bib1-mod1.bib}}{lst:bib1-mod1}
+ \end{cmhtcbraster}
+ \end{widepage}
+
+ Let's assume that we would like to format the output so as to align the \texttt{=} symbols.
+ Using the settings in \cref{lst:bibsettings1} and running the command
+ \begin{commandshell}
+latexindent.pl bib1.bib -l bibsettings1.yaml -o=+-mod2
+ \end{commandshell}
+ gives the output in \cref{lst:bib1-mod2}.
+
+ \begin{widepage}
+ \begin{cmhtcbraster}[raster column skip=.1\linewidth]
+ \cmhlistingsfromfile{demonstrations/bib1-mod2.bib}{\texttt{bib1.bib} using \cref{lst:bibsettings1}}{lst:bib1-mod2}
+ \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/bibsettings1.yaml}[yaml-TCB]{\texttt{bibsettings1.yaml}}{lst:bibsettings1}
+ \end{cmhtcbraster}
+ \end{widepage}
+ Some notes about \cref{lst:bibsettings1}:
+ \begin{itemize}
+ \item we have populated the \texttt{lookForAlignDelims} field with the \texttt{online} command,
+ and have used the \texttt{delimiterRegEx}, discussed in \vref{sec:delimiter-reg-ex};
+ \item we have tweaked the \texttt{keyEqualsValuesBracesBrackets} code block so that it will
+ \emph{not} be found following a comma; this means that, in contrast to the default
+ behaviour, the lines such as \lstinline!date={2013-05-23},! will \emph{not} be treated as
+ key-equals-value braces;
+ \item the adjustment to \texttt{keyEqualsValuesBracesBrackets} necessitates the associated
+ change to the \texttt{UnNamedGroupingBracesBrackets} field so that they will be searched
+ for following \texttt{=} symbols.
+ \end{itemize}
+ \end{example}
+
+ \begin{example}
+ We can build upon \cref{lst:bibsettings1} for slightly more complicated bibliography files.
+
+ Starting with the file in \cref{lst:bib2} and running the command
+ \begin{commandshell}
+latexindent.pl bib2.bib -l bibsettings1.yaml -o=+-mod1
+ \end{commandshell}
+ gives the output in \cref{lst:bib2-mod1}.
+
+ \begin{widepage}
+ \cmhlistingsfromfile{demonstrations/bib2.bib}{\texttt{bib2.bib}}{lst:bib2}
+ \cmhlistingsfromfile{demonstrations/bib2-mod1.bib}{\texttt{bib2-mod1.bib}}{lst:bib2-mod1}
+ \end{widepage}
+
+ The output in \cref{lst:bib2-mod1} is not ideal, as the \texttt{=} symbol within the url
+ field has been incorrectly used as an alignment delimiter.
+
+ We address this by tweaking the \texttt{delimiterRegEx} field in \cref{lst:bibsettings2}.
+
+ \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/bibsettings2.yaml}[yaml-TCB]{\texttt{bibsettings2.yaml}}{lst:bibsettings2}
+
+ Upon running the command
+ \begin{commandshell}
+latexindent.pl bib2.bib -l bibsettings1.yaml,bibsettings2.yaml -o=+-mod2
+ \end{commandshell}
+ we receive the \emph{desired} output in \cref{lst:bib2-mod2}.
+
+ \cmhlistingsfromfile{demonstrations/bib2-mod2.bib}{\texttt{bib2-mod2.bib}}{lst:bib2-mod2}
+
+ With reference to \cref{lst:bibsettings2} we note that the \texttt{delimiterRegEx} has been adjusted so that \texttt{=} symbols are used as the delimiter,
+ but only when they are \emph{not preceeded} by either \texttt{v} or \texttt{spfreload}.
+ \end{example}