summaryrefslogtreecommitdiff
path: root/support/arara/doc/chapters/rules.tex
diff options
context:
space:
mode:
Diffstat (limited to 'support/arara/doc/chapters/rules.tex')
-rw-r--r--support/arara/doc/chapters/rules.tex214
1 files changed, 208 insertions, 6 deletions
diff --git a/support/arara/doc/chapters/rules.tex b/support/arara/doc/chapters/rules.tex
index 759d62e133..a3f10dc2af 100644
--- a/support/arara/doc/chapters/rules.tex
+++ b/support/arara/doc/chapters/rules.tex
@@ -44,7 +44,7 @@ This rule executes the \rbox{asy} command line, referring to Asymptote, a powerf
\begin{description}
\item[\povalue{\hphantom{x}bw\hphantom{x}}] This option value, as the name suggests, converts all colors to a black and white model.
-\item[\povalue{cmyk}] This option value converts the RGB (red, green an blue) color model to the CMYK (cyan, magenta, yellow and black) counterpart.
+\item[\povalue{cmyk}] This option value converts the RGB (red, green an blue) color model to the CMYK (cyan, magenta, yellow and black) counterpart.
\item[\povalue{rgb}] This option value converts the CMYK (cyan, magenta, yellow and black) color model to the RGB (red, green an blue) counterpart.
@@ -71,7 +71,7 @@ This rule executes the \rbox{asy} command line, referring to Asymptote, a powerf
\item[\povalue{context}] This value, as the name indicates, sets the underlying \TeX\ engine to \rbox{context} for the current compilation. Note that the engine might play a major role in the generated code.
\item[\povalue{none}] This value, as the name suggests, sets the underlying \TeX\ engine to \rbox{none} for the current compilation. In this case, there will be no associated engine.
-\end{description}
+\end{description}
\item[\abox{format}] This option, as the name suggests, converts each output file to a specified format. Make sure to take a look at the Asymptote manual for further details.
@@ -134,7 +134,7 @@ This rule executes the \rbox{bib2gls} command line application which extracts gl
This rule runs \rbox{biber}, the backend bibliography processor for \rbox{biblatex}, on the corresponding base name of the \mtbox{currentFile} reference (i.e, the name without the associated extension) as a string.
\begin{description}
-\item[\rpsbox{tool}] This option sets whether the bibliography processor should be executed in \emph{tool mode}, intended for transformations and modifications of datasources. Since this mode is oriented towards a datasource rather than a document, make sure to use it alongside the \abox{options} option.
+\item[\rpsbox{tool}] This option sets whether the bibliography processor should be executed in \emph{tool mode}, intended for transformations and modifications of datasources. Since this mode is oriented towards a datasource rather than a document, make sure to use it alongside the \abox{options} option.
\item[\abox{options}] This option, as the name indicates, takes a list of raw command line options and appends it to the actual system call. An error is thrown if any data structure other than a proper list is provided as the value.
\end{description}
@@ -192,6 +192,77 @@ When in doubt, always remember that the \opbox{{-}dry-run} command line option i
% arara: clean: { extensions: [ aux, log ] }
\end{codebox}
+\item[\rulebox{context}]
+This rule runs the \rbox{context} \TeX\ engine on the provided \mtbox{currentFile} reference, generating a corresponding file in the Portable Document File format. Please refer to the user manual for further details.
+
+\begin{description}
+\item[\rpsbox{make}] This option, as the name indicates, sets whether the engine should create context formats. Please refer to the user manual for further details on this option.
+
+\item[\abox{ctx}] This option, as the name indicates, sets the \rbox{ctx} file for process management specification. Please refer to the user manual for further details on this option.
+
+\item[\abox{interface}] This option, as the name indicates, sets the specified user interface. Please refer to the user manual for further details on this option.
+
+\item[\rpsbox{autopdf}] This option, as the name indicates, closes the corresponding \rbox{pdf} file in viewer and then reopens it afterwards.
+
+\item[\abox{purge}] This option, as the name indicates, purges files according to the provided rule. Possible values are:
+
+\begin{description}
+\item[\povalue{partial}] This value, as the name suggests, purges files either or not after a proper run, defined through a pattern. Please refer to the user manual for further details.
+
+\item[\povalue{all}] This value, as the name suggests, purges all files either or not after a proper run, defined through a pattern. Please refer to the user manual for further details.
+
+\item[\povalue{result}] This value, as the name suggests, purges the resulting file before the actual run. Please refer to the user manual for further details.
+\end{description}
+
+\item[\abox{modules}] This option, as the name indicates, sets a list of modules and styles to be loaded, normally part of the distribution.
+
+\item[\abox{environments}] This option, as the name indicates, sets a list of environment files (document styles) to load first.
+
+\item[\abox{mode}] This option, as the name indicates, enables modes according to the provided list (conditional processing in styles).
+
+\item[\abox{path}] This option, as the name indicates, consults the given paths in the provided list during a file lookup.
+
+\item[\abox{arguments}] This option, as the name indicates, sets variables that can be consulted during a run. Such variables are defined as key/value pairs.
+
+\item[\abox{trackers}] This option, as the name indicates, sets the list of tracker variables. Please refer to the user manual for further details.
+
+\item[\abox{directives}] This option, as the name indicates, sets the list of directive variables. Please refer to the user manual for further details.
+
+\item[\abox{silent}] This option, as the name indicates, disables the log categories based on the provided list. Please refer to the user manual for further details.
+
+\item[\abox{errors}] This option, as the name indicates, shows errors at the end of a run and quits when it the provided list. Please refer to the user manual for further details.
+
+\item[\rpsbox{synctex}] This option sets whether \rbox{synctex}, an input and output synchronization feature that allows navigation from source to typeset material and vice versa, available in most \TeX\ engines, is activated.
+
+\item[\abox{interaction}] This option alters the underlying engine behaviour. If this option is omitted, the engine will prompt the user for interaction in the event of an error. Possible values are, in order of increasing user interaction (courtesy of our master Enrico Gregorio):
+
+\begin{description}
+\item[\povalue{batchmode}] In this mode, nothing is printed on the terminal, and errors are scrolled as if the \rbox{return} key is hit at every error. Missing files that \TeX\ tries to input or request from keyboard input cause the job to abort.
+
+\item[\povalue{nonstopmode}] In this mode, the diagnostic message will appear on the terminal, but there is no possibility of user interaction just like in batch mode, previously described.
+\end{description}
+
+\item[\abox{options}] This option, as the name indicates, takes a list of raw command line options and appends it to the actual system call. An error is thrown if any data structure other than a proper list is provided as the value.
+\end{description}
+
+\begin{codebox}{Example}{teal}{\icnote}{white}
+% arara: context
+\end{codebox}
+
+\item[\rulebox{convert}]
+This rule runs the \rbox{convert} program, a member of the ImageMagick suite of tools. This program is used to convert between image formats as well as resize an image, blur, crop, despeckle, dither, draw on, flip, join, resample, and more.
+
+\begin{description}
+\item[\rpbox{program}{convert}] This option specifies the command utility path as a means to avoid potential clashes with underlying operating system commands.
+
+\item[\abox{options}~\rqbox] This option, as the name indicates, takes a list of raw command line options and appends it to the actual script call. An error is thrown if any data structure other than a proper list is provided as the value.
+\end{description}
+
+\begin{codebox}{Example}{teal}{\icnote}{white}
+% arara: convert: { options: [ 'photo1.jpg', '--resize',
+% arara: --> '50%', 'photo2.jpg' ] }
+\end{codebox}
+
\item[\rulebox{csplain}]
This rule runs the \rbox{csplain} \TeX\ engine, a conservative extension of Knuth's plain \TeX\ with direct processing characters and hyphenation patterns for Czech and Slovak, on the provided \mtbox{currentFile} reference.
@@ -299,6 +370,37 @@ spreadsheet import functions also use this setting.
% arara: --> csv: booklist.csv }
\end{codebox}
+\item[\rulebox{detex}]
+This rule runs \rbox{detex}, a command line application that, as the name indicates, reads the provided \mtbox{currentFile} reference, removes all comments and \TeX\ control sequences and writes the remainder to the standard output or file.
+
+\begin{description}
+\item[\rpsbox{references}] This option defines whether the tool should echo values from page counters, references and citations.
+
+\item[\rpsbox{follow}] This option defines whether the tool should follow files referenced through typical input mechanisms.
+
+\item[\rpsbox{math}] This option defines whether the tool should replace math with nouns and verbs in order to preserve grammar.
+
+\item[\rpsbox{spaces}] This option, as the name indicates, define whether the tool should replace control sequences with spaces.
+
+\item[\rpsbox{words}] This option, as the name indicates, define whether the tool should output only a list of words.
+
+\item[\abox{environments}] This option takes a list of environments to be ignored by the tool during the text transformation.
+
+\item[\abox{mode}] This option, as the name indicates, defines the operation mode for the tool. Possible values are:
+
+\begin{description}
+\item[\povalue{latex}] This value, as the name suggests, enables and forces the \LaTeX\ mode for the tool.
+
+\item[\povalue{tex}] This value, as the name suggests, enables and forces the plain \TeX\ mode for the tool.
+\end{description}
+
+\item[\abox{output}] This value, as the name indicates, sets the output file in which the contents will be redirected.
+\end{description}
+
+\begin{codebox}{Example}{teal}{\icnote}{white}
+% arara: detex: { output: thesis.txt }
+\end{codebox}
+
\item[\rulebox{dvipdfm}]
This rule runs \rbox{dvipdfm}, a command line utility for file format translation, on the corresponding base name of the \mtbox{currentFile} reference (i.e, the name without the associated extension) as a string concatenated with the \rbox{dvi} suffix, generating a Portable Document Format \rbox{pdf} file.
@@ -386,7 +488,52 @@ This rule runs the \rbox{etex} extended (plain) \TeX\ engine on the provided \mt
\end{description}
\begin{codebox}{Example}{teal}{\icnote}{white}
-% arara: etex: { shell: yes }
+% arara: etex: {
+% arara: --> shell: yes,
+% arara: --> interaction: batchmode
+% arara: --> }
+\end{codebox}
+
+\item[\rulebox{fig2dev}]
+This rule runs \rbox{fig2dev}, a command line application that translates \rbox{fig} code in the corresponding base name of the \mtbox{currentFile} reference (i.e, the name without the associated extension) as a string concatenated with the \rbox{fig} suffix into the specified graphics language and puts them in the specified output file.
+
+\begin{description}
+\item[\abox{language}~\rqbox] This option, as the name indicates, sets the output graphics language for proper transformation. Possible values are listed in the following table (you can infer their types as well, based on the values):
+
+\bigskip
+
+{\centering
+\def\arraystretch{1.5}
+\begin{tabularx}{0.8\textwidth}{YYYYYY}
+\povalue{box} & \povalue{cgm} & \povalue{epic} &
+\povalue{eepic} & \povalue{eepicemu} & \povalue{emf}\\
+\povalue{eps} & \povalue{gif} & \povalue{ibmgl} &
+\povalue{jpeg} & \povalue{latex} & \povalue{map}\\
+\povalue{mf} & \povalue{mp} & \povalue{mmp} &
+\povalue{pcx} & \povalue{pdf} & \povalue{pdftex}\\
+\povalue{pdftex\_t} & \povalue{pic} & \povalue{pictex} &
+\povalue{png} & \povalue{ppm} & \povalue{ps}\\
+\povalue{pstex} & \povalue{pstex\_t} & \povalue{ptk} &
+\povalue{shape} & \povalue{sld} & \povalue{svg}\\
+\povalue{textyl} & \povalue{tiff} & \povalue{tk} &
+\povalue{tpic} & \povalue{xbm} & \povalue{xpm}
+\end{tabularx}\par}
+
+\bigskip
+
+\item[\abox{output}~\rqbox] This option, as the name indicates, sets the output file which will contain the translated code based on the provided file and language.
+
+\item[\abox{magnification}] This option, as the name suggests, sets the magnification level at which the figure is rendered.
+
+\item[\abox{font}] This option sets the default font used for text objects to the provided value. Keep in mind that the format of this option depends on the graphics language in use.
+
+\item[\abox{size}] This option, as the name suggests, set the default font size (in points) for text objects to the provided value.
+
+\item[\abox{options}] This option, as the name indicates, takes a list of raw command line options and appends it to the actual system call. An error is thrown if any data structure other than a proper list is provided as the value.
+\end{description}
+
+\begin{codebox}{Example}{teal}{\icnote}{white}
+% arara: fig2dev: { language: mp, output: drawing.mp }
\end{codebox}
\item[\rulebox{frontespizio}]
@@ -440,7 +587,7 @@ This rule runs \rbox{latexindent}, a Perl script that indents \TeX\ files accord
\begin{description}
\item[\rpsbox{silent}] This option, as the name indicates, sets whether the script will operate in silent mode, in which no output is given to the terminal.
-\item[\rpsbox{overwrite}] This option, as the name indicates, sets whether the \mtbox{currentFile} reference will be overwritten. If activated, a copy will be made before the actual indentation process.
+\item[\rpsbox{overwrite}] This option, as the name indicates, sets whether the \mtbox{currentFile} reference will be overwritten. If activated, a copy will be made before the actual indentation process.
\item[\abox{trace}] This option, as the name indicates, enables the script tracing mode, such that a verbose output will be given to the \rbox{indent.log} log file. Possible values are:
@@ -720,7 +867,7 @@ This rule runs \rbox{makeindex}, a general purpose hierarchical index generator,
\item[\abox{order}] This option, as the name indicates, sets the default ordering scheme for the \rbox{makeindex} program. Two possible values are available:
\begin{description}
-\item[\povalue{letter}] This value, as the name indicates, activates the letter ordering scheme. In such scheme, a blank space does not precede any letter in the alphabet.
+\item[\povalue{letter}] This value, as the name indicates, activates the letter ordering scheme. In such scheme, a blank space does not precede any letter in the alphabet.
\item[\povalue{word}] This value, as the name indicates, activates the word ordering scheme. In such scheme, a blank space precedes any letter in the alphabet.
\end{description}
@@ -951,6 +1098,18 @@ This rule runs \rbox{ps2pdf}, a tool that converts PostScript to Portable Docume
% arara: ps2pdf: { output: article }
\end{codebox}
+\item[\rulebox{qpdf}]
+This rule runs \rbox{qpdf}, a command line application that does structural, content-preserving transformations of Portable Document Files, as well as providing capabilities to developers.
+
+\begin{description}
+\item[\abox{options}~\rqbox] This option, as the name indicates, takes a list of raw command line options and appends it to the actual script call. An error is thrown if any data structure other than a proper list is provided as the value.
+\end{description}
+
+\begin{codebox}{Example}{teal}{\icnote}{white}
+% arara: qpdf: { options: [ '--linearize', 'input.pdf',
+% arara: --> 'output.pdf' ] }
+\end{codebox}
+
\item[\rulebox{sketch}]
This rule runs \rbox{sketch}, a system for producing line drawings of solid objects and scenes, on the corresponding base name of the \mtbox{currentFile} reference (i.e, the name without the associated extension) as a string concatenated with the \rbox{sk} suffix. Note that one needs to add support for this particular file type, as seen in Section~\ref{sec:basicstructure}, on page~\pageref{sec:basicstructure}.
@@ -1002,6 +1161,49 @@ This rule runs the \rbox{tex} \TeX\ engine on the provided \mtbox{currentFile} r
% arara: tex: { shell: yes }
\end{codebox}
+\item[\rulebox{texcount}]
+This rule runs \rbox{texcount}, a Perl script designed to count words in \TeX\ and \LaTeX\ files, ignoring macros, tables, formulae and more on the provided \mtbox{currentFile} reference. The script is highly configurable, so make sure to check the manual for further information.
+
+\begin{description}
+\item[\abox{rules}] This option, as the name suggests, sets the rules which dictate how the script should work regarding word counting and option handling. Possible values are:
+
+\begin{description}
+\item[\povalue{relaxed}] This value, as the name indicates, sets a relaxed set of rules, allowing more general cases to be counted as either words and macros.
+
+\item[\povalue{restricted}] This value, as the name indicates, sets a more restricted set of rules for word counting and option handling.
+\end{description}
+
+\item[\abox{verbosity}] This option, as the name suggests, sets the verbosity level of the script according to the provided integer value. Possible values are:
+
+\begin{description}
+\item[\povalue{\hphantom{x}0\hphantom{x}}] This value sets the lowest verbosity level of all, such that the script does not present parsing details.
+
+\item[\povalue{\hphantom{x}1\hphantom{x}}] This value raises the details a bit and sets the verbosity level to include parsed words and marked formulae.
+
+\item[\povalue{\hphantom{x}2\hphantom{x}}] This value adds more details from the previous verbosity level by including ignored text as well.
+
+\item[\povalue{\hphantom{x}3\hphantom{x}}] This value adds more details from the previous verbosity level by including comments and options.
+
+\item[\povalue{\hphantom{x}4\hphantom{x}}] This value sets the highest verbosity level of all, such that the script includes parsed worded, marked formulae, ignored text, comments, options and internal states.
+\end{description}
+
+\item[\rpsbox{strict}] This option sets whether the tool should enable strict mode, so certain groups for which rules are not defined raise warnings.
+
+\item[\rpsbox{html}] This option, as the name suggests, defines whether the tool should output the report in the HTML format.
+
+\item[\rpsbox{total}] This option, as the name suggests, defines whether the tool should provide a total sum instead of partial sums (per file).
+
+\item[\rpsbox{unicode}] This option, as the name indicates, defines whether the tool should select Unicode as encoding for both input and output.
+
+\item[\abox{output}] This option, as the name suggests, sets the output file name in which the report will be written.
+
+\item[\abox{options}] This option, as the name indicates, takes a list of raw command line options and appends it to the actual system call. An error is thrown if any data structure other than a proper list is provided as the value.
+\end{description}
+
+\begin{codebox}{Example}{teal}{\icnote}{white}
+% arara: texcount: { output: report.txt }
+\end{codebox}
+
\item[\rulebox{texindy}]
This rule runs \rbox{texindy}, a variant of the \rbox{xindy} indexing system focused on \LaTeX\ documents, on the corresponding base name of the \mtbox{currentFile} reference (i.e, the name without the associated extension) as a string concatenated with the \rbox{idx} suffix, generating an index as a special \rbox{ind} file.