summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/support/arara/chapters/rules.tex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2021-02-26 22:27:35 +0000
committerKarl Berry <karl@freefriends.org>2021-02-26 22:27:35 +0000
commit2456710acb7b4369eabd67ab4b31297ae142bb6a (patch)
tree66c53381f19ebc027fba14323ad9195555ee2858 /Master/texmf-dist/doc/support/arara/chapters/rules.tex
parent3465548e0c1d39b187bc8b5427001d0c9c5d1e4f (diff)
arara (26feb21)
git-svn-id: svn://tug.org/texlive/trunk@57953 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/support/arara/chapters/rules.tex')
-rw-r--r--Master/texmf-dist/doc/support/arara/chapters/rules.tex287
1 files changed, 271 insertions, 16 deletions
diff --git a/Master/texmf-dist/doc/support/arara/chapters/rules.tex b/Master/texmf-dist/doc/support/arara/chapters/rules.tex
index 39552b40cab..ed46c0b2daf 100644
--- a/Master/texmf-dist/doc/support/arara/chapters/rules.tex
+++ b/Master/texmf-dist/doc/support/arara/chapters/rules.tex
@@ -107,8 +107,6 @@ the like. For example, you could use that to make a common author and subject in
% arara: authorindex: { draft: yes }
\end{codebox}
-
-
\item[\rulebox{bib2gls}]
This rule executes the \rbox{bib2gls} command line application which extracts glossary information stored in a \rbox{bib} file and converts it into glossary entry definitions in resource files. This rule passes the base name of the \mtbox{currentFile} reference (i.e, the name without the associated extension) as the mandatory argument.
@@ -218,7 +216,7 @@ When in doubt, always remember that the \opbox{{-}dry-run} command line option i
\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.
+This rule runs the \rbox{context} \TeX\ engine on the provided \mtbox{currentFile} reference, generating a corresponding file in the Portable Document 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.
@@ -288,6 +286,17 @@ This rule runs the \rbox{convert} program, a member of the ImageMagick suite of
% arara: --> '50%', 'photo2.jpg' ] }
\end{codebox}
+\item[\rulebox{copy}]
+This rule copies the \rbox{File} reference to the provided target using the underlying operating system copy operation. The target is \emph{always} overwritten. However, be mindful that an error will be thrown if you try to overwrite the file referenced in \mtbox{getOriginalReference}.
+
+\begin{description}
+\item[\abox{target}~\rqbox] This option, as the name implies, specifies the target for the copy operation. Keep in mind that this option is required.
+\end{description}
+
+\begin{codebox}{Example}{teal}{\icnote}{white}
+% arara: copy: { target: 'backup/thesis.tex' }
+\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.
@@ -481,9 +490,23 @@ This rule runs \rbox{dvips} in order to obtain a corresponding \rbox{ps} file fr
\end{codebox}
\item[\rulebox{dvisvgm}]
-This rule runs \rbox{dvisvgm} in order to obtain a corresponding \rbox{svg} file, a vector graphics format based on XML, from the initial \rbox{dvi} reference. It is important to observe that the base name is acquired from the \mtbox{currentFile} reference (i.e, the name without the associated extension) and used to construct the resulting file.
+This rule runs \rbox{dvisvgm} in order to obtain a corresponding \rbox{svg} file, a vector graphics format based on XML, from the initial reference. It is important to observe that the base name is acquired from the \mtbox{currentFile} reference (i.e, the name without the associated extension) and used to construct the resulting file.
+
+\begin{description}
+\item[\abox{entry}] This option sets the extension to be used for the initial reference (i.e, the current file name) as input to the command line tool. The following values are available for this option:
\begin{description}
+\item[\povalue{dvi}] This value sets the extension to be used for the initial reference as a device independent format. This is the default value when no value is provided.
+
+\item[\povalue{xdv}] This value sets the extension to be used for the initial reference as an extended device independent format.
+
+\item[\povalue{eps}] This value sets the extension to be used for the initial reference as an encapsulated PostScript graphics format.
+
+\item[\povalue{pdf}] This value sets the extension to be used for the initial reference as a Portable Document Format.
+\end{description}
+
+\item[\abox{pages}] This value, as the name implies, takes a list of integers indicating the pages to be processed by the command line tool.
+
\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}
@@ -599,6 +622,44 @@ This rule automates the steps required by the \rbox{frontespizio} package in ord
% arara: --> shell: yes, interaction: nonstopmode }
\end{codebox}
+\item[\rulebox{ghostscript}]
+This rule runs \rbox{ghostscript}, an interpreter for PostScript and Portable Document Format files, according to the provided parameters.
+
+\begin{description}
+\item[\rpbox{program}{gs}] This option specifies the command utility path as a means to avoid potential clashes with underlying operating system commands or specific Windows naming schemes.
+
+\item[\abox{options}~\rqbox] This option, as the name indicates, takes a list of raw command line options and appends it to the actual \rbox{ghostscript} call. An error is thrown if any data structure other than a proper list is provided as the value. This option is required.
+
+\item[\abox{device}] This option specifies which output device the tool should use. If this option is not given, the default device (usually a display device) is used.
+
+\item[\abox{output}] This option, as the name indicates, specifies a file in which the tool should send the output. Please refer to the documentation for more details.
+\end{description}
+
+\begin{codebox}{Example}{teal}{\icnote}{white}
+% arara: ghostscript: { options: [ '-dCompatibilityLevel=1.4',
+% arara: --> '-dPDFSETTINGS=/printer', '-dNOPAUSE', '-dQUIET',
+% arara: --> '-dBATCH', 'input.pdf' ],
+% arara: --> output: output.pdf,
+% arara: --> device: pdfwrite }
+\end{codebox}
+
+\item[\rulebox{gnuplot}]
+This rule runs \rbox{gnuplot}, a command-driven plotting program that can generate plots of functions, data and data fits. The program also provides scripting capabilities, looping, functions, text processing, variables, macros, arbitrary pre-processing of input data (usually across columns), as well as the ability to perform non-linear multi-dimensional multi-set weighted data fitting.
+
+\begin{description}
+\item[\rpsbox{persist}] This option, as the name implies, sets whether the program should let plot windows survive after the main execution exits.
+
+\item[\rpsbox{default}] this option, as the name suggests, sets whether the program should read the default settings from either \rbox{gnuplotrc} or \rbox{~/.gnuplot} on entry.
+
+\item[\abox{commands}] This option, as the name implies, executes the requested commands before loading the next input file. Please refer to the user manual for further details.
+
+\item[\abox{input}~\rqbox] This required option, as the name indicates, sets the list of input file names to be processed by the program. 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: gnuplot: { input: [ myplot.gnuplot ], default: yes }
+\end{codebox}
+
\item[\rulebox{halt}]
This rule, as the name suggests, sets a \rbox{halt} flag, which stops the current interpretation workflow, such that subsequent directives are ignored. This rule contains no associated options. Please refer to Section~\ref{sec:others}, on page~\pageref{sec:others}, for more information on flags.
@@ -722,9 +783,9 @@ This rule runs \rbox{latexmk}, a fantastic command line tool for fully automated
\item[\abox{clean}] This option, as the name indicates, removes all temporary files generated after a sequence of intermediate calls for document generation. Two possible values are available:
\begin{description}
-\item[\povalue{all}] This value, as the name indicates, removes all temporary, intermediate files, as well as resulting, final formats such as PostScript and Portable Document File. Only relevant source files are kept.
+\item[\povalue{all}] This value, as the name indicates, removes all temporary, intermediate files, as well as resulting, final formats such as PostScript and Portable Document Format. Only relevant source files are kept.
-\item[\povalue{partial}] This value, as the name indicates, removes all temporary, intermediate files and keeps the resulting, final formats such as PostScript and Portable Document File.
+\item[\povalue{partial}] This value, as the name indicates, removes all temporary, intermediate files and keeps the resulting, final formats such as PostScript and Portable Document Format.
\end{description}
\item[\abox{engine}] This option, as the name indicates, sets the underlying \TeX\ engine of \rbox{latexmk} to be used for the compilation sequence. Possible values are:
@@ -732,11 +793,19 @@ This rule runs \rbox{latexmk}, a fantastic command line tool for fully automated
\begin{description}
\item[\povalue{latex}] This value, as the name indicates, sets the underlying \TeX\ engine of the script to \rbox{latex} for the compilation sequence.
+\item[\povalue{latex-dev}] This value, as the name indicates, sets the underlying \TeX\ engine of the script to \rbox{latex-dev} (the development branch) for the compilation sequence.
+
\item[\povalue{pdflatex}] This value, as the name indicates, sets the underlying \TeX\ engine of the script to \rbox{pdflatex} for the compilation sequence.
+\item[\povalue{pdflatex-dev}] This value, as the name indicates, sets the underlying \TeX\ engine of the script to \rbox{pdflatex-dev} (the development branch) for the compilation sequence.
+
\item[\povalue{xelatex}] This value, as the name indicates, sets the underlying \TeX\ engine of the script to \rbox{xelatex} for the compilation sequence.
+\item[\povalue{xelatex-dev}] This value, as the name indicates, sets the underlying \TeX\ engine of the script to \rbox{xelatex-dev} (the development branch) for the compilation sequence.
+
\item[\povalue{lualatex}] This value, as the name indicates, sets the underlying \TeX\ engine of the script to \rbox{lualatex} for the compilation sequence.
+
+\item[\povalue{lualatex-dev}] This value, as the name indicates, sets the underlying \TeX\ engine of the script to \rbox{lualatex-dev} (the development branch) for the compilation sequence.
\end{description}
\item[\abox{program}] This option, as the name suggests, sets the \TeX\ engine according to the provided value. It is important to note that this option has higher priority over \abox{engine} values, so the latter will be discarded.
@@ -748,8 +817,89 @@ This rule runs \rbox{latexmk}, a fantastic command line tool for fully automated
% arara: latexmk: { engine: pdflatex }
\end{codebox}
+\item[\rulebox{llmk}]
+This rule runs \rbox{llmk}, a command line tool specific for building \LaTeX\ documents. The tool's aim is to provide a simple way to specify a workflow of processing documents and encourage people to always explicitly show the right workflow for each document.
+
+\begin{description}
+\item[\abox{clean}] This option, as the name indicates, removes all temporary files generated after a sequence of intermediate calls for document generation. Two possible values are available:
+
+\begin{description}
+\item[\povalue{all}] This value, as the name indicates, removes all temporary, intermediate files, as well as resulting, final formats such as PostScript and Portable Document Format. Only relevant source files are kept.
+
+\item[\povalue{partial}] This value, as the name indicates, removes all temporary, intermediate files and keeps the resulting, final formats such as PostScript and Portable Document Format.
+\end{description}
+
+\item[\abox{debug}] This option activates the specified debug category, so debugging messages related to the activated category will be shown. Please refer to the documentation for more details.
+
+\item[\rpsbox{dry}] This option sets whether the tool should display a list of commands to be executed without actually invoking them.
+
+\item[\abox{mode}]
+This option sets the verbosity level of messages to be displayed during a run. Three possible values are available:
+
+\begin{description}
+\item[\povalue{quiet}] This value, as the name indicates, suppresses most of the messages from the program during execution.
+
+\item[\povalue{silent}] This value, as the name indicates, silences messages from invoked programs by redirecting both standard output and standard error streams to the null device.
+
+\item[\povalue{verbose}] This value, as the name indicates, displays additional information such as invoked commands with options and arguments by the program.
+\end{description}
+\end{description}
+
+\begin{codebox}{Example}{teal}{\icnote}{white}
+% arara: llmk: { mode: verbose }
+\end{codebox}
+
+\item[\rulebox{ltx2any}]
+This rule runs \rbox{ltx2any}, a command line tool written in Ruby that acts as a \LaTeX\ build wrapper, on the provided \mtbox{currentFile} reference.
+
+\begin{description}
+\item[\rpsbox{clean}] This option, as the name indicates, sets whether all intermediate results generated during the compilation to be deleted.
+
+\item[\abox{engine}] This option, as the name indicates, sets the engine to be using during the current execution.
+
+\item[\abox{parameters}] This option, as the name indicates, takes a list of parameters to be passed to the engine. An error is thrown if any data structure other than a proper list is provided as the value.
+
+\item[\abox{tikzimages}] This option takes a list of externalised Ti\textit{k}Z images to rebuild. An error is thrown if any data structure other than a proper list is provided as the value.
+
+\item[\abox{jobname}] This option, as the name indicates, sets the job name to be used in the resulting file.
+
+\item[\abox{logname}] This option, as the name indicates, sets the log file name to be used during the current execution.
+
+\item[\abox{logformat}] This option, as the name indicates, sets the log format to be used during the current execution. Three possible values are available:
+
+\begin{description}
+\item[\povalue{raw}] This value, as the name indicates, sets the log format to be raw, i.e, as generated by the underlying engines.
+
+\item[\povalue{markdown}] This value, as the name indicates, sets the log format to be displayed in Markdown.
+
+\item[\povalue{pdf}] This value, as the name indicates, sets the log format to be displayed in the Portable Document Format.
+\end{description}
+
+\item[\abox{loglevel}] This option, as the name indicates, sets the log level to be used during the current execution. Three possible values are available:
+
+\begin{description}
+\item[\povalue{error}] This value, as the name indicates, sets the base log level to report errors only. No other information is appended.
+
+\item[\povalue{warning}] This value, as the name indicates, sets the base log level to report warnings and errors. No other information is appended.
+
+\item[\povalue{info}] This value, as the name indicates, set the base log level to report all information available, regardless of message categories.
+\end{description}
+
+\item[\abox{frequency}] This option, as the name indicates, sets how often the engine runs. Values smaller than one will cause it to run until the resulting file no longer changes.
+
+\item[\abox{directory}] This option, as the name indicates, sets the directory to hold intermediate files during the compilation.
+
+\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{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: ltx2any: { synctex: yes }
+\end{codebox}
+
\item[\rulebox{luahbtex}]
-This rule runs the \rbox{luahbtex} \TeX\ engine on the provided \mtbox{currentFile} reference, generating a corresponding file in the Portable Document File format, as expected.
+This rule runs the \rbox{luahbtex} \TeX\ engine on the provided \mtbox{currentFile} reference, generating a corresponding file in the Portable Document Format, as expected.
\begin{description}
\item[\abox{interaction}] This option alters the underlying engine behaviour. If this option is omitted, \TeX\ 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):
@@ -779,7 +929,7 @@ This rule runs the \rbox{luahbtex} \TeX\ engine on the provided \mtbox{currentFi
\end{codebox}
\item[\rulebox{lualatex}]
-This rule runs the new \rbox{lualatex} \TeX\ engine on the provided \mtbox{currentFile} reference, generating a corresponding file in the Portable Document File format, as expected.
+This rule runs the new \rbox{lualatex} \TeX\ engine on the provided \mtbox{currentFile} reference, generating a corresponding file in the Portable Document Format, as expected.
\begin{description}
\item[\rpbox{branch}{stable}] This option allows branching formats for the current engine, mainly focused on package development. Users of current \TeX\ distributions might benefit from format branching in order to easily test documents and code against the upcoming releases. Possible values are:
@@ -817,7 +967,7 @@ This rule runs the new \rbox{lualatex} \TeX\ engine on the provided \mtbox{curre
\end{codebox}
\item[\rulebox{luatex}]
-This rule runs the \rbox{luatex} \TeX\ engine on the provided \mtbox{currentFile} reference, generating a corresponding file in the Portable Document File format, as expected.
+This rule runs the \rbox{luatex} \TeX\ engine on the provided \mtbox{currentFile} reference, generating a corresponding file in the Portable Document Format, as expected.
\begin{description}
\item[\abox{interaction}] This option alters the underlying engine behaviour. If this option is omitted, \TeX\ 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):
@@ -943,6 +1093,18 @@ This rule runs \rbox{metapost}, a tool to compile the Metapost graphics programm
% arara: metapost: { files: [ graphics.mp ] }
\end{codebox}
+\item[\rulebox{move}]
+This rule moves the \rbox{File} reference to the provided target using the underlying operating system move operation. The target is \emph{always} overwritten. However, be mindful that an error will be thrown if you try to move or overwrite the file referenced in \mtbox{getOriginalReference}.
+
+\begin{description}
+\item[\abox{target}~\rqbox] This option, as the name implies, specifies the target for the move operation. Keep in mind that this option is required.
+\end{description}
+
+\begin{codebox}{Example}{teal}{\icnote}{white}
+% arara: move: { files: [ 'thesis.pdf' ],
+% arara: --> target: 'backup/thesis.pdf' }
+\end{codebox}
+
\item[\rulebox{nomencl}]
This rule runs \rbox{makeindex} in order to automatically generate a nomenclature list from \TeX\ documents that work with the \rbox{nomencl} package. The program itself is a general purpose hierarchical index generator and takes the corresponding base name of the \mtbox{currentFile} reference (i.e, the name without the associated extension) as a string concatenated with the \rbox{nlo} suffix and a special style file in order to generate the nomenclature list as a special \rbox{nls} file.
@@ -968,6 +1130,51 @@ This rule runs the \rbox{pbibtex} program, a reference management software, on t
% arara: --> if exists(toFile('references.bib'))
\end{codebox}
+\item[\rulebox{pdfcrop}]
+This rule runs \rbox{pdfcrop}, a command line utility to calculate and remove empty margins, on corresponding base name of the \mtbox{currentFile} reference (i.e, the name without the associated extension) as a string concatenated with the \rbox{pdf} suffix.
+
+\begin{description}
+\item[\abox{output}] This option, as the name indicates, sets the output file. When omitted, the tool uses the input base name with the \rbox{-crop.pdf} suffix.
+
+\item[\rpsbox{verbose}] This option, as the name indicates, sets whether the command line tool will be executed in verbose mode.
+
+\item[\rpsbox{debug}] This option, as the name indicates, sets whether the command line tool will be executed in debug mode.
+
+\item[\abox{engine}] This option, as the name indicates, sets the underlying \TeX\ engine to be used during the run. Three possible values are available:
+
+\begin{description}
+\item[\povalue{pdftex}] This value, as the name indicates, sets \rbox{pdftex} as the underlying \TeX\ engine to be used during the run.
+
+\item[\povalue{xetex}] This value, as the name indicates, sets \rbox{xetex} as the underlying \TeX\ engine to be used during the run.
+
+\item[\povalue{luatex}] This value, as the name indicates, sets \rbox{luatex} as the underlying \TeX\ engine to be used during the run.
+\end{description}
+
+\item[\abox{margins}] This option, as the name indicates, takes a list of four elements denoting left, top, right and bottom margins, respectivelly. An error will be thrown if no list is provided or if the list does not contain exactly four elements.
+
+\item[\rpsbox{clip}] This option, as the name indicates, sets whether the command line tool should include clipping support, if margins are set.
+
+\item[\rpsbox{hires}] This option, as the name indicates, sets whether the command line tool should use a high resolution bounding box feature.
+
+\item[\rpsbox{ini}] This option, as the name indicates, sets whether the \rbox{initex} variant of the underlying \TeX\ engine is used.
+
+\item[\rpsbox{restricted}] This option, as the name indicates, sets whether the command line tool should run on restricted mode.
+
+\item[\abox{papersize}] This option, as the name indicates, sets the paper size. According to the documentation, this option should only be used with older versions of \rbox{ghostscript}.
+
+\item[\abox{resolution}] This option, as the name indicates, sets the resolution by forwarding the value to the underlying \rbox{ghostscript} call.
+
+\item[\abox{bbox}] This option, as the name indicates, takes a list of four elements denoting left, bottom, right and top margins, respectivelly, to override bounding box values found by \rbox{ghostscript}. An error will be thrown if no list is provided or if the list does not contain exactly four elements.
+
+\item[\rpsbox{uncompress}] This option, as the name indicates, sets whether the tool should generate an uncompressed Portable Document Format file, useful for debugging.
+
+\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: pdfcrop
+\end{codebox}
+
\item[\rulebox{pdfcsplain}]
This rule runs the \rbox{pdfcsplain} \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.
@@ -998,7 +1205,7 @@ This rule runs the \rbox{pdfcsplain} \TeX\ engine, a conservative extension of K
\end{codebox}
\item[\rulebox{pdflatex}]
-This rule runs the \rbox{pdflatex} \TeX\ engine on the provided \mtbox{currentFile} reference, generating a corresponding file in the Portable Document File format, as expected.
+This rule runs the \rbox{pdflatex} \TeX\ engine on the provided \mtbox{currentFile} reference, generating a corresponding file in the Portable Document Format, as expected.
\begin{description}
\item[\rpbox{branch}{stable}] This option allows branching formats for the current engine, mainly focused on package development. Users of current \TeX\ distributions might benefit from format branching in order to easily test documents and code against the upcoming releases. Possible values are:
@@ -1036,7 +1243,7 @@ This rule runs the \rbox{pdflatex} \TeX\ engine on the provided \mtbox{currentFi
\end{codebox}
\item[\rulebox{pdftex}]
-This rule runs the \rbox{pdftex} \TeX\ engine on the provided \mtbox{currentFile} reference, generating a corresponding file in the Portable Document File format, as expected.
+This rule runs the \rbox{pdftex} \TeX\ engine on the provided \mtbox{currentFile} reference, generating a corresponding file in the Portable Document Format, as expected.
\begin{description}
\item[\abox{interaction}] This option alters the underlying engine behaviour. If this option is omitted, \TeX\ 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):
@@ -1164,7 +1371,7 @@ This rule runs the \rbox{platex} \TeX\ engine on the provided \mtbox{currentFile
\end{codebox}
\item[\rulebox{ps2pdf}]
-This rule runs \rbox{ps2pdf}, a tool that converts PostScript to Portable Document File, 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{ps} suffix.
+This rule runs \rbox{ps2pdf}, a tool that converts PostScript to Portable Document Format, 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{ps} suffix.
\begin{description}
\item[\abox{output}] This option, as the name indicates, sets the output name for the generated \rbox{pdf} file. There is no need to provide an extension, as the value is always normalized with \mtbox{getBasename} such that only the name without the associated extension is used. The base name of the current file reference is used as the default value.
@@ -1214,7 +1421,7 @@ This rule runs \rbox{pythontex}, a wrapper that provides access to Python from w
\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.
+This rule runs \rbox{qpdf}, a command line application that does structural, content-preserving transformations of Portable Document Format 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.
@@ -1225,6 +1432,33 @@ This rule runs \rbox{qpdf}, a command line application that does structural, con
% arara: --> 'output.pdf' ] }
\end{codebox}
+\item[\rulebox{sage}]
+This rule runs \rbox{sage}, a free open source mathematics software system, 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{sage} extension (which can be overriden).
+
+\begin{description}
+\item[\rpbox{program}{sage}] This option, as the name indicates, sets the program name. If the tool is not directly available in your system path, make sure to use the full path to the installed \rbox{sage} binary.
+
+\item[\rpbox{extension}{sage}] This option, as the name indicates, sets the default extension to the input file to be processed by \rbox{sage}. Three possible values are available:
+
+\begin{description}
+\item[\povalue{sage}] This value, as the name indicates, sets the extension to refer to the Sage format, the default one used by the software system.
+
+\item[\povalue{py}] This value, as the name indicates, sets the extension to refer to a typical Python source code.
+
+\item[\povalue{spyx}] This value, as the name indicates, sets the extension to refer to the SPYX format, a specific Sage compiled source code.
+\end{description}
+
+\item[\abox{command}] This option, as the name indicates, forwards the provided value to the command line utility to be evaluated as a Sage code.
+
+\item[\rpsbox{dotsage}] This option, as the name indicates, sets whether the tool should consider using the \rbox{.sage} directory in the user home directory or a temporary one.
+
+\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: sage
+\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}.
@@ -1251,6 +1485,19 @@ This rule runs \rbox{songidx}, a song index generation script for the \rbox{song
% arara: songidx: { input: songs }
\end{codebox}
+\item[\rulebox{spix}]
+This rule runs \rbox{spix}, an interesting command line \TeX\ automation tool written in Python, on the provided \mtbox{currentFile} reference.
+
+\begin{description}
+\item[\abox{dry}] This option sets whether the tool should display a list of commands to be executed without actually invoking them.
+
+\item[\abox{options}] 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: spix
+\end{codebox}
+
\item[\rulebox{tex}]
This rule runs the \rbox{tex} \TeX\ engine on the provided \mtbox{currentFile} reference, generating a corresponding file in a device independent format.
@@ -1444,7 +1691,15 @@ This rule runs the \rbox{uptex} \TeX\ engine on the provided \mtbox{currentFile}
\end{codebox}
\item[\rulebox{xdvipdfmx}]
-This rule runs \rbox{xdvipdfmx}, the back end for the \rbox{xetex} \TeX\ engine (and not intended to be invoked directly), 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.
+This rule runs \rbox{xdvipdfmx}, the back end for the \rbox{xetex} \TeX\ engine (and not intended to be invoked directly), on the corresponding base name of the \mtbox{currentFile} reference (i.e, the name without the associated extension) as a string concatenated with a certain suffix, generating a Portable Document Format \rbox{pdf} file.
+
+\item[\abox{entry}] This option sets the extension to be used for the initial reference (i.e, the current file name) as input to the command line tool. The following values are available for this option:
+
+\begin{description}
+\item[\povalue{dvi}] This value sets the extension to be used for the initial reference as a device independent format. This is the default value when no value is provided.
+
+\item[\povalue{xdv}] This value sets the extension to be used for the initial reference as an extended device independent format.
+\end{description}
\begin{description}
\item[\abox{output}] This option, as the name indicates, sets the output name for the generated \rbox{pdf} file. There is no need to provide an extension, as the value is always normalized with \mtbox{getBasename} such that only the name without the associated extension is used. The base name of the current file reference is used as the default value.
@@ -1457,7 +1712,7 @@ This rule runs \rbox{xdvipdfmx}, the back end for the \rbox{xetex} \TeX\ engine
\end{codebox}
\item[\rulebox{xelatex}]
-This rule runs the new \rbox{xelatex} \TeX\ engine on the provided \mtbox{currentFile} reference, generating a corresponding file in the Portable Document File format, as expected.
+This rule runs the new \rbox{xelatex} \TeX\ engine on the provided \mtbox{currentFile} reference, generating a corresponding file in the Portable Document Format, as expected.
\begin{description}
\item[\rpbox{branch}{stable}] This option allows branching formats for the current engine, mainly focused on package development. Users of current \TeX\ distributions might benefit from format branching in order to easily test documents and code against the upcoming releases. Possible values are:
@@ -1492,7 +1747,7 @@ This rule runs the new \rbox{xelatex} \TeX\ engine on the provided \mtbox{curren
\end{codebox}
\item[\rulebox{xetex}]
-This rule runs the \rbox{xetex} \TeX\ engine on the provided \mtbox{currentFile} reference, generating a corresponding file in the Portable Document File format, as expected.
+This rule runs the \rbox{xetex} \TeX\ engine on the provided \mtbox{currentFile} reference, generating a corresponding file in the Portable Document Format, as expected.
\begin{description}
\item[\abox{interaction}] This option alters the underlying engine behaviour. If this option is omitted, \TeX\ 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):