diff options
Diffstat (limited to 'Master')
92 files changed, 2298 insertions, 376 deletions
diff --git a/Master/texmf-dist/doc/man/man1/arara.1 b/Master/texmf-dist/doc/man/man1/arara.1 new file mode 100644 index 00000000000..3b78f430037 --- /dev/null +++ b/Master/texmf-dist/doc/man/man1/arara.1 @@ -0,0 +1,47 @@ +.TH ARARA 1 "26 February 2021" "v6.0.0" +.SH NAME +arara \- a TeX automation tool based on rules and directives. +.SH SYNOPSIS +.B arara +.RI [ options ] +.IR documents ... +.SH DESCRIPTION +\fBarara\fP is a TeX automation tool based on rules and directives. It gives +you a way to enhance your TeX experience. The tool is an effort to provide a +concise way to automate the daily TeX workflow for users and also package +writers. Users might write their own rules when the provided ones do not suffice. +.PP +arara takes a list of documents as input. They will be processed according +to their directives. Options apply to the execution of all documents. +.SH OPTIONS +.IP \fB--log\fP +Generate a log output. +.IP \fB--verbose\fP / \fB--silent\fP +Print or suppress command output. +.IP \fB--dry-run\fP +Go through all the motions of running a command but with no actual calls. +.IP \fB--safe-run\fP +Run in safe mode and disable potentially harmful features. +.IP \fB--header\fP +Extract directives only in the file header. +.IP \fB--preamble\fP name +Set the file preamble as named based on the configuration file. +.IP \fB--timeout\fP milliseconds +Sets an execution timeout for spawned processes. +.IP \fB--language\fP code +Set the localization to the language specified by code. +.IP \fB--max-loops\fP number +Set the number > 0 of loops for looping directives. +.IP \fB--working-directory\fP path +Set the working directory for the whole execution. +.IP \fB--call-property\fP value +Pass a property as \fCkey=value\fP parameter into the application +to be used within the session. +.IP \fB--version\fP +Show the version and exit. +.IP \fB--help\fP +Show a help message and exit. +.SH BUGS +Issue tracker at +.UR https://gitlab.com/islandoftex/arara/-/issues +.UE . diff --git a/Master/texmf-dist/doc/support/arara/README.md b/Master/texmf-dist/doc/support/arara/README.md index 9adb41b2555..1bb200f2c4e 100644 --- a/Master/texmf-dist/doc/support/arara/README.md +++ b/Master/texmf-dist/doc/support/arara/README.md @@ -1,6 +1,6 @@ ![arara](https://i.stack.imgur.com/hjUsN.png) -# arara v5.1.3 +# arara v6.0.0 ![Language: Kotlin](https://img.shields.io/badge/Language-Kotlin-blue.svg?style=flat-square) ![Minimum JRE: 8.0](https://img.shields.io/badge/Minimum_JRE-8-blue.svg?style=flat-square) @@ -10,11 +10,10 @@ way to enhance your TeX experience. The tool is an effort to provide a concise way to automate the daily TeX workflow for users and also package writers. Users might write their own rules when the provided ones do not suffice. -> Please note that `arara` recently moved. We are proud to announce that -> `arara` is now part of the [Island of TeX](https://gitlab.com/islandoftex). -> The new address is https://gitlab.com/islandoftex/arara. The old GitHub -> repository will be used as mirror but development happens on GitLab. Please -> open relevant issues and merge requests there. +> We are proud to announce that `arara` is part of the +> [Island of TeX](https://gitlab.com/islandoftex). The GitHub repository will +> be used as mirror but development happens on GitLab. Please open relevant +> issues and merge requests there. ## Basic use @@ -41,32 +40,39 @@ use your own rules. ## Getting the latest and greatest arara `arara` is continuously built by the GitLab CI. For each and every commit, it is - ensured that a green tick means `arara` passes the test suite and is ready to - be tested. However, that is *not* meant you can use the executable artifacts of - the builds *for productive use*. +ensured that a green tick means `arara` passes the test suite and is ready to +be tested. However, that is *not* meant you can use the executable artifacts of +the builds *for productive use*. - Development of `arara` takes place in the development branch. Feel free to be - one of our testers and enjoy the latest features and bug fixes by building from - there. +Development of `arara` takes place in the development branch. Feel free to be +one of our testers and enjoy the latest features and bug fixes by building from +there. -## Support +If you encounter any bugs or issues when using the development branch, you are +most welcome to get in touch with us and discuss potential solutions. We are +also always watching out for developers who want to join us making `arara` even +better. -We use a [Gitter](https://gitter.im/cereda/arara) chatroom for discussing things -related to `arara`. You are more than welcome to come join the fun and say *hi!* -to us. We also have the [issues](https://gitlab.com/islandoftex/arara/issues) -section in our repository as a valid channel to report problems, bugs and -suggest improvements. +## Get in touch + +We use a [Gitter](https://gitter.im/Island-of-TeX/arara) chatroom for discussing +things related to `arara`. You are more than welcome to come join the fun and +say *hi!* to us. We also have the +[issues](https://gitlab.com/islandoftex/arara/issues) section in our repository +as a valid channel to report problems, bugs and suggest improvements. + +If you want to stay in the loop of our other projects, feel free to visit our +[community room on Gitter](https://gitter.im/Island-of-TeX/community) or +alternatively, the Matrix rooms for +[arara](https://matrix.to/#/!HfEWIEvFtDplCLSQvz:matrix.org?via=matrix.org) or +the [community](https://matrix.to/#/!titTeSvZiqNOvRIKCv:matrix.org?via=matrix.org). ## Localization Would you like to make `arara` speak your own language? Splendid! We would love -to have you in the team! Just send us an e-mail, join our dedicated chatroom or -open an issue about it. The localization process is quite straightforward, we -can help you! Any language is welcome! - -A big thanks to our translators Marco Daniel, Clemens Niederberger, Ulrike -Fischer, Gert Fischer, Enrico Gregorio and Marijn Schraagen for the awesome -localization work! +to have you in the team! Just contact us by opening an issue or joining our +dedicated chatroom. The localization process is quite straightforward, we can +help you! Any language is welcome! ## Downloads @@ -93,7 +99,6 @@ has been vetted as an open source license by the ## The team -`arara`, the cool TeX automation tool, is brought to you by Paulo Cereda, Marco -Daniel, Brent Longborough, Nicola Talbot and Ben Frank. If you want to support -TeX development by a donation, the best way to do this is donating to the -[TeX Users Group](https://www.tug.org/donate.html). +`arara`, the cool TeX automation tool, is brought to you by the Island of TeX. +If you want to support TeX development by a donation, the best way to do this +is donating to the [TeX Users Group](https://www.tug.org/donate.html). diff --git a/Master/texmf-dist/doc/support/arara/arara-manual.pdf b/Master/texmf-dist/doc/support/arara/arara-manual.pdf Binary files differindex ed5a6b0eaac..1bf1b53eda8 100644 --- a/Master/texmf-dist/doc/support/arara/arara-manual.pdf +++ b/Master/texmf-dist/doc/support/arara/arara-manual.pdf diff --git a/Master/texmf-dist/doc/support/arara/arara-manual.tex b/Master/texmf-dist/doc/support/arara/arara-manual.tex index 196d1ce7a44..91d2bcf4a7a 100644 --- a/Master/texmf-dist/doc/support/arara/arara-manual.tex +++ b/Master/texmf-dist/doc/support/arara/arara-manual.tex @@ -42,7 +42,8 @@ \usepackage[margin=2.5cm]{geometry} \usepackage{arara} -\newcommand{\araraversion}{5.1.3} +\newcommand{\araraversion}{% + \InputIfFileExists{version.tex}{}{undefined}} \begin{document} @@ -64,7 +65,7 @@ \centering \Huge \sffamily - \bfseries User manual + \bfseries Reference manual \end{tcolorbox} \vspace{6em} diff --git a/Master/texmf-dist/doc/support/arara/arara-quickstart.pdf b/Master/texmf-dist/doc/support/arara/arara-quickstart.pdf Binary files differnew file mode 100644 index 00000000000..6ec554a6324 --- /dev/null +++ b/Master/texmf-dist/doc/support/arara/arara-quickstart.pdf diff --git a/Master/texmf-dist/doc/support/arara/arara-quickstart.tex b/Master/texmf-dist/doc/support/arara/arara-quickstart.tex new file mode 100644 index 00000000000..2eef9002e8e --- /dev/null +++ b/Master/texmf-dist/doc/support/arara/arara-quickstart.tex @@ -0,0 +1,823 @@ +% arara: quickstart + +% Arara, the cool TeX automation tool +% Copyright (c) 2012 -- 2020, Island of TeX +% All rights reserved. +% +% Redistribution and use in source and binary forms, with or without +% modification, are permitted provided that the following conditions +% are met: +% +% 1. Redistributions of source code must retain the above copyright +% notice, this list of conditions and the following disclaimer. +% +% 2. Redistributions in binary form must reproduce the above copyright +% notice, this list of conditions and the following disclaimer in the +% documentation and/or other materials provided with the distribution. +% +% 3. Neither the name of the project's author nor the names of its +% contributors may be used to endorse or promote products derived from +% this software without specific prior written permission. +% +% THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +% "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +% LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS +% FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE +% COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, +% INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, +% BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +% LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER +% CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +% LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY +% WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +% POSSIBILITY OF SUCH DAMAGE. + +\pdfobjcompresslevel=1 +\pdfpageattr {/Group << /S /Transparency /I true /CS /DeviceRGB>>} + +\documentclass[a4paper,oneside,11pt]{memoir} + +\usepackage[T1]{fontenc} +\usepackage[utf8]{inputenc} +\usepackage[margin=2.5cm]{geometry} +\usepackage{arara} + +\usepackage{tikzlings} + +\newcommand{\araraversion}{% + \InputIfFileExists{version.tex}{}{undefined}} + +\newcommand{\peter}[1][1]{\begin{tikzpicture}[scale=#1, transform shape] +\node[ + draw=araracolour, + thick, + fill=araracolour!20!white, + rectangle, + minimum width=4cm, + minimum height=3cm, + rounded corners +] (box) {}; + +\begin{scope} +\clip (box.south west) rectangle (box.north east); +\anteater[ + yshift=-3.2cm, + xshift=-.3cm, + scale=2, + hat=warningcolour +] +\end{scope} +\end{tikzpicture}} + +\newcommand{\accessories}{% +\begin{tikzpicture}[ + y=0.80pt, + x=0.80pt, + yscale=-.044, + xscale=.044, + inner sep=0pt, + outer sep=0pt +] +% hat +\path[ + fill=black, + line width=0.080pt +] +(332.9381,0.2962) .. controls (310.4381,2.1962) and (301.5381,3.0962) .. +(289.9381,4.7962) .. controls (211.3381,16.4962) and (164.7381,42.8962) .. +(142.9381,88.0962) .. controls (131.0381,112.7962) and (127.8381,130.5962) .. +(125.9381,181.6962) .. controls (125.4381,197.3962) and (124.4381,217.1962) .. +(123.8381,225.6962) .. controls (122.5381,245.4962) and (119.2381,269.7962) .. +(117.6381,271.3962) .. controls (117.3381,271.6962) and (112.3381,270.9962) .. +(106.5381,269.7962) .. controls (85.2381,265.4962) and (64.2381,266.0962) .. +(46.0381,271.2962) .. controls (30.7381,275.7962) and (22.5381,281.8962) .. +(13.0381,296.0962) .. controls (-1.7619,317.9962) and (-3.9619,338.7962) .. +(6.4381,358.5962) .. controls (15.4381,375.5962) and (45.7381,403.5962) .. +(70.2381,417.5962) .. controls (85.8381,426.3962) and (97.2381,430.6962) .. +(133.4381,441.2962) .. controls (169.9381,451.8962) and (171.7381,452.3962) .. +(192.2381,455.0962) .. controls (276.5381,466.4962) and (311.0381,469.0962) .. +(373.9381,468.9962) .. controls (420.8381,468.9962) and (440.8381,467.8962) .. +(477.4381,463.1962) .. controls (576.5381,450.5962) and (634.4381,433.0962) .. +(672.8381,404.1962) .. controls (694.7381,387.5962) and (708.5381,368.3962) .. +(714.0381,346.6962) .. controls (718.7381,328.2962) and (714.3381,312.9962) .. +(699.0381,295.0962) .. controls (678.4381,270.7962) and (647.1381,260.3962) .. +(612.5381,266.2962) .. controls (607.5381,267.0962) and (600.9381,267.6962) .. +(597.9381,267.4962) -- (592.4381,267.1962) -- (591.8381,262.6962) .. +controls (591.4381,260.1962) and (590.6381,248.6962) .. (590.0381,237.1962) .. +controls (589.4381,225.5962) and (588.2381,203.7962) .. (587.4381,188.6962) .. +controls (584.0381,126.1962) and (577.3381,96.5962) .. (560.7381,71.0962) .. +controls (554.2381,61.0962) and (537.7381,44.5962) .. (527.9381,38.1962) .. +controls (500.3381,20.1962) and (458.5381,7.4962) .. (409.4381,2.1962) .. +controls (396.3381,0.6962) and (343.1381,-0.6038) .. (332.9381,0.2962) -- cycle; + +% glasses +\path[ + fill=black, + line width=0.080pt +] (141.9381,516.6962) .. controls (122.6381,518.5962) and (104.4381,521.6962) .. +(60.9381,530.5962) .. controls (50.2381,532.7962) and (39.0381,534.8962) .. +(36.2381,535.2962) .. controls (33.3381,535.5962) and (30.4381,536.5962) .. +(29.8381,537.2962) .. controls (29.1381,538.1962) and (28.8381,543.1962) .. +(29.1381,552.3962) .. controls (29.5381,569.4962) and (30.7381,572.2962) .. +(41.6381,583.8962) .. controls (51.4381,594.3962) and (53.8381,598.8962) .. +(58.4381,615.5962) .. controls (64.4381,637.4962) and (76.8381,670.5962) .. +(85.3381,687.5962) .. controls (96.3381,709.3962) and (117.6381,722.2962) .. +(155.8381,730.3962) .. controls (167.4381,732.8962) and (170.3381,733.0962) .. +(191.9381,733.0962) .. controls (210.5381,733.0962) and (217.5381,732.7962) .. +(225.4381,731.2962) .. controls (261.7381,724.5962) and (285.6381,708.1962) .. +(308.4381,674.1962) .. controls (317.1381,661.1962) and (325.9381,643.2962) .. +(329.8381,630.4962) .. controls (331.6381,624.7962) and (334.2381,616.4962) .. +(335.5381,612.0962) .. controls (338.6381,602.0962) and (343.2381,594.7962) .. +(347.9381,592.4962) .. controls (353.1381,589.8962) and (371.8381,589.9962) .. +(377.6381,592.5962) .. controls (385.1381,596.0962) and (389.1381,602.7962) .. +(397.9381,627.6962) .. controls (418.0381,684.3962) and (441.0381,710.1962) .. +(484.8381,724.6962) .. controls (517.3381,735.4962) and (548.1381,736.1962) .. +(580.4381,726.8962) .. controls (612.4381,717.5962) and (633.1381,701.2962) .. +(646.4381,674.6962) .. controls (651.3381,664.6962) and (654.5381,655.1962) .. +(662.9381,625.1962) .. controls (669.9381,599.9962) and (675.6381,586.7962) .. +(681.4381,582.0962) .. controls (683.4381,580.4962) and (686.6381,577.7962) .. +(688.5381,575.9962) -- (692.0381,572.7962) -- (691.7381,556.5962) .. +controls (691.4381,540.5962) and (691.4381,540.3962) .. (688.9381,538.5962) .. +controls (687.5381,537.4962) and (682.8381,535.9962) .. (678.4381,535.2962) .. +controls (674.0381,534.4962) and (663.0381,531.9962) .. (653.9381,529.7962) .. +controls (635.4381,525.2962) and (617.4381,521.7962) .. (595.9381,518.5962) .. +controls (583.9381,516.6962) and (577.0381,516.2962) .. (555.4381,516.2962) .. +controls (525.2381,516.1962) and (520.0381,516.8962) .. (462.9381,527.2962) .. +controls (372.7381,543.7962) and (353.8381,544.2962) .. (288.4381,531.1962) .. +controls (248.4381,523.1962) and (229.0381,520.1962) .. (199.9381,517.7962) .. +controls (182.3381,516.2962) and (152.5381,515.6962) .. (141.9381,516.6962) -- +cycle(237.4381,532.2962) .. +controls (256.8381,535.0962) and (276.8381,540.7962) .. (291.4381,547.6962) .. +controls (309.0381,555.8962) and (318.3381,566.0962) .. (321.5381,580.3962) .. +controls (323.0381,587.0962) and (323.0381,589.2962) .. (322.0381,597.1962) .. +controls (320.4381,609.6962) and (314.2381,627.2962) .. (305.0381,646.1962) .. +controls (295.2381,666.1962) and (288.7381,675.9962) .. (278.4381,686.1962) .. +controls (261.9381,702.5962) and (241.9381,712.6962) .. (216.9381,717.2962) .. +controls (202.3381,719.9962) and (172.9381,719.7962) .. (158.3381,716.8962) .. +controls (140.0381,713.1962) and (129.7381,709.1962) .. (118.3381,701.0962) .. +controls (106.1381,692.4962) and (98.8381,682.1962) .. (91.5381,663.5962) .. +controls (80.4381,635.1962) and (75.2381,608.3962) .. (76.1381,584.1962) .. +controls (76.5381,573.1962) and (76.9381,571.2962) .. (79.6381,565.4962) .. +controls (85.0381,553.8962) and (92.0381,548.0962) .. (107.0381,542.5962) .. +controls (124.8381,536.0962) and (148.5381,532.8962) .. (197.9381,530.2962) .. +controls (208.1381,529.7962) and (226.4381,530.6962) .. (237.4381,532.2962) -- +cycle(564.1381,532.2962) .. +controls (597.8381,535.5962) and (620.2381,541.1962) .. (632.6381,549.2962) .. +controls (642.6381,555.9962) and (647.9381,564.1962) .. (650.0381,576.1962) .. +controls (653.6381,596.8962) and (643.6381,647.3962) .. (630.6381,673.6962) .. +controls (626.2381,682.7962) and (624.3381,685.3962) .. (616.4381,693.2962) .. +controls (603.2381,706.5962) and (590.1381,712.5962) .. (564.6381,717.2962) .. +controls (550.4381,719.9962) and (522.7381,719.7962) .. (508.2381,716.8962) .. +controls (480.4381,711.3962) and (463.6381,702.5962) .. (446.5381,684.6962) .. +controls (428.8381,666.1962) and (411.7381,632.7962) .. (405.4381,604.3962) .. +controls (402.9381,593.0962) and (403.6381,580.0962) .. (407.1381,572.4962) .. +controls (413.8381,557.9962) and (429.7381,547.3962) .. (456.4381,539.6962) .. +controls (488.6381,530.3962) and (521.8381,528.0962) .. (564.1381,532.2962) -- cycle; + +% mustache +\path[ + fill=black, + line width=0.080pt +] (294.9381,961.1962) .. controls (277.8381,964.7962) and (259.4381,974.1962) .. +(239.9381,989.1962) .. controls (236.9381,991.4962) and (225.4381,1000.9962) .. +(214.4381,1010.1962) .. controls (190.2381,1030.3962) and (181.1381,1036.8962) .. +(165.8381,1044.6962) .. controls (149.4381,1053.0962) and (137.7381,1056.8962) .. +(126.2381,1057.4962) .. controls (114.7381,1058.0962) and (109.8381,1056.4962) .. +(104.0381,1050.1962) .. controls (97.1381,1042.6962) and (94.7381,1029.2962) .. +(99.2381,1022.5962) .. controls (102.3381,1017.9962) and (107.6381,1015.2962) .. +(117.2381,1013.1962) .. controls (127.3381,1011.0962) and (133.4381,1008.4962) .. +(134.8381,1005.7962) .. controls (135.8381,1004.0962) and (135.5381,1003.4962) .. +(133.5381,1002.1962) .. controls (121.3381,994.1962) and (102.0381,995.0962) .. +(88.8381,1004.2962) .. controls (78.6381,1011.2962) and (68.7381,1025.7962) .. +(65.4381,1038.2962) .. controls (63.7381,1044.8962) and (63.5381,1056.0962) .. +(64.9381,1062.4962) .. controls (66.6381,1069.8962) and (72.0381,1079.5962) .. +(78.1381,1086.1962) .. controls (111.5381,1122.5962) and (206.0381,1138.0962) .. +(290.6381,1121.1962) .. controls (313.6381,1116.4962) and (326.8381,1111.2962) .. +(341.4381,1100.6962) .. controls (352.2381,1092.8962) and (357.2381,1090.5962) .. +(364.1381,1089.9962) .. controls (369.7381,1089.3962) and (370.0381,1089.4962) .. +(377.1381,1094.3962) .. controls (399.2381,1109.5962) and (430.5381,1119.7962) .. +(472.4381,1125.3962) .. controls (489.0381,1127.5962) and (541.4381,1127.8962) .. +(555.9381,1125.8962) .. controls (588.2381,1121.3962) and (613.9381,1113.9962) .. +(631.6381,1104.0962) .. controls (673.5381,1080.6962) and (680.2381,1040.4962) .. +(647.4381,1009.8962) .. controls (630.3381,993.9962) and (611.1381,990.9962) .. +(600.5381,1002.7962) .. controls (598.5381,1004.8962) and (596.9381,1007.0962) .. +(596.9381,1007.6962) .. controls (596.9381,1009.4962) and (602.5381,1011.4962) .. +(614.7381,1013.9962) .. controls (628.6381,1016.8962) and (633.0381,1019.2962) .. +(634.9381,1025.2962) .. controls (637.8381,1034.0962) and (632.5381,1043.8962) .. +(620.2381,1052.2962) .. controls (611.9381,1057.9962) and (605.1381,1059.4962) .. +(595.6381,1057.8962) .. controls (580.8381,1055.2962) and (572.4381,1049.8962) .. +(519.9381,1008.7962) .. controls (482.8381,979.8962) and (463.8381,968.9962) .. +(439.2381,962.5962) .. controls (432.0381,960.6962) and (427.8381,960.2962) .. +(415.9381,960.2962) .. controls (398.7381,960.2962) and (389.4381,962.1962) .. +(373.0381,969.1962) .. controls (367.3381,971.6962) and (362.1381,973.6962) .. +(361.4381,973.6962) .. controls (360.7381,973.6962) and (355.9381,971.6962) .. +(350.8381,969.2962) .. controls (336.7381,962.5962) and (328.6381,960.5962) .. +(313.9381,960.0962) .. controls (305.6381,959.8962) and (299.2381,960.1962) .. +(294.9381,961.1962) -- cycle; +\end{tikzpicture}} + +\newcommand{\dad}[1][1]{\begin{tikzpicture}[scale=#1, transform shape] +\node[ + thick, + rectangle, + minimum width=4cm, + minimum height=3cm, + rounded corners +] (box) {}; + +\begin{scope}[ + scale=2, + yshift=-1.7cm, + xshift=-.13cm +] +\clip (box.south west) rectangle (box.north east); +\anteater +\node at (0, 1.72) {\accessories}; +\end{scope} + +\node[ + draw=araracolour, + rectangle, + rounded corners=2pt, + fill=araracolour!20!white, + inner sep=4pt +] at ([yshift=-.5cm]box.south) {\parbox{3.5cm}{\centering\small\em Anteater facts\\ +with Peter's dad}}; +\end{tikzpicture}} + +\definecolor{pinkglasses}{RGB}{128,0,128} + +\newcommand{\hair}{% +\begin{tikzpicture}[ + y=0.80pt, + x=0.80pt, + yscale=-1.4, + xscale=1.4, + inner sep=0pt, + outer sep=0pt +] +\path[ + fill=black +] (17.0420,6.0910) .. controls (12.7510,7.3280) and (12.2310,11.1080) .. +(11.8050,13.0730) .. controls (11.3790,15.0400) and (10.6560,17.5560) .. +(11.1750,19.1090) .. controls (10.2290,18.4300) and (10.4470,17.3390) .. +(10.4470,17.3390) .. controls (10.4470,17.3390) and (4.7500,25.7270) .. +(14.6650,29.8970) .. controls (13.9870,30.7220) and (10.7380,29.4140) .. +(10.7380,29.4140) .. controls (10.7380,29.4140) and (10.5200,31.2310) .. +(12.7250,30.6750) .. controls (9.1380,33.7790) and (5.3550,26.0690) .. +(5.3550,26.0690) -- (5.8400,28.2530) .. controls (5.8400,28.2530) and (4.5780,28.5910) .. +(2.6880,17.8760) .. controls (0.7980,7.1580) and (8.0710,1.6300) .. (9.8650,0.9510) .. +controls (11.6590,0.2710) and (14.7140,0.0780) .. (16.3140,0.9510) .. +controls (19.9510,-1.8140) and (23.5730,2.2030) .. (24.4110,3.4720) .. +controls (25.2490,4.7430) and (27.9030,8.5160) .. (28.3880,11.0850) .. +controls (28.8720,13.6530) and (31.2480,31.0860) .. (22.2790,28.6870) .. +controls (25.4300,27.7900) and (25.4300,22.1880) .. (25.4300,22.1880) .. +controls (25.4300,22.1880) and (22.9810,24.7100) .. (22.2300,23.6920) .. +controls (25.4300,22.1880) and (25.5520,15.6690) .. (23.5400,12.0060) .. +controls (21.9730,9.0630) and (18.5870,6.7300) .. (17.0420,6.0910) -- cycle; +\end{tikzpicture}} + +\newcommand{\glasses}{% +\begin{tikzpicture}[ + y=0.80pt, + x=0.80pt, + yscale=-.2, + xscale=.2, + inner sep=0pt, + outer sep=0pt +] +\begin{scope}[ + shift={(-25.07793,-59.30764)} +] +\path[fill=pinkglasses,nonzero rule,line width=0.028pt] (31.6043,59.6053) .. +controls (28.0060,60.1443) and (25.0779,61.4535) .. (25.0779,62.5231) .. +controls (25.0779,62.7567) and (25.9951,63.3250) .. (27.1240,63.7910) .. +controls (31.3253,65.5249) and (32.2359,66.4389) .. (37.1406,73.8473) .. +controls (38.8222,76.3873) and (41.5881,80.0071) .. (43.3400,81.9612) .. +controls (50.2579,89.6764) and (55.7343,92.5720) .. (66.3529,94.1285) .. +controls (72.3149,95.0023) and (75.6172,94.8746) .. (80.8168,93.5693) .. +controls (88.1546,91.7271) and (92.0344,88.9779) .. (95.4564,83.1959) .. +controls (97.6069,79.5623) and (98.5566,78.9626) .. (102.1599,78.9626) .. +controls (105.7229,78.9626) and (106.7220,79.5760) .. (108.7639,83.0195) .. +controls (110.9603,86.7237) and (112.5710,88.6054) .. (114.8246,90.1008) .. +controls (119.1140,92.9470) and (128.2654,95.1434) .. (133.8746,94.6732) .. +controls (146.2571,93.6346) and (153.4679,90.3231) .. (160.5548,82.4198) .. +controls (163.7718,78.8320) and (166.3481,75.3995) .. (168.7894,71.4484) .. +controls (171.2087,67.5326) and (173.2485,65.5979) .. (176.4902,64.1445) .. +controls (178.0071,63.4647) and (179.2418,62.7210) .. (179.2418,62.4878) .. +controls (179.2418,61.7759) and (177.3015,60.6477) .. (174.9732,60.0057) .. +controls (173.0499,59.4755) and (171.3043,59.3912) .. (163.1904,59.4360) .. +controls (148.3865,59.5174) and (144.2463,60.3013) .. (109.9210,69.5183) .. +controls (105.3349,70.7499) and (101.0751,71.0293) .. (97.7502,70.3170) .. +controls (96.4883,70.0465) and (90.7299,68.5574) .. (84.9443,67.0059) .. +controls (70.5510,63.1447) and (62.6551,61.3417) .. (54.6760,60.0932) .. +controls (49.8429,59.3368) and (35.4310,59.0320) .. (31.6043,59.6053) -- +cycle(61.9432,66.4778) .. controls (66.9188,67.3121) and (74.3257,69.2894) .. +(82.5807,71.9864) .. controls (90.2713,74.4992) and (92.8077,76.2134) .. +(92.7975,78.8920) .. controls (92.7852,82.1249) and (89.4599,86.1225) .. +(85.0149,88.2491) .. controls (80.2234,90.5411) and (75.4899,91.2706) .. +(69.5985,90.6250) .. controls (64.3421,90.0490) and (61.0930,89.1024) .. +(56.2635,86.7395) .. controls (50.6896,84.0129) and (46.9510,80.6612) .. +(44.9516,76.5989) .. controls (43.2501,73.1417) and (42.9986,70.5195) .. +(44.1972,68.7320) .. controls (45.7894,66.3578) and (48.9257,65.5231) .. +(55.2404,65.7937) .. controls (57.1807,65.8770) and (60.1970,66.1846) .. +(61.9432,66.4778) -- cycle(157.0168,66.4397) .. +controls (161.0198,67.7657) and (161.9222,71.2014) .. +(159.5833,76.2109) .. controls (156.0940,83.6838) and (145.9396,89.5096) .. +(134.4038,90.6564) .. controls (124.3496,91.6562) and (115.1051,87.8921) .. +(112.1802,81.6084) .. controls (110.7116,78.4531) and (111.6849,76.2441) .. +(115.3538,74.4047) .. controls (118.8759,72.6390) and (133.3102,68.2554) .. +(140.2952,66.8298) .. controls (146.5746,65.5482) and (153.8171,65.3792) .. +(157.0168,66.4397); +\end{scope} +\end{tikzpicture}} + +\newcommand{\mum}[1][1]{\begin{tikzpicture}[scale=#1, transform shape] +\node[ + thick, + rectangle, + minimum width=4cm, + minimum height=3cm, + rounded corners +] (box) {}; + +\begin{scope}[ + scale=2, + yshift=-1.7cm, + xshift=-.13cm +] +\clip (box.south west) rectangle (box.north east); +\anteater +\node at (0, 1.55) {\glasses}; +\node at (-0.07, 1.6) {\hair}; +\end{scope} + +\node[ + draw=warningcolour, + rectangle, + rounded corners=2pt, + fill=warningcolour!20!white, + inner sep=4pt +] at ([yshift=-.5cm]box.south) {\parbox{3.5cm}{\centering\small\em Interesting tips\\ +with Peter's mum}}; +\end{tikzpicture}} + +\newtcolorbox{talkbox}{ + sidebyside, + lower separated=false, + lefthand width=3.3cm, + sidebyside gap=10pt, + colback=white, + boxrule=0pt, + frame hidden, + colframe=white, + left=0pt, + right=0pt, + top=0pt, + bottom=0pt +} + +\newtcolorbox{factbox}{ + sidebyside, + lower separated=false, + righthand width=3.3cm, + sidebyside gap=14pt, + colback=attentioncolour!20!white, + boxrule=0pt, + frame hidden, + colframe=white, + left=6pt, + right=6pt, + top=4pt, + bottom=4pt, + width=1\textwidth +} + +\newtcolorbox{tipbox}{ + sidebyside, + lower separated=false, + righthand width=3.3cm, + sidebyside gap=14pt, + colback=pinkglasses!20!white, + boxrule=0pt, + frame hidden, + colframe=white, + left=6pt, + right=6pt, + top=4pt, + bottom=4pt, + width=1\textwidth +} + +\title{A quickstart guide to \arara} +\author{Peter, the anteater, for the Island of \TeX} + +\begin{document} + +\maketitle + +\parskip=1em + +Welcome to \arara, the cool \TeX\ automation tool! This document is intended to be a quickstart guide, providing the basic instructions to start using our tool. We will help our good friend Peter,\footnote{Peter was graduated from Termite High School, Alta Floresta, Mato Grosso, Brazil. He went on to study at the California Institute of Ti\textit{k}Zlings with a scholarship from San Diego Zoo. He completed his university education at the Rain Forest Academy, Manaus. He is currently teaching as a Fellow of the Federal University for the Advancement of Furry Animals, Cuiabá. He is a Corresponding Member of Duckpond Academy, Sempione Park, Milano, Italy.}\ the anteater, in his learning adventure. He is very excited about it! Hello, Peter! + +\begin{talkbox} +\peter[.7] +\tcblower +\em Hello, nice to meet you, person from the Island of \TeX! I am Peter, the anteater. So I heard about this tool named \arara, what is it? Is there anything to do with \TeX\ and friends? +\end{talkbox} + +As a matter of fact, it is! \arara\ is a \TeX\ automation tool. The name was chosen as an homage to a Brazilian bird of the same name, which is a macaw. The word \emph{arara} comes from the Tupian word \emph{a'rara}, which means \emph{big bird}. The tool is an effort to provide a concise way to automate the daily \TeX\ workflow for users and also package writers. + +\begin{talkbox} +\peter[.7] +\tcblower +\em It definitely sounds intriguing! So tell me, how does \arara\ work? Does it do everything automatically for me, like other tools? Do things happen by magic? +\end{talkbox} + +A very good question, Peter. The best way to explain how \arara\ works is to provide a quick comparison with similar tools. I believe you are familiar with \TeX\ documents, right? Let us use the following file \rbox{article.tex} as an example: + +\begin{ncodebox}{Source file}{teal}{\icnote}{white}{article.tex} +\documentclass{article} + +\begin{document} +Hello world! +\end{document} +\end{ncodebox} + +How would one successfully compile \rbox{article.tex} with \rbox{latexmk} and \rbox{rubber}, for instance? It is quite straightforward: it is just a matter of providing the file to the tool and letting it do the hard work: + +\begin{codebox}{Terminal}{teal}{\icnote}{white} +$ latexmk -pdf article.tex +$ rubber --pdf article.tex +\end{codebox} + +The mentioned tools perform an analysis on the file and decide what has to be done. However, if one tries to invoke \rbox{arara} on \rbox{article.tex}, I am afraid \emph{nothing} will be generated; the truth is, \arara\ does not know what to do with your file, and the tool will even raise an error message complaining about this issue: + +\begin{codebox}{Terminal}{teal}{\icnote}{white} +$ arara article.tex + __ _ _ __ __ _ _ __ __ _ + / _` | '__/ _` | '__/ _` | +| (_| | | | (_| | | | (_| | + \__,_|_| \__,_|_| \__,_| + +Processing "article.tex" (size: 70 B, last modified: 12/28/2020 +07:03:16), please wait. + + ERROR + +It looks like no directives were found in the provided file. Make +sure to include at least one directive and try again. + +Total: 0.04 seconds +\end{codebox} + +Peter, this is the major difference of \arara\ when compared to other tools: \emph{it is not an automatic process and the tool does not employ any guesswork on its own}. You are in control of your documents; \arara\ will not do anything unless you \emph{teach it how to do a task and explicitly tell it to execute the task}. So, it is not magic. + +\begin{talkbox} +\peter[.7] +\tcblower +\em I see. On the other hand, this approach gives me, as user, full control of my document compilation. Being aware of the compilation steps makes me understand the \TeX\ tooling better. Quite clever! Now, do tell me: how does one tell \arara\ to do a task? +\end{talkbox} + +First of all, Peter, \arara\ has to know \emph{how} to do a task. This is done by defining rules. A rule is a formal description of how the tool should handle a certain task. For example, if we want to use \rbox{pdflatex} with \arara, we need a rule for that. Once a rule is defined, the tool automatically provides an access layer to the user. Note that \arara\ is distributed with dozens of predefined rules, so you already have several options out of the box to set up your workflow. + +\begin{factbox} +\small\em Giant anteaters can be found throughout South and Central America, though their numbers have diminished considerably from the latter. To thrive, they need to be able to move throughout large areas with patches of forest. They can often be found in tropical and dry forests, savannas, and open grasslands, where the ants upon which they feed are abundant.~\href{https://www.nationalgeographic.com/animals/mammals/g/giant-anteater/}{\faExternalLink} +\tcblower +\dad[.7] +\end{factbox} + +Now, back to your question. Once we know how to execute a task, we need to explicitly tell \arara\ when to do it. That is actually the easy part, provided that you have everything up and running. We accomplish the task by adding a special comment line, hereafter known as a \emph{directive}, somewhere in our document to indicate how the tool should work, e.g: + +\begin{codebox}{Source file}{teal}{\icnote}{white} +% arara: pdflatex +\end{codebox} + +\begin{talkbox} +\peter[.7] +\tcblower +\em Makes sense. So, a directive is a special comment line which is not the command to be executed, but the name of the rule associated with that directive. Is that correct? +\end{talkbox} + +Perfect, Peter! That is basically how \arara\ works: we teach the tool to do a task by providing a rule, and tell it to execute it +via directives in the source code. Let us see how our \rbox{article.tex} file should be: + +\begin{ncodebox}{Source file}{teal}{\icnote}{white}{article.tex} +% arara: pdflatex +\documentclass{article} + +\begin{document} +Hello world! +\end{document} +\end{ncodebox} + +Note, Peter, that the tool expects \emph{you} to provide a list of tasks, and this is done by inserting special comments, i.e, directives, in the source file. Since we just added one directive in our document, let us see how \arara\ behaves with this updated code: + +\begin{codebox}{Terminal}{teal}{\icnote}{white} +$ arara article.tex + __ _ _ __ __ _ _ __ __ _ + / _` | '__/ _` | '__/ _` | +| (_| | | | (_| | | | (_| | + \__,_|_| \__,_|_| \__,_| + +Processing "article.tex" (size: 88 B, last modified: 12/28/2020 +07:05:05), please wait. + +(PDFLaTeX) PDFLaTeX engine .............................. SUCCESS + +Total: 0.56 seconds +\end{codebox} + +\begin{talkbox} +\peter[.7] +\tcblower +\em Goodness me, it worked like a charm! The moment we specified a directive, \arara\ knew exactly what I wanted to do with that particular file! Awesome! +\end{talkbox} + +Exactly! You see, Peter, there is no guesswork from \arara. The tool will do exactly what you tell it to do, no more, no less. There is a lot of freedom to this design, which gives you an interesting way to enhance your \TeX\ experience. + +\begin{factbox} +\small\em Anteaters are not aggressive, but they can be fierce. A cornered anteater will rear up on its hind legs, using its tail for balance, and lash out with dangerous claws. The giant anteater's claws are some four inches long, and the animal can fight off even a puma or jaguar.~\href{https://www.nationalgeographic.com/animals/mammals/g/giant-anteater/}{\faExternalLink} +\tcblower +\dad[.7] +\end{factbox} + +\begin{talkbox} +\peter[.7] +\tcblower +\em I have been wondering: there are scenarios in which we need to provide additional information to the underlying commands~---~for instance, we need to enable shell escape when using the \rbox[araracolour]{minted} package. How can we achieve this? +\end{talkbox} + +For such scenarios, \arara\ provides a second type of directive, a parametrized one, which allows passing arguments to the corresponding rule. From your example, to enable shell escape, one simply needs to write the following directive: + +\begin{codebox}{Source file}{teal}{\icnote}{white} +% arara: pdflatex: { shell: yes } +\end{codebox} + +Of course, \rbox[cyan]{shell} is not taken randomly, but defined in the rule scope, otherwise \arara\ would raise an error about an invalid key. The reference manual has a list of all available keys for each predefined rule. It is worth a read. + + +\begin{tipbox} +\small\em Do you know that a directive can be split into multiple lines? Simply use the \abox[araracolour]{arara: {-}{-}>} mark to each line which should compose the directive. Although it is possible to spread lines of a multiline directive all over the code, it is considered good practice to keep them together for easier reading and editing. +\tcblower +\mum[.7] +\end{tipbox} + +\begin{talkbox} +\peter[.7] +\tcblower +\em Great, these directives are really convenient! I am now curious on how to explore \arara: shall we move to a more complex document? Consider the following addition to my document: +\end{talkbox} + +\begin{ncodebox}{Source file}{teal}{\icnote}{white}{article.tex} +\documentclass{article} + +\begin{document} +\section{Termite recipes} +\label{sec:termiterecipes} + +Hello, this is Section~\ref{sec:termiterecipes}. +\end{document} +\end{ncodebox} + +\begin{talkbox} +\peter[.7] +\tcblower +\em As we can see, this document has to be compiled twice, or the reference to the first section will not be resolved accordingly. How can I tackle this scenario with \arara? +\end{talkbox} + +The solution is quite straightforward, Peter: how about adding two directives into your document? You can keep them together for convenience (usually at the top), but they can happen anywhere in your file. Let us update the code: + +\begin{ncodebox}{Source file}{teal}{\icnote}{white}{article.tex} +% arara: pdflatex +% arara: pdflatex +\documentclass{article} + +\begin{document} +\section{Termite recipes} +\label{sec:termiterecipes} + +Hello, this is Section~\ref{sec:termiterecipes}. +\end{document} +\end{ncodebox} + +The execution workflow is now as expected: our document was correctly compiled twice, as it should be, so references are resolved accordingly! + +\begin{codebox}{Terminal}{teal}{\icnote}{white} +$ arara article.tex + __ _ _ __ __ _ _ __ __ _ + / _` | '__/ _` | '__/ _` | +| (_| | | | (_| | | | (_| | + \__,_|_| \__,_|_| \__,_| + +Processing 'article.tex' (size: 196 B, last modified: 01/07/2021 +08:18:00), please wait. + +(PDFLaTeX) PDFLaTeX engine .............................. SUCCESS +(PDFLaTeX) PDFLaTeX engine .............................. SUCCESS + +Total: 1.60 seconds +\end{codebox} + +\begin{talkbox} +\peter[.7] +\tcblower +\em Cool! But I have been wondering: once the references are resolved, subsequents runs will add an extra, unnecessary compilation. It would not do any harm, surely, but is there a way to avoid it? +\end{talkbox} + +There is a way, Peter! We can use logical expressions and special operators and methods processed at runtime in order to determine whether and how a directive should be processed. This feature is named \emph{directive conditional}, or simply \emph{conditional} for short. Let us update the document to include this feature: + +\begin{ncodebox}{Source file}{teal}{\icnote}{white}{article.tex} +% arara: pdflatex +% arara: pdflatex if found('log', 'undefined references') +\documentclass{article} + +\begin{document} +\section{Termite recipes} +\label{sec:termiterecipes} + +Hello, this is Section~\ref{sec:termiterecipes}. +\end{document} +\end{ncodebox} + +Observe, Peter, that the first directive has no conditional, so it will always be processed. The second one, however, has an associated logical test: check if the log file contains a warning about undefined references and, if so, process the directive itself. When references are resolved accordingly, the tool will not process the second directive at all, as we can see in the following run: + +\begin{codebox}{Terminal}{teal}{\icnote}{white} +$ arara article.tex + __ _ _ __ __ _ _ __ __ _ + / _` | '__/ _` | '__/ _` | +| (_| | | | (_| | | | (_| | + \__,_|_| \__,_|_| \__,_| + +Processing 'article.tex' (size: 236 B, last modified: 01/07/2021 +08:42:02), please wait. + +(PDFLaTeX) PDFLaTeX engine .............................. SUCCESS + +Total: 0.97 seconds +\end{codebox} + +In this particular case, the test is evaluated beforehand, and the directive is processed if, and only if, the result of such evaluation is true. This directive, when the conditional holds true, is executed at most once. + +\begin{tipbox} +\small\em When using certain conditional operators, there are no conceptual guarantees for proper halting of unbounded loops. However, do not worry, dear! The team has provided a technical solution for potentially infinite iterations: \arara\ has a predefined maximum number of loops. The default value is set to 10, but it can be overridden. +\tcblower +\mum[.7] +\end{tipbox} + +\begin{talkbox} +\peter[.7] +\tcblower +\em These conditionals can help me dictate how my workflow should behave in certain scenarios! I gather there are several possible ways of tackling them, right? +\end{talkbox} + +Correct, Peter. In the previous example, we used the \rbox[attentioncolour]{\color{black}if} operator, but we could have used \rbox[attentioncolour]{\color{black}while} or \rbox[attentioncolour]{\color{black}until} as well. The logical expression could also be rewritten. We could even have combined these two directives into one! So you see, there is always room for improvement. + +\begin{factbox} +\small\em The giant anteater uses its sharp claws to tear an opening into an anthill and put its long snout, sticky saliva, and efficient tongue to work. But it has to eat quickly, flicking its tongue up to 150 times per minute. Ants fight back with painful stings, so an anteater may spend only a minute feasting on each mound.~\href{https://www.nationalgeographic.com/animals/mammals/g/giant-anteater/}{\faExternalLink} +\tcblower +\dad[.7] +\end{factbox} + +If this subject caught your attention, take a look at the reference manual for more details on directive conditionals and available methods. There are multiple code excerpts to help you understand better the inner workings. + +\begin{talkbox} +\peter[.7] +\tcblower +\em I will certainly check them out! Now, I am curious to see other directives in action together, so let us try a different yet common scenario: bibliographies and citations. Consider the following bibliography file, containing a reference\footnotemark\ to my doctoral thesis: +\end{talkbox} + +\footnotetext[2]{Peter’s doctoral thesis ``On flexibilty: \LaTeX, latex and rubber'' was published at Manaus. His reputation in the academic world is based on his famous study ``The Mandelbrot heritage: towards a fractal topology of formicaries''. Some of his works arose from a fruitful cooperation with the well known Brazilian-Italian savant Professore P.\ van Duck.} + +\begin{ncodebox}{Source file}{teal}{\icnote}{white}{bibliography.bib} +@phdthesis{peter:2020, + author = {Peter Anteater}, + title = {On flexibility: \LaTeX, latex and rubber}, + school = {Polytechnic University of P{\^{a}}ntano Fundo}, + year = 2020, + address = {Pantanal}, + month = {jan} +} +\end{ncodebox} + +\begin{talkbox} +\peter[.7] +\tcblower +\em I want to cite my thesis in the article you and I are writing for this quickstart guide. From the \TeX\ side, it is quite straightforward! How about \arara? Here is my code: +\end{talkbox} + +\begin{ncodebox}{Source file}{teal}{\icnote}{white}{article.tex} +\documentclass{article} + +\begin{document} +\section{Termite recipes} +\label{sec:termiterecipes} + +A citation from my thesis~\cite{peter:2020}. + +\bibliographystyle{alpha} +\bibliography{bibliography} +\end{document} +\end{ncodebox} + +Peter, remember that \arara\ does not employ any guesswork, so do not expect it to magically compile your document and get all the citations correctly. We need to explicitly tell it what to do, as if we were explaining the compilation steps to a friend. \arara\ is focused on reproducibility. + +\begin{factbox} +\small\em Anteaters are edentate animals -- they have no teeth. But their long tongues are more than sufficient to lap up the 35,000 ants and termites they swallow whole each day. As the largest of all four anteater species, the giant anteater can reach eight feet long from the tip of its snout to the end of its tail.~\href{https://www.nationalgeographic.com/animals/mammals/g/giant-anteater/}{\faExternalLink} +\tcblower +\dad[.7] +\end{factbox} + +We, as users, can learn a great deal about \TeX\ and friends by organising our workflow into directives. Let us review what should be done in order to correctly compile your document: + +\begin{enumerate} +\item For starters, we need to run the \TeX\ engine in order to write (amongst other things) the relevant bibliography information to the auxiliary file. We can achieve this by inserting the following directive: + +\begin{codebox}{Directive}{teal}{\icnote}{white} +% arara: pdflatex +\end{codebox} + +\item Once the auxiliary file holds the relevant bibliography information, we need to run the Bib\TeX\ tool as a means to map entries from the bibliography database to the existing citations into an intermediate bibliography file. We can achieve this by inserting the following directive: + +\begin{codebox}{Directive}{teal}{\icnote}{white} +% arara: bibtex +\end{codebox} + +\item Once the intermediate bibliography file is generated, we can now have a proper bibliography section in our document, so we need to run the \TeX\ engine again. We can achieve this by inserting the following directive: + +\begin{codebox}{Directive}{teal}{\icnote}{white} +% arara: pdflatex +\end{codebox} + +\item However, the citations are still not yet referenced in the document, so a final run of the \TeX\ engine is required in order to correctly adjust these references. We can achieve this by inserting the following directive: + +\begin{codebox}{Directive}{teal}{\icnote}{white} +% arara: pdflatex +\end{codebox} +\end{enumerate} + +And we are done! These are the compilation steps required to correctly generate your article from the given source and bibliography files. Note that the entire workflow involves two different tools working together: the \TeX\ engine and the Bib\TeX\ tool. + +\begin{talkbox} +\peter[.7] +\tcblower +\em Wait a minute, no less than four compilation steps? I would never guessed it! This is great: \arara\ is also helping me understand better how the \TeX\ workflow works! +\end{talkbox} + +Quite true, Peter! \arara\ tries its best to help users think out of the box! Now that we know the exact compilation steps to be taken, we just need to arrange them in the correct order in our document: + +\begin{ncodebox}{Source file}{teal}{\icnote}{white}{article.tex} +% arara: pdflatex +% arara: bibtex +% arara: pdflatex +% arara: pdflatex +\documentclass{article} + +\begin{document} +\section{Termite recipes} +\label{sec:termiterecipes} + +A citation from my thesis~\cite{peter:2020}. + +\bibliographystyle{alpha} +\bibliography{bibliography} +\end{document} +\end{ncodebox} + +Now, let us take \arara\ into action! By running the tool on our article, we can see all compilation steps being performed in the exact order we specified in the source code, as expected: + +\begin{codebox}{Terminal}{teal}{\icnote}{white} +$ arara article.tex + __ _ _ __ __ _ _ __ __ _ + / _` | '__/ _` | '__/ _` | +| (_| | | | (_| | | | (_| | + \__,_|_| \__,_|_| \__,_| + +Processing 'article.tex' (size: 281 B, last modified: 01/08/2021 +06:17:20), please wait. + +(PDFLaTeX) PDFLaTeX engine .............................. SUCCESS +(BibTeX) The BibTeX reference management software ....... SUCCESS +(PDFLaTeX) PDFLaTeX engine .............................. SUCCESS +(PDFLaTeX) PDFLaTeX engine .............................. SUCCESS + +Total: 2.49 seconds +\end{codebox} + +\begin{talkbox} +\peter[.7] +\tcblower +\em Great! I see \arara\ is quite expressive! I am very curious: what about other possibilities, will I learn them by looking at the reference manual? Surely there are way more features to discover. +\end{talkbox} + +Of course, Peter! The reference manual contains everything there is to know about \arara, so it is a great resource for learning! In this quickstart guide, we simply covered the basics, as an introductory material. The tool has several features, including support for working directory, processing of multiple files, argument passing through command line flags, configuration files, default preambles, file hashing, safe mode, and much more. There is a world of possibilities! + +\begin{talkbox} +\peter[.7] +\tcblower +\em Thank you very much, person from the Island of \TeX! I am sure I will have a lot of fun with \arara! Should I need any assistance, how can I contact the team? +\end{talkbox} + +Great talking to you, Peter! If you run into any issue with \arara, please let us know. We all have very active profiles in the \href{https://tex.stackexchange.com/}{\TeX\ community at StackExchange}, so just use the \rbox[gray]{arara} tag in your question and we will help you the best we can (also, take a look at their \href{https://tex.meta.stackexchange.com/q/1436}{starter guide}). We also have a \href{https://gitter.im/Island-of-TeX/arara}{Gitter} and \href{https://matrix.to/#/!HfEWIEvFtDplCLSQvz:matrix.org?via=matrix.org}{Matrix} chat rooms, in which we occasionally hang out. Also, if you think the report is worthy of an issue, open one in our \href{https://gitlab.com/islandoftex/arara/issues}{GitLab repository}. Happy \TeX ing with \arara, Peter! + +\end{document} diff --git a/Master/texmf-dist/doc/support/arara/arara.sty b/Master/texmf-dist/doc/support/arara/arara.sty index 56eaf7608d7..3430afdb051 100644 --- a/Master/texmf-dist/doc/support/arara/arara.sty +++ b/Master/texmf-dist/doc/support/arara/arara.sty @@ -56,7 +56,6 @@ \RequirePackage{comfortaa} \RequirePackage[regular]{sourcecodepro} -\RequirePackage{adforn} \RequirePackage{fontawesome} \RequirePackage{forest} @@ -426,6 +425,7 @@ \newcommand{\ctbox}[1]{\rbox[cyan]{#1}} \newcommand{\mdbox}[3]{\ctbox{#1}~\mtbox{#2}\hfill\rrbox{#3}} \newcommand{\mddbox}[4]{\ctbox{#1}~\mdbox{#2}{#3}{#4}} +\newcommand{\mdddbox}[5]{\ctbox{#1}~\mddbox{#2}{#3}{#4}{#5}} \renewcommand{\secheadstyle}{\Large\normalfont\em} \renewcommand{\subsecheadstyle}{\large\normalfont\em} @@ -441,8 +441,8 @@ \renewcommand{\printpartname}{\centering\includegraphics[scale=.3]{logos/bird.pdf}\par\partnamefont \textcolor{araracolour}{part}} \renewcommand{\printpartnum}{\partnumfont\textcolor{araracolour}{\numtoname{\c@part}}} \cftpagenumbersoff{part} -\renewcommand\partnumberline[1]{\hfil\hspace\@tocrmarg {\normalfont\normalsize\adforn{16}}\quad#1\hspace{0.5em}---\hspace{0.5em}} -\renewcommand*{\cftpartafterpnum}{\quad\adforn{44}} +\renewcommand\partnumberline[1]{\hfil\hspace\@tocrmarg#1\hspace{0.5em}---\hspace{0.5em}} +\renewcommand*{\cftpartafterpnum}{} \setlength\cftchapternumwidth{2em} \setlength\cftsectionnumwidth{3em} diff --git a/Master/texmf-dist/doc/support/arara/chapters/building.tex b/Master/texmf-dist/doc/support/arara/chapters/building.tex index 9c9b27c1244..4f894f01b70 100644 --- a/Master/texmf-dist/doc/support/arara/chapters/building.tex +++ b/Master/texmf-dist/doc/support/arara/chapters/building.tex @@ -2,7 +2,7 @@ \chapter{Building from source} \label{chap:buildingfromsource} -\arara\ is a Kotlin and Java application licensed under the \href{http://www.opensource.org/licenses/bsd-license.php}{New BSD License}, a verified GPL-compatible free software license, and the source code is available in the project repository at \href{https://gitlab.com/islandoftex/arara}{GitLab}. This chapter provides detailed instructions on how to build our tool from source. +\arara\ is a Kotlin application licensed under the \href{http://www.opensource.org/licenses/bsd-license.php}{New BSD License}, a verified GPL-compatible free software license, and the source code is available in the project repository at \href{https://gitlab.com/islandoftex/arara}{GitLab}. This chapter provides detailed instructions on how to build our tool from source. \section{Requirements} \label{sec:requirements} @@ -14,12 +14,12 @@ In order to build our tool from source, we need to ensure that our development e \begin{codebox}{Terminal}{teal}{\icnote}{white} $ git --version -git version 2.17.1 +git version 2.29.2 \end{codebox} Please refer to the \rbox{git} \href{https://git-scm.com/}{project website} in order to obtain specific installation instructions for your operating system. In general, most recent Unix systems have \rbox{git} installed out of the shelf. -\item Our tool is written in the Java programming language, so we need a proper Java Development Kit, a collection of programming tools for the Java platform. Our source code is known to be compliant with several vendors, including Oracle, OpenJDK, and Azul Systems. In order to check if your operating system has the proper tools, run the following command in the terminal (version numbers might vary): +\item Our tool is written in the Kotlin programming language, so we need a proper Java Development Kit, a collection of programming tools for the Java platform. Our source code is known to be compliant with several vendors, including Oracle, OpenJDK, and Azul Systems. In order to check if your operating system has the proper tools, run the following command in the terminal (version numbers might vary): \begin{codebox}{Terminal}{teal}{\icnote}{white} $ javac -version @@ -28,7 +28,7 @@ javac 1.8.0_171 The previous command, as the name suggests, refers to the \rbox{javac} tool, which is the Java compiler itself. The most common Java Development Kit out there is from \href{http://www.oracle.com/technetwork/java/javase/downloads/index.html}{Oracle}. However, several Linux distributions (as well as some developers, yours truly included) favour the OpenJDK vendor, so your mileage may vary. Please refer to the corresponding website of the vendor of your choice in order to obtain specific installation instructions for your operating system. -\item As a means to provide a straightforward and simplified compilation workflow, \arara\ relies on Gradle, a software project management and comprehension tool. Gradle is a build tool just like arara with a much more comprehensive build framework to provide support for the JVM ecosystem. In order to check if \rbox{gradle}, the Gradle binary, is available in your operating system, run the following command in the terminal (version numbers might vary): +\item As a means to provide a straightforward and simplified compilation workflow, \arara\ relies on Gradle, a software project management and comprehension tool. Gradle is a build tool just like ours with a much more comprehensive build framework to provide support for the JVM ecosystem. In order to check if \rbox{gradle}, the Gradle binary, is available in your operating system, run the following command in the terminal (version numbers might vary): \begin{codebox}{Terminal}{teal}{\icnote}{white} $ gradle --version @@ -41,7 +41,8 @@ Revision: <unknown> Kotlin: 1.3.50 Groovy: 2.5.8 -Ant: Apache Ant(TM) version 1.10.7 compiled on September 1 2019 +Ant: Apache Ant(TM) version 1.10.7 compiled + on September 1 2019 JVM: 1.8.0_232 (Oracle Corporation 25.232-b09) OS: Linux 5.5.0-1-MANJARO amd64 \end{codebox} @@ -101,7 +102,7 @@ Great, we are in the correct location! From the previous output, let us inspect $ gradle build \end{codebox} -Gradle is based around the central concept of a build life cycle. The \rbox{compile} phase, as the name suggests, compiles the source code of the project using the underlying Java compiler. After compiling, the code can be packaged, tested and run. The \rbox{build} target actually compiles, tests and packages our tool. Afterwards, you will have a \abox[araracolour]{application/build/libs/} directory with multiple JAR files, one containing \rbox{with-deps}. That file is ready to run as it bundles all dependencies. Subsequent builds will be significantly faster than the first build because they do not fetch dependencies and rely on a build cache. Finally, after some time, Gradle will output the following message as result (please note that the entire compilation and packaging only took 4 seconds on my development machine due to an existing local cache): +Gradle is based around the central concept of a build life cycle. The \rbox{compile} phase, as the name suggests, compiles the source code of the project using the underlying Java compiler. After compiling, the code can be packaged, tested and run. The \rbox{build} target actually compiles, tests and packages our tool. Afterwards, you will have a \abox[araracolour]{cli/build/libs/} directory with multiple JAR files, one containing \rbox{with-deps}. That file is ready to run as it bundles all dependencies. Subsequent builds will be significantly faster than the first build because they do not fetch dependencies and rely on a build cache. Finally, after some time, Gradle will output the following message as result (please note that the entire compilation and packaging only took 4 seconds on my development machine due to an existing local cache): \begin{codebox}{Terminal}{teal}{\icnote}{white} BUILD SUCCESSFUL in 4s @@ -111,7 +112,7 @@ BUILD SUCCESSFUL in 4s Now, let us move the resulting Java archive file from that particular directory to our current directory. Run the following command in the terminal (please note that the Java archive file was also renamed during the move operation): \begin{codebox}{Terminal}{teal}{\icnote}{white} -$ mv application/build/libs/arara-with-deps-*.jar arara.jar +$ mv cli/build/libs/arara-cli-with-deps-*.jar arara.jar \end{codebox} Now, our current directory contains the final \rbox{arara.jar} Java archive file properly built from source. This file can be safely distributed and deployed, as seen later on, in Chapter~\ref{chap:deployingthetool}, on page~\pageref{chap:deployingthetool}. You can also test the resulting file by running the following command in the terminal: @@ -123,23 +124,31 @@ $ java -jar arara.jar | (_| | | | (_| | | | (_| | \__,_|_| \__,_|_| \__,_| -Usage: arara [OPTIONS] [file]... +Usage: arara [OPTIONS] file... Options: - -l, --log Generate a log output - -v, --verbose / -s, --silent Print the command output - -n, --dry-run Go through all the motions of running a - command, but with no actual calls - -H, --header Extract directives only in the file header - -t, --timeout INT Set the execution timeout (in milliseconds) - -L, --language TEXT Set the application language - -m, --max-loops INT Set the maximum number of loops (> 0) - -p, --preamble TEXT Set the file preamble based on the - configuration file - -d, --working-directory DIRECTORY - Set the working directory for all tools - -V, --version Show the version and exit - -h, --help Show this message and exit + -l, --log Generate a log output + -v, --verbose / -s, --silent Print the command output + -n, --dry-run Go through all the motions of running + a command, but with no actual calls + -s, --safe-run Run in safe mode and disable + potentially harmful features. Make + sure your projects uses only allowed + features. + -H, --header Extract directives only in the file + header + -p, --preamble TEXT Set the file preamble based on the + configuration file + -t, --timeout INT Set the execution timeout (in + milliseconds) + -L, --language TEXT Set the application language + -m, --max-loops INT Set the maximum number of loops (> 0) + -d, --working-directory PATH Set the working directory for all + tools + -P, --call-property VALUE Pass parameters to the application + to be used within the session. + -V, --version Show the version and exit + -h, --help Show this message and exit Arguments: file The file(s) to evaluate and process diff --git a/Master/texmf-dist/doc/support/arara/chapters/cli.tex b/Master/texmf-dist/doc/support/arara/chapters/cli.tex index e4e34b76088..05d1d2f10a7 100644 --- a/Master/texmf-dist/doc/support/arara/chapters/cli.tex +++ b/Master/texmf-dist/doc/support/arara/chapters/cli.tex @@ -66,7 +66,7 @@ When executed in verbose mode, \arara\ will display the underlying system comman ----------------------------------------------------------------- (BibTeX) The BibTeX reference management software ----------------------------------------------------------------- -This is BibTeX, Version 0.99d (TeX Live 2019) +This is BibTeX, Version 0.99d (TeX Live 2020) The top-level auxiliary file: doc5.aux The style file: plain.bst Database file #1: mybib.bib @@ -116,23 +116,31 @@ $ arara | (_| | | | (_| | | | (_| | \__,_|_| \__,_|_| \__,_| -Usage: arara [OPTIONS] [file]... +Usage: arara [OPTIONS] file... Options: - -l, --log Generate a log output - -v, --verbose / -s, --silent Print the command output - -n, --dry-run Go through all the motions of running a - command, but with no actual calls - -H, --header Extract directives only in the file header - -t, --timeout INT Set the execution timeout (in milliseconds) - -L, --language TEXT Set the application language - -m, --max-loops INT Set the maximum number of loops (> 0) - -p, --preamble TEXT Set the file preamble based on the - configuration file - -d, --working-directory DIRECTORY - Set the working directory for all tools - -V, --version Show the version and exit - -h, --help Show this message and exit + -l, --log Generate a log output + -v, --verbose / -s, --silent Print the command output + -n, --dry-run Go through all the motions of running + a command, but with no actual calls + -s, --safe-run Run in safe mode and disable + potentially harmful features. Make + sure your projects uses only allowed + features. + -H, --header Extract directives only in the file + header + -p, --preamble TEXT Set the file preamble based on the + configuration file + -t, --timeout INT Set the execution timeout (in + milliseconds) + -L, --language TEXT Set the application language + -m, --max-loops INT Set the maximum number of loops (> 0) + -d, --working-directory PATH Set the working directory for all + tools + -P, --call-property VALUE Pass parameters to the application + to be used within the session. + -V, --version Show the version and exit + -h, --help Show this message and exit Arguments: file The file(s) to evaluate and process @@ -157,7 +165,7 @@ When running \arara\ without this option, two directives will be extracted (the \item[\describeop{l}{log}] This option enables the logging feature of our tool. All streams from all system commands will be logged and, at the end of the execution, a consolidated log file named \rbox{arara.log} will be generated. This option can also be activated by default in the configuration file (see Section~\ref{sec:basicstructure}, on page~\pageref{sec:basicstructure}). Refer to Chapter~\ref{chap:logging}, on page~\pageref{chap:logging}, for more details on the logging feature. -\item[\describeopp{L}{language}{code}] This option sets the language of the current execution of \arara\ according to the language code identified by the \prbox{code} value provided as the parameter. The language code tries to follow the ISO 639 norm, standardized nomenclature used to classify languages. For example, this is our tool speaking Dutch: +\item[\describeopp{L}{language}{code}] This option sets the language of the current execution of \arara\ according to the language code identified by the \prbox{code} value provided as the parameter. The language code tries to follow the IETF BCP 47 norm, standardized nomenclature used to classify languages. For example, this is our tool speaking Dutch: \begin{codebox}{Terminal}{teal}{\icnote}{white} $ arara -L nl doc5.tex @@ -169,10 +177,10 @@ $ arara -L nl doc5.tex Verwerken van 'doc5.tex' (grootte: 285 B, laatst gewijzigd: 03/01/2020 19:25:40), een ogenblik geduld. -(PDFLaTeX) PDFLaTeX engine .............................. SUCCESVOL -(BibTeX) The BibTeX reference management software ....... SUCCESVOL -(PDFLaTeX) PDFLaTeX engine .............................. SUCCESVOL -(PDFLaTeX) PDFLaTeX engine .............................. SUCCESVOL +(PDFLaTeX) PDFLaTeX engine ............................ SUCCESVOL +(BibTeX) The BibTeX reference management software ..... SUCCESVOL +(PDFLaTeX) PDFLaTeX engine ............................ SUCCESVOL +(PDFLaTeX) PDFLaTeX engine ............................ SUCCESVOL Totaal: 1,07 seconden \end{codebox} @@ -188,10 +196,10 @@ At time of writing, \arara\ is able to speak English, German, Dutch, Italian and \begin{tabular}{lll} \rbox[araracolour]{\hphantom{x}en\hphantom{x}} English & \rbox[araracolour]{\hphantom{x}de\hphantom{x}} German & -\rbox[araracolour]{\hphantom{x}qn\hphantom{x}} Broad Norfolk \\ +\rbox[araracolour]{en-QN} Broad Norfolk \\ \rbox[araracolour]{\hphantom{x}it\hphantom{x}} Italian & \rbox[araracolour]{\hphantom{x}nl\hphantom{x}} Dutch & -\rbox[araracolour]{ptbr} Portuguese (BR) +\rbox[araracolour]{pt-BR} Portuguese (BR) \end{tabular}\par} \vspace{1.4em} @@ -201,6 +209,10 @@ Would you like to make \arara\ speak your own language? Splendid! We would love This option can also be specified in the configuration file (see Section~\ref{sec:basicstructure}, on page~\pageref{sec:basicstructure}). However, one can always override this setting by running the tool with an explicit \opbox{L} option. +\begin{messagebox}{Invalid language codes}{araracolour}{\icinfo}{white} +From version 6.0 on, if you pass an invalid language code, \arara\ will now run in English and issue a log warning but not fail anymore. Failing due to the wrong language in the output was considered inappropriate. +\end{messagebox} + \item[\describeopp{m}{max-loops}{number}] As a means to avoid infinite iterations, \arara\ has a predefined maximum number of loops, with the default set to 10, as a technical solution (seen in Section~\ref{sec:directives}, on page~\pageref{sec:directives}). For instance, consider the following directive: \begin{codebox}{A naughty directive}{teal}{\icnote}{white} @@ -236,30 +248,30 @@ $ arara -n doc5.tex | (_| | | | (_| | | | (_| | \__,_|_| \__,_|_| \__,_| -Processing 'doc5.tex' (size: 285 B, last modified: 03/01/2020 -19:25:40), please wait. +Processing "doc5.tex" (size: 360 B, last modified: 12/28/2020 +13:03:32), please wait. [DR] (PDFLaTeX) PDFLaTeX engine ----------------------------------------------------------------- Author: Island of TeX -About to run: [ pdflatex, /home/paulo/Downloads/doc5.tex ] @ +About to run: [pdflatex, doc5.tex] @ /home/paulo/Downloads [DR] (BibTeX) The BibTeX reference management software ----------------------------------------------------------------- Author: Island of TeX -About to run: [ bibtex, doc5 ] @ +About to run: [bibtex, doc5] @ /home/paulo/Downloads [DR] (PDFLaTeX) PDFLaTeX engine ----------------------------------------------------------------- Author: Island of TeX -About to run: [ pdflatex, /home/paulo/Downloads/doc5.tex ] @ +About to run: [pdflatex, doc5.tex] @ /home/paulo/Downloads [DR] (PDFLaTeX) PDFLaTeX engine ----------------------------------------------------------------- Author: Island of TeX -About to run: [ pdflatex, /home/paulo/Downloads/doc5.tex ] @ +About to run: [pdflatex, doc5.tex] @ /home/paulo/Downloads -Total: 0.23 seconds +Total: 0.18 seconds \end{codebox} Note that the rule authors are displayed (so they can be blamed in case anything goes wrong), as well as the system command to be executed. It is an interesting approach to see everything that will happen to your document and in which order. @@ -343,7 +355,30 @@ If left unattended, this particular execution would never finish (and probably c \item[\describeop{v}{verbose}] This option enables the verbose mode of \arara, as seen in Section~\ref{sec:userinterfacedesign}, on page~\pageref{sec:userinterfacedesign}. It also enables all streams to be flushed directly to the terminal, including potential user input interactions (the exact opposite of silent mode). This option can also be activated by default in the configuration file (see Section~\ref{sec:basicstructure}, on page~\pageref{sec:basicstructure}). \item[\describeop{s}{silent}] This option disables the verbose mode of \arara\ (thus activating the default silent mode), if previously enabled by a proper configuration file (see Chapter~\ref{chap:configurationfile}, on page~\pageref{chap:configurationfile}). It is important to note that this command line option has higher priority over the \opbox{{-}verbose} counterpart. -% It might be worth clarifying here that --silent doesn't completely stop all messages from being written to STDOUT, just the messages normally produced by the system commands called by the subtasks. The normal arara messages are still displayed. + +\item[\describeop{S}{safe-run}] This option enables the safe mode of \arara, protecting the system by disallowing certain user actions. Currently, the following features are restricted: + +\begin{itemize}[label={--}] +\item File lookup will only perform explicit file resolution. Wildcard filters are disabled. + +\item \mtbox{unsafelyExecuteSystemCommand} will raise an exception and abort the run. Keep in mind that rules are still allowed to construct arbitrary commands using \rbox{Command} objects, so this restriction only disallows arbitrary system commands that would not get logged and are thus invisible to the user. + +\item The \rbox{options} parameter does not expand orb tags in any directive. +\end{itemize} + +\item[\describeopp{P}{call-property}{entry}] This option forwards the provided \prbox{entry}, in the \rbox{key=value} format, to the session map. For instance, consider the following call: + +\begin{codebox}{Example}{teal}{\icnote}{white} +$ arara -P foo=bar hello.tex +\end{codebox} + +In a rule, you may now retrieve the value associated to the \rbox{foo} key, which is \rbox{bar}, set at runtime, by calling the following method in your code: + +\begin{codebox}{Example}{teal}{\icnote}{white} +getSession().get('arg:foo') +\end{codebox} + +This option may be called multiple times, as a means to provide as many data pairs as needed. Please refer to \mtbox{getSession} in Chapter~\ref{chap:methods}, on page~\pageref{chap:methods}, for more details. \end{description} You can combine options, use long or short variations interchangeably and write them in any order, provided that a file name is given at some point in the command line, otherwise the usage will be printed. Use the provided features in order to enhance and optimize your automation workflow. diff --git a/Master/texmf-dist/doc/support/arara/chapters/concepts.tex b/Master/texmf-dist/doc/support/arara/chapters/concepts.tex index 87fac0469fc..f4ea941ab60 100644 --- a/Master/texmf-dist/doc/support/arara/chapters/concepts.tex +++ b/Master/texmf-dist/doc/support/arara/chapters/concepts.tex @@ -15,21 +15,23 @@ A \emph{rule} is a formal description of how \arara\ handles a certain task. For | (_| | | | (_| | | | (_| | \__,_|_| \__,_|_| \__,_| -Processing 'doc1.tex' (size: 83 B, last modified: 05/03/2018 -12:10:33), please wait. +Processing "doc1.tex" (size: 31 B, last modified: 12/28/2020 +07:37:37), please wait. -I could not find a rule named 'foo' in the provided rule paths. + ERROR + +I could not find a rule named "foo" in the provided rule paths. Perhaps a misspelled word? I was looking for a file named -'foo.yaml' in the following paths in order of priority: +"foo.yaml" in the following paths in order of priority: (/opt/paulo/arara/rules) -Total: 0.09 seconds +Total: 0.03 seconds \end{codebox} Once a rule is defined, \arara\ automatically provides an access layer to that rule through directives in the source code, a concept to be formally introduced later on, in Section~\ref{sec:directives}. Observe that a directive reflects a particular instance of a rule of the same name (i.e, a \rbox{foo} directive in a certain source code is an instance of the \rbox{foo} rule). \begin{messagebox}{A note about rules}{attentioncolour}{\icattention}{black} -For version 5.0, we kept the current YAML rule scheme. However, the names of the rules being public are marked as deprecated, as they might change in future versions. +From version 6.0 on, rules included in the core distribution have been renamed to have a unique prefix in the texmf tree. File names should not be relied upon. \end{messagebox} In short, a rule is a plain text file written in the YAML format, described in Chapter~\ref{chap:yaml}, on page~\pageref{chap:yaml}. I opted for this format because back then it was cleaner and more intuitive to use than other markup languages such as XML, besides of course being a data serialization standard for programming languages. @@ -38,12 +40,12 @@ In short, a rule is a plain text file written in the YAML format, described in C As a bonus, the acronym \emph{YAML} rhymes with the word \emph{camel}, so \arara\ is heavily environmentally friendly. Speaking of camels, there is the programming reference as well, since this amusing animal is usually associated with Perl and friends. \end{messagebox} -The default rules, i.e, the rules shipped with \arara, are placed inside a special subdirectory named \abox[araracolour]{rules/} inside another special directory named \abox[araracolour]{ARARA\_HOME} (the place where our tool is installed). We will learn later on, in Section~\ref{sec:basicstructure}, on page~\pageref{sec:basicstructure}, that we can add an arbitrary number of paths for storing our own rules, in order of priority, so do not worry too much about the location of the default rules, although it is important to understand and acknowledge their existence. +The default rules, i.e, the rules shipped with \arara, are placed inside a special subdirectory named \abox[araracolour]{rules/} inside another special directory named \abox[araracolour]{ARARA\_HOME} (the place where our tool is installed). We will learn later on, in Section~\ref{sec:basicstructure}, on page~\pageref{sec:basicstructure}, that we can add an arbitrary number of paths for storing our own rules, in order of priority, so do not worry too much about the location of the default rules, although it is important to understand and acknowledge their existence. Observe, however, that rules in the core distribution have a different naming scheme than the ones located in the user space. The following list describes the basic structure of an \arara\ rule by presenting the proper elements (or keys, if we consider the proper YAML nomenclature). Observe that elements marked as \rbox[araracolour]{M} are mandatory (i.e, the rule \emph{has} to have them in order to work). Similarly, elements marked as \rbox[araracolour]{O} are optional, so you can safely ignore them when writing a rule for our tool. A key preceded by \rbox{context$\rightarrow$} indicates a context and should be properly defined inside it. \begin{description} -\item[\describe{M}{!config}] This keyword is mandatory and must be the first line of any \arara\ rule. It denotes the object mapping metadata to be internally used by the tool. Actually, the tool is not too demanding on using it (in fact, you could suppress it entirely and \arara\ will not complain), but it is considered good practice to start all rules with a \abox{!config} keyword regardless. +\item[\describe{M}{!config}] This keyword is mandatory and must be the first line of any \arara\ rule. It denotes the object mapping metadata to be internally used by the tool. The tool requires it, so make sure to start all rules with a \abox{!config} keyword. \item[\describe{M}{identifier}] This key acts as a unique identifier for the rule (as expected). It is highly recommended to use lowercase letters without spaces, accents or punctuation symbols, as good practice (again). As a convention, if you have an identifier named \rbox{pdflatex}, the rule filename must be \rbox{pdflatex.yaml} (like our own instance). Please note that, although \rbox{yml} is known to be a valid YAML extension as well, \arara\ only considers files ending with the \rbox{yaml} extension. This is a deliberate decision. @@ -75,7 +77,7 @@ In order to properly set a subtask, the keys used in this specification are defi \item[\describecontext{M}{commands}{command}] This key holds the action to be performed, typically a system command. The tool offers two types of returned values: \begin{itemize}[label={--}] -\item A \rbox{Command} object: \arara\ features an approach for handling system commands based on a high level structure with explicit argument parsing named \rbox{Command} (for our curious users, it is a plain Java object). In order to use this approach, we need to rely on orb tags and use a helper method named \mtbox{getCommand} to obtain the desired result. We will detail this method later on, in Section~\ref{sec:commands}, on page~\pageref{sec:commands}. We highly recommend the adoption of this approach for rule writing instead of using plain strings. +\item A \rbox{Command} object: \arara\ features an approach for handling system commands based on a high level structure with explicit argument parsing named \rbox{Command}. In order to use this approach, we need to rely on orb tags and use a helper method named \mtbox{getCommand} to obtain the desired result. We will detail this method later on, in Section~\ref{sec:commands}, on page~\pageref{sec:commands}. \begin{codebox}{Example}{teal}{\icnote}{white} command: "@{ return getCommand('ls') }" @@ -99,20 +101,14 @@ As an example, please refer to the official \rbox{clean} rule for a real scenari There are at least one variable available in the \abox{command} context and is described as follows (note that MVEL variables and orb tags are discussed in Chapter~\ref{chap:mvel}). A variable will be denoted by \varbox{variable} in this list. For each rule argument (defined later on), there will be a corresponding variable in the \abox{command} context, directly accessed through its unique identifier. \begin{description} -\item[\varbox{reference}] This variable holds the canonical, absolute path representation of the file name as a \rbox{File} object. This is useful if it's necessary to know the hierarchical structure of a project. Since the reference is a Java object, we can use all methods available in the \rbox{File} class. +\item[\varbox{reference}] This variable holds the canonical, absolute path representation of the file name as a \rbox{File} object. This is useful if it's necessary to know the hierarchical structure of a project. Since the reference is a Java object, we can use methods available in the \rbox{File} class. \end{description} \begin{messagebox}{Quote handling}{araracolour}{\icinfo}{white} \setlength{\parskip}{1em} -The YAML format disallows key values starting with \rbox{@} without proper quoting. This is the reason we had to use double quotes for the value and internally using single quotes for the command string. Also, we could use the other way around, or even using only one type and then escaping them when needed. This is excessively verbose but needed due to the format requirement. Thankfully, \arara\ offers two solutions for removing the quoting verbosity when writing commands. - -The first solution is used in previous versions and it still works like a charm in modern days. We need to precede our command with a special keyword \rbox{<arara>} which will be removed afterwards. This solution works on virtually every key in the rule context, so it is a bonus. The new code will look like this: - -\begin{codebox}{Example}{teal}{\icnote}{white} -command: <arara> @{ return getCommand('ls') } -\end{codebox} +The YAML format disallows key values starting with \rbox{@} without proper quoting. This is the reason we had to use double quotes for the value and internally using single quotes for the command string. Also, we could use the other way around, or even using only one type and then escaping them when needed. This is excessively verbose but needed due to the format requirement. -The second approach is more of a YAML feature rather than a tool exclusive, although we have to do a couple of checks under the hood in order to ensure the correct execution. The idea here is to use the scalar content in folded style, as seen in Section~\ref{sec:yamlscalars}, on page~\pageref{sec:yamlscalars}. The new code will look like this: +From version 6.0 on, the \rbox{<arara>} shorthand is not supported anymore. We encourage the use of a YAML feature named \emph{folded style} when writing such values. The idea here is to use the scalar content in folded style, as seen in Section~\ref{sec:yamlscalars}, on page~\pageref{sec:yamlscalars}. The new code will look like this: \begin{codebox}{Example}{teal}{\icnote}{white} command: > @@ -121,7 +117,7 @@ command: > } \end{codebox} -Mind the indentation, as YAML requires it to properly identify blocks. Please keep in mind that the \rbox{<arara>} keyword is marked as deprecated in version 5.0 and will be removed in future versions of \arara, so it is highly recommended to favour this approach. +Mind the indentation, as YAML requires it to properly identify blocks. If your code still relies on the \rbox{<arara>} shorthand, please update it accordingly to use YAML's folded style instead. \end{messagebox} \item[\describecontext{O}{commands}{exit}] This key holds a special purpose, as it represents a custom exit status evaluation for the corresponding command. In general, a successful execution has zero as an exit status, but sometimes we end up with tools or situations where we need to override this check for whatever reason. For this purpose, simply write a MVEL expression \emph{without orb tags} as plain string and use the special variable \varbox{value} if you need the actual exit status returned by the command, available at runtime. For example, if the command returns a non-zero value indicating a successful execution, we can write this key as: @@ -160,13 +156,40 @@ In order to properly set an argument, the keys used in this specification are de identifier: shell \end{codebox} -It is important to mention that not all names are valid as argument identifiers. \arara\ has restrictions on three names, described as follows, which cannot be used. +It is important to mention that not all names are valid as argument identifiers. \arara\ has restrictions on two names, described as follows, which cannot be used. \begin{messagebox}{Reserved names for rule arguments}{attentioncolour}{\icattention}{black} Our tool has two names reserved for internal use: \abox{files}, and \abox{reference}. Do not use them as argument identifiers! \end{messagebox} -\item[\describecontext{O}{arguments}{flag}] This key holds a plain string and is evaluated when the corresponding argument is defined in the directive context. After being evaluated, the result will be stored in a variable of the same name to be later accessed in the \abox{command} context. In the scenario where the argument is not defined in the directive, the variable will hold an empty string. +\item[\describecontext{O}{arguments}{flag}] This key holds a plain string and is evaluated when the corresponding argument is defined in the directive context. After being evaluated, the result will be stored in a variable of the same name to be later accessed in the \abox{command} context. In the scenario where the argument is not defined in the directive, the variable will hold an empty list. + +\begin{messagebox}{Return type}{araracolour}{\icinfo}{white} +From version 6.0 on, the return value for \abox{flag} is now transformed into a proper \rbox{List<String>} type instead of a plain, generic \rbox{Object} reference, as seen in previous versions. The following rules apply: + +\begin{itemize}[label={--}] +\item If a list is returned, it will be flattened and all values will be turned into strings. + +\rbox[araracolour]{\hspace{1ex}[ 'a', 1, [ 2, 'b' ] ]\hspace{1ex}} $\implies$ \rbox[araracolour]{\hspace{1ex}[ 'a', '1', '2', 'b' ]\hspace{1ex}} + +\item If a string is returned, a single list with only that string will be returned. + +\rbox[araracolour]{\hspace{1ex}'hello world'\hspace{1ex}} $\implies$ \rbox[araracolour]{\hspace{1ex}[ 'hello world' ]\hspace{1ex}} + +\item If another type is returned, it will be turned into string. + +\rbox[araracolour]{\hspace{1ex}3.1415\hspace{1ex}} $\implies$ \rbox[araracolour]{\hspace{1ex}[ '3.1415' ]\hspace{1ex}} +\end{itemize} + +Other return types than string or lists are not encouraged. However, if such types are used, they will be transformed into a list of strings, as previously seen. If you need interoperability of complex \abox{command} code with older versions, use the following trick to get the value of previously non-list values: + +\begin{codebox}{Example}{teal}{\icnote}{white} +isList(variable) ? variable[0] : variable +\end{codebox} + +In this way, one can keep a compatibility layer for older versions. However, it is highly recommended to use the latest version of \arara\ whenever possible. + +\end{messagebox} \begin{codebox}{Example}{teal}{\icnote}{white} flag: > @@ -181,24 +204,51 @@ There are two variables available in the \abox{flag} context, described as follo \begin{description} \item[\varbox{parameters}] This variable holds a map of directive parameters available at runtime. For each argument identifier listed in the \abox{arguments} list in the rule context, there will be an entry in this variable. This is useful to get the actual values provided during execution and take proper actions. If a parameter is not set in the directive context, the reference will still exist in the map, but it will be mapped to an empty string. -\item[\varbox{reference}] This variable holds the canonical, absolute path representation of the file name as a \rbox{File} object. This is useful if it's necessary to know the hierarchical structure of a project. Since the reference is a Java object, we can use all methods available in the \rbox{File} class. +\begin{codebox}{Example}{teal}{\icnote}{white} +check = parameters.contains("foo"); +\end{codebox} + +\item[\varbox{reference}] This variable holds the canonical, absolute path representation of the file name as a \rbox{File} object. This is useful if it is necessary to know the hierarchical structure of a project. Since the reference is a Java object, we can use methods available in the \rbox{File} class. + +\begin{codebox}{Example}{teal}{\icnote}{white} +parent = reference.getParent(); +\end{codebox} \end{description} In the previous example, observe that the MVEL expression defined in the \abox{flag} key checks if the user provided an affirmative value regarding shell escape, through comparing \varbox{parameters.shell} with a set of predefined affirmative values. In any case, the corresponding command flag is defined as result of such evaluation. -\item[\describecontext{O}{arguments}{default}] As default behaviour, if a parameter is not set in the directive context, the reference will be mapped to an empty string. This key exists for the exact purpose of overriding such behaviour. +\item[\describecontext{O}{arguments}{default}] As default behaviour, if a parameter is not set in the directive context, the reference will be mapped to an empty string. This key exists for the exact purpose of overriding such behaviour and always expects a string value, as if it were provided by the user in the directive context. + +\begin{messagebox}{No more evaluation and variables}{araracolour}{\icinfo}{white} +\setlength{\parskip}{1em} +In earlier versions, \arara\ used to evaluate the \abox{default} key and return a plain, generic \rbox{Object} reference, which was then forwarded directly to the corresponding \abox{command} context. The workflow changed for version 6.0 on. + +From now on, \abox{default} always expects a string value, as if it were provided by the user in the directive context. No variables are available and no more evaluation is expected from this key. Consider the following example: \begin{codebox}{Example}{teal}{\icnote}{white} -default: '' +default: "@{ 1 == 1 }" \end{codebox} -There are three variables available in the \abox{default} context, described as follows. Note that are also several helper methods available in the rule context (for instance, \mtbox{isTrue} presented in the previous example) which provide interesting features for rule writing. They are detailed later on, in Chapter~\ref{chap:methods}, on page~\pageref{chap:methods}. +There is an orb tag expression in this string, which should resolve to \rbox{true} in previous versions of \arara. However, from now on, it will not be evaluated at all and the literal string will be assigned to the \abox{default} key. -\begin{description} -\item[\varbox{parameters}] This variable holds a map of directive parameters available at runtime. For each argument identifier listed in the \abox{arguments} list in the rule context, there will be an entry in this variable. This is useful to get the actual values provided during execution and take proper actions. If a parameter is not set in the directive context, the reference will still exist in the map, but it will be mapped to an empty string. +The \abox{default} key, whenever available and in the scenario in which the user does not provide an explicit value for the current argument in the directive context, is forwarded to the \abox{flag} context for proper evaluation. Then the workflow proceeds as usual. +\end{messagebox} -\item[\varbox{reference}] This variable holds the canonical, absolute path representation of the file name as a \rbox{File} object. This is useful if it's necessary to know the hierarchical structure of a project. Since the reference is a Java object, we can use all methods available in the \rbox{File} class. -\end{description} +\begin{messagebox}{Return type}{araracolour}{\icinfo}{white} +\setlength{\parskip}{1em} +The \abox{default} key, whenever available, returns a string to be evaluated in the corresponding \abox{flag} context. However, if the target evaluation context does not exist (i.e, there is no corresponding \abox{flag} key), the value is transformed into a list of strings and then forwarded directly to the \abox{command} context. For instance: + +\begin{codebox}{Example}{teal}{\icnote}{white} +- identifier: foo + default: 'bar' +\end{codebox} + +This scenario will directly forward \rbox[araracolour]{\hspace{1ex}[ 'bar' ] \hspace{1ex}} (a list of strings containing the specified value as single element) as the value for the \varbox{foo} variable in the corresponding \abox{command} context. +\end{messagebox} + +\begin{codebox}{Example}{teal}{\icnote}{white} +default: 'stable' +\end{codebox} \item[\describecontext{O}{arguments}{required}] There might be certain scenarios in which a rule could make use of required arguments (for instance, a copy operation in which source and target must be provided). The \abox{required} key acts as a boolean switch to indicate whether the corresponding argument should be mandatory. In this case, set the key value to \rbox{true} and the argument becomes required. Later on at runtime, \arara\ will throw an error if a required parameter is missing in the directive. @@ -225,7 +275,7 @@ arguments: '--no-shell-escape') } required: false - default: '' + default: 'false' \end{codebox} \end{description} @@ -239,7 +289,7 @@ A \emph{directive} is a special comment inserted in the source file in which you There are two types of directives in \arara\ which determine the way the corresponding rules will be instantiated. They are listed as follows. Note that directives are always preceded by the \rbox{arara:} pattern. \begin{description} -\item[empty directive] This type of directive has already been mentioned in Chapter~\ref{chap:introduction}, on page~\pageref{chap:introduction}, it has only the rule name (which refers to the \abox{identifier} key from the rule of the same name). All rule arguments are mapped to empty strings, except the ones with \abox{default} values. +\item[empty directive] This type of directive has already been mentioned in Chapter~\ref{chap:introduction}, on page~\pageref{chap:introduction}, it has only the rule name (which refers to the \abox{identifier} key from the rule of the same name). All rule arguments are mapped to empty lists, except the ones with \abox{default} values, mapped to lists containing single elements. \begin{codebox}{Empty directive}{teal}{\icnote}{white} % arara: pdflatex @@ -268,13 +318,13 @@ When handling parametrized directives, \arara\ always checks if directive parame | (_| | | | (_| | | | (_| | \__,_|_| \__,_|_| \__,_| -Processing 'hello.tex' (size: 103 B, last modified: -05/03/2018 15:40:16), please wait. +Processing "hello.tex" (size: 102 B, last modified: 12/28/2020 +10:28:00), please wait. -I have spotted an error in rule 'pdflatex' located at -'/opt/paulo/arara/rules'. I found these unknown keys -in the directive: (foo). This should be an easy fix, -just remove them from your map. + ERROR + +I found these unknown keys in the directive: (foo). This should +be an easy fix, just remove them from your map. Total: 0.21 seconds \end{codebox} @@ -331,7 +381,7 @@ Several methods are available in the directive context in order to ease the writ Although there are no conceptual guarantees for proper halting of unbounded loops, we have provided a technical solution for potentially infinite iterations: \arara\ has a predefined maximum number of loops. The default value is set to 10, but it can be overridden either in the configuration file or with a command line flag. We discuss this feature later on, in Sections~\ref{sec:options} and~\ref{sec:basicstructure}, on pages~\pageref{sec:options} and~\pageref{sec:basicstructure}, respectively. \end{messagebox} -All directives, regardless of their type, are internally mapped with the \abox{reference} parameter, discussed earlier on, in Section~\ref{sec:coreconcepts}, on page~\pageref{sec:coreconcepts}, as a special variable in the rule context. When inspecting the log file, you will find all map keys and values for each extracted directive (actually, there is an entire log section devoted to detailing directives found in the code). This feature is covered in Section~\ref{sec:directivenormalization}, on page~\pageref{sec:directivenormalization}. See, for instance, the report of the directive extraction and normalization process performed by \arara\ when inspecting \rbox{doc2.tex}, available in the log file. Note that timestamps were deliberately removed in order to declutter the output, and line breaks were included in order to easily spot the log entries. +All directives, regardless of their type, are internally mapped alongside with the \abox{reference} parameter, discussed earlier on, in Section~\ref{sec:coreconcepts}, on page~\pageref{sec:coreconcepts}, as a special variable in the rule context. When inspecting the log file, you will find all map keys and values for each extracted directive (actually, there is an entire log section devoted to detailing directives found in the code). This feature is covered in Section~\ref{sec:directivenormalization}, on page~\pageref{sec:directivenormalization}. See, for instance, the report of the directive extraction and normalization process performed by \arara\ when inspecting \rbox{doc2.tex}, available in the log file. Note that timestamps were deliberately removed in order to declutter the output, and line breaks were included in order to easily spot the log entries. \begin{ncodebox}{Source file}{teal}{\icnote}{white}{doc2.tex} % arara: pdflatex @@ -375,106 +425,111 @@ It is important to observe that, in this case, \rbox{doc3.tex} is a plain \TeX\ Even when a directive is interpreted with a file other than the one being processed by \arara\ (through the magic of the \abox{files} parameter), it is possible to use helper methods in the rule context to get access to the original file and reference. Such methods are detailed later on, in Section~\ref{sec:files}, on page~\pageref{sec:files}. -\section{Important changes in the 5.x series} +\begin{messagebox}{Orb tag expansion in parameter values}{araracolour}{\icinfo}{white} +From version 6.0 on, \arara\ is able to expand orb tags within a special \rbox{options} parameter in the directive context. For instance: + +\begin{codebox}{Example}{teal}{\icnote}{white} +% arara: lualatex: { +% arara: --> options: [ '--output-directory=@{getSession(). +% arara: --> get("arg:builddir")}' +% arara: --> ] +% arara: --> } +\end{codebox} + +This feature supports the following methods with their documented meanings, as seen in Chapter~\ref{chap:methods}, on page~\pageref{chap:methods}: + +\vspace{2ex} + +\begin{tabularx}{0.95\textwidth}{YYY} +\mtbox{getBasename} & \mtbox{getSession} & \mtbox{getOriginalReference} +\end{tabularx} + +\vspace{2ex} + +Keep in mind that this feature is disabled when \arara\ is running in safe mode, as seen in Chapter~\ref{chap:commandline}, on page~\pageref{chap:commandline}. +\end{messagebox} + +\section{Important changes in version 6} \label{sec:migrationguide} \begin{messagebox}{A note to users}{araracolour}{\icattention}{white} If this is your first time using \arara\ or you do not have custom rules in the old format, you can safely ignore this section. All rules shipped with our tool are already written in the new format. \end{messagebox} -\begin{messagebox}{Removal of the file string reference}{araracolour}{\icattention}{white} -\arara\ previously had the file name string reference as the \abox{file} variable in the rule context. As of version 5.0, support for this variable has been dropped. Users should favour the \abox{reference} variable instead, since it holds the absolute, canonical representation of the file name as a proper \rbox{File} object. +\begin{messagebox}{{API, CLI} and library}{araracolour}{\icinfo}{white} +From version 6.0 on, \arara\ is now split into an API, a core implementation (library) and the implementation of the executable (command line interface). Projects relying on code in the \rbox{arara} JAR distributions have to be updated. \end{messagebox} -\begin{messagebox}{Removal of triggers}{araracolour}{\icattention}{white} -\arara\ previously had the concept of triggers which allowed to easily trigger events like halting \arara. As of version 5.0, support for triggers has been dropped due to the lack of use cases. +\begin{messagebox}{Localization updates}{araracolour}{\icinfo}{white} +The localization framework was redesigned in version 6.0: -As the only pre-defined trigger has been \rbox{halt} we did not deprecate the ability to halt the application. However, the new mechanism uses the concept of session values (see \autoref{sec:others}). -\end{messagebox} +\begin{itemize}[label={--}] +\item Localization is now provided by classes as a library instead of property files in the tool resources. -\begin{messagebox}{Removal of Velocity support}{araracolour}{\icinfo}{white} -\arara\ featured support for the Velocity Template Language. In version 5.0, this support has been removed. We decided in favour of this breaking change to achieve more independence from third-party modules and to avoid being stuck at version~1.7 for compatibility reasons. +\item From version 6.0 on, languages have to be passed as IETF BCP 47 codes. The old system has been removed. Hence, please use \rbox{en-QN} instead of \rbox{qn}, and so forth. -Due to this change, \arara\ does not ship support for any templating language at the moment. If you are interested in getting a templating language on board, you are welcome to support our efforts to make the inclusion of JVM code on the user-side more pleasant. +\item If you pass an invalid language code, \arara\ will now run in English and issue a log warning but not fail anymore. Failing due to the wrong language in the output was considered inappropriate. +\end{itemize} \end{messagebox} -\begin{messagebox}{Removal of string-based commands}{araracolour}{\icinfo}{white} -Up to version 5.0 you could simply use +\begin{messagebox}{Method signature changes}{araracolour}{\icinfo}{white} +The following method signatures have been altered: -\begin{codebox}{Return statement}{teal}{\icnote}{white} -return "command"; -\end{codebox} +\begin{itemize} +\item[\textcolor{warningcolour}{\faClose}]\mddbox{C}{R}{loadObject(File file, String name)}{Pair<Integer, Object>} -\noindent in your rules. This resulted in \arara\ implicitly constructing a command object. As this does not make clear that this command is actually run, we now enforce the usage of +\vspace{.5em} -\vspace{1em} +\hspace{2cm}\textcolor{teal}{\faArrowDown} -\mdbox{R}{getCommand(List<String> commands)}{Command} +\item[\textcolor{okcolour}{\faCheck}]\mddbox{C}{R}{\parbox{0.32\textwidth}{loadObject(File file,\\ \hspace*{1em}String name)}}{\parbox{0.43\textwidth}{Pair<ClassLoading.\\ +\hspace*{1em}ClassLoadingStatus, Object>}} \vspace{1em} -\noindent in the \rbox{return} statement. Hence, the new way of doing the same is (with either single or double quote pairs): +{\color{araracolour}\hrule} -\begin{codebox}{Return statement}{teal}{\icnote}{white} -return getCommand("command"); -\end{codebox} -\end{messagebox} - -\begin{messagebox}{Methods: removal and change of name}{araracolour}{\icinfo}{white} -The following previously available methods (and repective overloaded variants) have been removed: - -\begin{itemize} -\item[\textcolor{warningcolour}{\faClose}] \mdbox{R}{addQuotes(String string)}{String} -\item[\textcolor{warningcolour}{\faClose}] \mdbox{R}{isAIX()}{boolean} -\item[\textcolor{warningcolour}{\faClose}] \mdbox{R}{isIrix()}{boolean} -\item[\textcolor{warningcolour}{\faClose}] \mdbox{R}{isOS2()}{boolean} -\item[\textcolor{warningcolour}{\faClose}] \mdbox{R}{isSolaris()}{boolean} -\item[\textcolor{warningcolour}{\faClose}] \mdbox{R}{getFullBasename(File file)}{String} -\item[\textcolor{warningcolour}{\faClose}] \mdbox{R}{\parbox{0.62\textwidth}{mergeVelocityTemplate(File input,\\\hspace*{1em} File output, Map<String, Object> map)}}{void} -\end{itemize} - -The following methods have been renamed: -\begin{itemize} -\item[\textcolor{warningcolour}{\faClose}] \mdbox{R}{(Session.)insert(String key, Object value)}{void} +\item[\textcolor{warningcolour}{\faClose}]\mddbox{C}{R}{loadObject(String ref, String n)}{Pair<Integer, Object>} \vspace{.5em} \hspace{2cm}\textcolor{teal}{\faArrowDown} -\item[\textcolor{okcolour}{\faCheck}]\mdbox{R}{(Session.)put(String key, Object value)}{void} +\item[\textcolor{okcolour}{\faCheck}]\mddbox{C}{R}{\parbox{0.32\textwidth}{loadObject(String ref,\\ \hspace*{1em}String n)}}{\parbox{0.43\textwidth}{Pair<ClassLoading.\\ +\hspace*{1em}ClassLoadingStatus, Object>}} \vspace{1em} -\item[\textcolor{warningcolour}{\faClose}] \mdbox{R}{(Session.)exists(String key)}{boolean} +{\color{araracolour}\hrule} + +\item[\textcolor{warningcolour}{\faClose}]\mddbox{C}{R}{loadClass(File file, String name)}{Pair<Integer, Object>} \vspace{.5em} \hspace{2cm}\textcolor{teal}{\faArrowDown} -\item[\textcolor{okcolour}{\faCheck}] \mdbox{R}{(Session.)contains(String key)}{boolean} +\item[\textcolor{okcolour}{\faCheck}]\mddbox{C}{R}{\parbox{0.32\textwidth}{loadClass(File file,\\ \hspace*{1em}String name)}}{\parbox{0.43\textwidth}{Pair<ClassLoading.\\ +\hspace*{1em}ClassLoadingStatus, Object>}} \vspace{1em} -\item[\textcolor{warningcolour}{\faClose}] \mdbox{R}{(Session.)obtain(String key)}{Object} +{\color{araracolour}\hrule} + +\item[\textcolor{warningcolour}{\faClose}]\mddbox{C}{R}{loadClass(String ref, String n)}{Pair<Integer, Object>} \vspace{.5em} \hspace{2cm}\textcolor{teal}{\faArrowDown} -\item[\textcolor{okcolour}{\faCheck}]\mdbox{R}{(Session.)get(String key)}{Object} +\item[\textcolor{okcolour}{\faCheck}]\mddbox{C}{R}{\parbox{0.32\textwidth}{loadClass(String ref,\\ \hspace*{1em}String n)}}{\parbox{0.43\textwidth}{Pair<ClassLoading.\\ +\hspace*{1em}ClassLoadingStatus, Object>}} \end{itemize} -\end{messagebox} - -\begin{messagebox}{Support for multiple files}{araracolour}{\icinfo}{white} -From version 5.0 on, \arara\ is able to compile multiple files at once by providing multiple files as arguments. Please note that they should reside in the same working directory. Every other kind of compilation of multiple files is restricted by the mechanisms of the running programs. See \autoref{chap:commandline} for details. -\end{messagebox} -\begin{messagebox}{Support for changing the working directory}{araracolour}{\icinfo}{white} -A common problem when compiling \TeX\ files are specialties of \TeX\ engines looking for files. Usually, you should call an engine from the directory where the target file is located. \arara\ had the same restriction in that case. Now you can instruct \arara\ to operate from another directory lifting that constraint. See \autoref{chap:commandline} for details. +You can now access the status values as enumeration. \end{messagebox} -\begin{messagebox}{Relative paths for \TeX\ engines and tools}{araracolour}{\icinfo}{white} -It is worth mentioning that, although \arara\ provides the absolute, canonical path of the provided files in the rule context through the \abox{reference} variable, \TeX-related tools rely on the file name as a relative path with \mtbox{reference.getName()}. This decision was made due to path constraints in these tools, as well as to ensure auxiliary files are written in their correct locations. If you need to run \arara\ on a file located in another directory, refer to \autoref{chap:commandline}, as there is an specific command line option for that purpose. +\begin{messagebox}{Null handling}{araracolour}{\icinfo}{white} +The implementation of methods available within rules has been moved to Kotlin causing \rbox{null} values to be handled differently. Previously undefined behavior will now cause an error. \end{messagebox} -This section pretty much covered the basics of the changes to this version. Of course, it is highly advisable to make use of the new features available in \arara\ 5.0 for achieving better results. If you need any help, please do not hesitate to contact us. See Section~\ref{sec:support}, on page~\pageref{sec:support}, for more details on how to get help. +This section pretty much covered the basics of the changes to this version. Of course, it is highly advisable to make use of the new features available in \arara\ 6.0 for achieving better results. If you need any help, please do not hesitate to contact us. See Section~\ref{sec:support}, on page~\pageref{sec:support}, for more details on how to get help. diff --git a/Master/texmf-dist/doc/support/arara/chapters/configuration.tex b/Master/texmf-dist/doc/support/arara/chapters/configuration.tex index e7aba4102b7..b321c176ae5 100644 --- a/Master/texmf-dist/doc/support/arara/chapters/configuration.tex +++ b/Master/texmf-dist/doc/support/arara/chapters/configuration.tex @@ -81,7 +81,7 @@ paths: \end{codebox} \end{description} -Observe that the \varbox{user} variable actually holds a map containing two keys (resulting in a map within a map). However, for didactic purposes, it is easier to use the property navigation feature of MVEL, detailed in Section~\ref{sec:propertynavigation}, on page~\pageref{sec:propertynavigation}, and consider the map references as three independent variables. You can use property navigation styles interchangeably. Note that you can also precede the path with the special keyword \rbox{<arara>} and save some quotes (see Section~\ref{sec:rule}, on page~\pageref{sec:rule}, but keep in mind that this special keyword is marked as deprecated and will be removed in future versions). In this specific scenario, the special keyword will be automatically removed afterwards. +Observe that the \varbox{user} and \varbox{application} variables actually holds maps. However, for didactic purposes, it is easier to use the property navigation feature of MVEL, detailed in Section~\ref{sec:propertynavigation}, on page~\pageref{sec:propertynavigation}, and consider the map references as three independent variables. You can use property navigation styles interchangeably. \begin{messagebox}{Avoid folded and literal styles for scalars in a path}{attentioncolour}{\icattention}{black} Do not use folded or literal styles for scalars in a path! The orb tag resolution for a path in plain string should be kept as simple as possible, so \emph{always} use the inline style. @@ -119,6 +119,10 @@ header: false \item[\describecf{O}{string}{logname}{arara}] This key modifies the default log file name, according to the associated plain string value, plus the \rbox{log} extension. The value cannot be empty or contain invalid characters. There is no orb tag evaluation in this specific context, only a plain string value. The log file will be written by our tool if, and only if, the \opbox{{-}log} command line option is used. +\begin{messagebox}{Log paths}{araracolour}{\icok}{white} +From version 6.0 on, the log file may now be specified as path \emph{anywhere} on the file system. However, keep in mind that this behavior may be altered for future updates in safe mode. +\end{messagebox} + \begin{codebox}{Example}{teal}{\icnote}{white} logname: mylog \end{codebox} @@ -165,6 +169,18 @@ preambles: When defining preambles in the configuration file, \emph{always} use the literal style for scalar blocks. The reason for this requirement is the proper retention of line breaks, which are significant when parsing the strings into proper directive lines. Using the folded style in this particular scenario will almost surely be problematic. \end{messagebox} +\item[\describecfn{O}{string}{defaultPreamble}] This key allows to specify a preamble for \arara\ to use even if there are no directives in the file nor preambles specified on the command-line. Preambles are resolved at execution time, which means that preambles from local configurations will take precedence over global preambles. + +\begin{codebox}{Example}{teal}{\icnote}{white} +defaultPreamble: twopdftex +\end{codebox} + +\item[\describecfn{O}{boolean}{prependPreambleIfDirectivesGiven}] This key allows you to specify a boolean value indicating whether preambles should be applied to all files or only those without directives. It defaults to \rbox{true} to avoid breaking existing workflows. + +\begin{codebox}{Example}{teal}{\icnote}{white} +prependPreambleIfDirectivesGiven: false +\end{codebox} + \item[\describecfn{O}{file type list}{filetypes}] This key holds a list of file types supported by \arara\ when searching for a file name, as well as their corresponding directive lookup patterns. In order to properly set a file type, the keys used in this specification are defined inside the \rbox{filetypes$\rightarrow$} context and presented as follows. \begin{description} diff --git a/Master/texmf-dist/doc/support/arara/chapters/deploying.tex b/Master/texmf-dist/doc/support/arara/chapters/deploying.tex index 25932f9f9d2..6af9d316d5f 100644 --- a/Master/texmf-dist/doc/support/arara/chapters/deploying.tex +++ b/Master/texmf-dist/doc/support/arara/chapters/deploying.tex @@ -21,29 +21,31 @@ forked edges, [{\abox[araracolour]{ARARA\_HOME}} [{\rbox[araracolour]{arara.jar}}] [{\abox[araracolour]{rules/}},s sep=1mm - [{\rbox[araracolour]{animate.yaml}}] - [{\rbox[araracolour]{bib2gls.yaml}}] + [{\rbox[araracolour]{arara-rule-animate.yaml}}] + [{\rbox[araracolour]{arara-rule-bib2gls.yaml}}] [{\color{araracolour}\ldots},no edge] - [{\rbox[araracolour]{xetex.yaml}}] - [{\rbox[araracolour]{xindy.yaml}}] + [{\rbox[araracolour]{arara-rule-xetex.yaml}}] + [{\rbox[araracolour]{arara-rule-xindy.yaml}}] ] ] \end{forest}\par} \vspace{1.4em} -Provided that this specific directory structure is honoured, the tool is ready for use off the shelf. In fact, the official \arara\ package available in the \href{https://gitlab.com/islandoftex/arara/-/releases}{release section} of our project repository. Once the package is properly downloaded, we simply need to extract it into a proper \abox[araracolour]{ARARA\_HOME} location. +Provided that this specific directory structure is honoured, the tool is ready for use off the shelf. In fact, the official \arara\ CTAN package is available in the \href{https://gitlab.com/islandoftex/arara/-/jobs/artifacts/master/download?job=publish:tdszip}{artifacts section} of our project repository. Once the package is properly downloaded, we simply need to extract it into a proper \abox[araracolour]{ARARA\_HOME} location. \section{Defining a location} \label{sec:definingalocation} -First and foremost, we need to obtain \rbox{arara-5.0.zip} from either our project repository at GitLab. As the name indicates, this is a compressed file format, so we need to extract it into a proper location. Run the following command in the terminal: +First and foremost, we need to obtain \rbox{master-ctan.zip} from our project repository at GitLab, which is our CTAN package artifact. As the name indicates, this is a compressed file format, so we need to extract it into a proper location. Run the following commands in the terminal: \begin{codebox}{Terminal}{teal}{\icnote}{white} -$ unzip arara-5.0.zip +$ unzip master-ctan.zip +$ unzip arara.tds.zip +$ mv scripts/arara . \end{codebox} -As a result of the previous command, we obtained a directory named \abox[araracolour]{arara} with the exact structure presented in Section~\ref{sec:directorystructure} in our working directory. Now we need to decide where \arara\ should reside in our system. For example, I usually deploy my tools inside the \abox[araracolour]{/opt/paulo} path, so I need to run the following command in the terminal (please note that my personal directory already has the proper permissions, so I do not need superuser privileges): +As a result of the previous commands, we obtained a directory named \abox[araracolour]{arara} with the exact structure presented in Section~\ref{sec:directorystructure} in our working directory (amongst other files and directories that can be safely discarded). Now we need to decide where \arara\ should reside in our system. For example, I usually deploy my tools inside the \abox[araracolour]{/opt/paulo} path, so I need to run the following command in the terminal (please note that my personal directory already has the proper permissions, so I do not need superuser privileges): \begin{codebox}{Terminal}{teal}{\icnote}{white} $ mv arara /opt/paulo/ @@ -69,11 +71,11 @@ forked edges, [{\abox[araracolour]{arara/}} [{\rbox[araracolour]{arara.jar}}] [{\abox[araracolour]{rules/}},s sep=1mm - [{\rbox[araracolour]{animate.yaml}}] - [{\rbox[araracolour]{bib2gls.yaml}}] + [{\rbox[araracolour]{arara-rule-animate.yaml}}] + [{\rbox[araracolour]{arara-rule-bib2gls.yaml}}] [{\color{araracolour}\ldots},no edge] - [{\rbox[araracolour]{xetex.yaml}}] - [{\rbox[araracolour]{xindy.yaml}}] + [{\rbox[araracolour]{arara-rule-xetex.yaml}}] + [{\rbox[araracolour]{arara-rule-xindy.yaml}}] ] ] ] @@ -97,23 +99,31 @@ $ java -jar /opt/paulo/arara/arara.jar | (_| | | | (_| | | | (_| | \__,_|_| \__,_|_| \__,_| -Usage: arara [OPTIONS] [file]... +Usage: arara [OPTIONS] file... Options: - -l, --log Generate a log output - -v, --verbose / -s, --silent Print the command output - -n, --dry-run Go through all the motions of running a - command, but with no actual calls - -H, --header Extract directives only in the file header - -t, --timeout INT Set the execution timeout (in milliseconds) - -L, --language TEXT Set the application language - -m, --max-loops INT Set the maximum number of loops (> 0) - -p, --preamble TEXT Set the file preamble based on the - configuration file - -d, --working-directory DIRECTORY - Set the working directory for all tools - -V, --version Show the version and exit - -h, --help Show this message and exit + -l, --log Generate a log output + -v, --verbose / -s, --silent Print the command output + -n, --dry-run Go through all the motions of running + a command, but with no actual calls + -s, --safe-run Run in safe mode and disable + potentially harmful features. Make + sure your projects uses only allowed + features. + -H, --header Extract directives only in the file + header + -p, --preamble TEXT Set the file preamble based on the + configuration file + -t, --timeout INT Set the execution timeout (in + milliseconds) + -L, --language TEXT Set the application language + -m, --max-loops INT Set the maximum number of loops (> 0) + -d, --working-directory PATH Set the working directory for all + tools + -P, --call-property VALUE Pass parameters to the application + to be used within the session. + -V, --version Show the version and exit + -h, --help Show this message and exit Arguments: file The file(s) to evaluate and process @@ -187,23 +197,31 @@ $ arara | (_| | | | (_| | | | (_| | \__,_|_| \__,_|_| \__,_| -Usage: arara [OPTIONS] [file]... +Usage: arara [OPTIONS] file... Options: - -l, --log Generate a log output - -v, --verbose / -s, --silent Print the command output - -n, --dry-run Go through all the motions of running a - command, but with no actual calls - -H, --header Extract directives only in the file header - -t, --timeout INT Set the execution timeout (in milliseconds) - -L, --language TEXT Set the application language - -m, --max-loops INT Set the maximum number of loops (> 0) - -p, --preamble TEXT Set the file preamble based on the - configuration file - -d, --working-directory DIRECTORY - Set the working directory for all tools - -V, --version Show the version and exit - -h, --help Show this message and exit + -l, --log Generate a log output + -v, --verbose / -s, --silent Print the command output + -n, --dry-run Go through all the motions of running + a command, but with no actual calls + -s, --safe-run Run in safe mode and disable + potentially harmful features. Make + sure your projects uses only allowed + features. + -H, --header Extract directives only in the file + header + -p, --preamble TEXT Set the file preamble based on the + configuration file + -t, --timeout INT Set the execution timeout (in + milliseconds) + -L, --language TEXT Set the application language + -m, --max-loops INT Set the maximum number of loops (> 0) + -d, --working-directory PATH Set the working directory for all + tools + -P, --call-property VALUE Pass parameters to the application + to be used within the session. + -V, --version Show the version and exit + -h, --help Show this message and exit Arguments: file The file(s) to evaluate and process diff --git a/Master/texmf-dist/doc/support/arara/chapters/introduction.tex b/Master/texmf-dist/doc/support/arara/chapters/introduction.tex index 77e43685a8c..6a326618485 100644 --- a/Master/texmf-dist/doc/support/arara/chapters/introduction.tex +++ b/Master/texmf-dist/doc/support/arara/chapters/introduction.tex @@ -33,13 +33,15 @@ $ arara hello.tex | (_| | | | (_| | | | (_| | \__,_|_| \__,_|_| \__,_| -Processing 'hello.tex' (size: 86 B, last modified: 05/03/2018 -07:28:30), please wait. +Processing "hello.tex" (size: 70 B, last modified: 12/28/2020 +07:03:16), please wait. + + ERROR It looks like no directives were found in the provided file. Make sure to include at least one directive and try again. -Total: 0.00 seconds +Total: 0.04 seconds \end{codebox} Quite surprising. However, this behaviour is not wrong at all, it is completely by design: \arara\ needs to know what you want. And for that purpose, you need to tell the tool what to do. @@ -68,12 +70,12 @@ $ arara hello.tex | (_| | | | (_| | | | (_| | \__,_|_| \__,_|_| \__,_| -Processing 'hello.tex' (size: 86 B, last modified: 05/03/2018 -07:28:30), please wait. +Processing "hello.tex" (size: 88 B, last modified: 12/28/2020 +07:05:05), please wait. (PDFLaTeX) PDFLaTeX engine .............................. SUCCESS -Total: 0.73 seconds +Total: 0.56 seconds \end{codebox} Hurrah, we finally got our document properly compiled with a \TeX\ engine by the inner workings of our beloved tool, resulting in an expected \rbox{hello.pdf} file created using the very same system call that typical automation tools like \rbox{latexmk} and \rbox{rubber} use. Observe that \arara\ works practically on other side of the spectrum: you need to tell it how and when to do a task. @@ -130,17 +132,17 @@ That is pretty much how \arara\ works: directives in the source code are mapped \section{Operating system remarks} \label{sec:operatingsystemremarks} -The application is written using the Kotlin language (and some pieces of Java), so \arara\ runs on top of a Java virtual machine, available on all the major operating systems~--~in some cases, you might need to install the proper virtual machine. We tried very hard to keep both code and libraries compatible with older virtual machines or from other vendors. Currently, \arara\ is known to run on Oracle's Java 8 to 13, OpenJDK 8 to 13 and ZuluFX 8 and 11. +The application is written using the Kotlin language, so \arara\ runs on top of a Java virtual machine, available on all the major operating systems~--~in some cases, you might need to install the proper virtual machine. We tried very hard to keep both code and libraries compatible with older virtual machines or from other vendors. Currently, \arara\ is known to run on Java 8 to 15, from any vendor. \begin{messagebox}{Outdated Java virtual machines}{attentioncolour}{\icerror}{black} Dear reader, beware of outdated software, mainly Java virtual machines! Although \arara\ offers support for older virtual machines, try your best to keep your software updated as frequently as possible. The legacy support exists only for historical reasons, and also due to the sheer fact that we know some people that still runs \arara\ on very old hardware. If you are not in this particular scenario, get the latest virtual machine. \end{messagebox} -In Chapter~\ref{chap:buildingfromsource}, on page~\pageref{chap:buildingfromsource}, we provide instructions on how to build \arara\ from sources using Apache Maven. Even if you use multiple operating systems, \arara\ should behave the same, including the rules. There are helper functions available in order to provide support for system-specific rules based on the underlying operating system. +In Chapter~\ref{chap:buildingfromsource}, on page~\pageref{chap:buildingfromsource}, we provide instructions on how to build \arara\ from sources using Gradle. Even if you use multiple operating systems, \arara\ should behave the same, including the rules. There are helper functions available in order to provide support for system-specific rules based on the underlying operating system. \section{Support} \label{sec:support} -If you run into any issue with \arara, please let us know. We all have very active profiles in the \href{https://tex.stackexchange.com/}{\TeX\ community at StackExchange}, so just use the \rbox[araracolour]{arara} tag in your question and we will help you the best we can (also, take a look at their \href{https://tex.meta.stackexchange.com/q/1436}{starter guide}). We also have a \href{https://gitter.im/cereda/arara}{Gitter chat room}, in which we occasionally hang out. Also, if you think the report is worthy of an issue, open one in our \href{https://gitlab.com/islandoftex/arara/issues}{GitLab repository}. +If you run into any issue with \arara, please let us know. We all have very active profiles in the \href{https://tex.stackexchange.com/}{\TeX\ community at StackExchange}, so just use the \rbox[araracolour]{arara} tag in your question and we will help you the best we can (also, take a look at their \href{https://tex.meta.stackexchange.com/q/1436}{starter guide}). We also have a \href{https://gitter.im/Island-of-TeX/arara}{Gitter} and \href{https://matrix.to/#/!HfEWIEvFtDplCLSQvz:matrix.org?via=matrix.org}{Matrix} chat rooms, in which we occasionally hang out. Also, if you think the report is worthy of an issue, open one in our \href{https://gitlab.com/islandoftex/arara/issues}{GitLab repository}. We really hope you like our humble contribution to the \TeX\ community. Let \arara\ enhance your \TeX\ experience, it will help you when you will need it the most. Enjoy the manual. diff --git a/Master/texmf-dist/doc/support/arara/chapters/logging.tex b/Master/texmf-dist/doc/support/arara/chapters/logging.tex index 80a4c45a4fd..dd248e0fa5e 100644 --- a/Master/texmf-dist/doc/support/arara/chapters/logging.tex +++ b/Master/texmf-dist/doc/support/arara/chapters/logging.tex @@ -19,11 +19,9 @@ When running our tool on the previous example with the \opbox{{-}log} command li The very first entry to appear in the log file is the current version of \arara. \begin{codebox}{Log file}{teal}{\icnote}{white} -Welcome to arara 5.0.0! +Welcome to arara 6.0.0! \end{codebox} -% TODO: review what will be output in the future - The following entries in the log file are the absolute path of the current deployment of \arara\ (line 1), details about the current Java virtual machine (namely, vendor and absolute path, in lines 2 and 3, respectively), the underlying operating system information (namely, system name, architecture and eventually the kernel version, in line 4), home and working directories (lines 5 and 6, respectively), and the absolute path of the applied configuration file, if any (line 7). This block is very important to help with tracking possible issues related to the underlying operating system and the tool configuration itself. \begin{codebox}{Log file}{teal}{\icnote}{white} @@ -42,7 +40,11 @@ We understand that the previous entries containing information about the underly From experience, these entries greatly help our users to track down errors in the execution, as well as learning more about the underlying operating system. However, be mindful of sharing your log file! Since the log file contains structured blocks, it is highly advisable to selectively choose the ones relevant to the current discussion. \end{messagebox} -It is important to observe that localized messages are also applied to the log file. If a language other than English is selected, either through the \opbox{{-}language} command line option or the equivalent key in the configuration file, the logging framework will honour the current setting and entries will be available in the specified language. Having a log file in your own language might mitigate the traumatic experience of error tracking for \TeX\ newbies. +It is important to observe that localized messages are also applied to the log file. If a language other than English is selected, either through the \opbox{{-}language} command line option or the equivalent key in the configuration file, the logging framework will honour the current setting and entries will be available in the specified language. Having a log file in your own language might mitigate the traumatic experience of error tracking for \TeX\ newbies. From version 6.0 on, if you pass an invalid language code (for instance, \rbox{-L foo} in the command line), \arara\ will default to English and issue a log warning: + +\begin{codebox}{Log file}{teal}{\icnote}{white} +Language foo not available; defaulting to English. +\end{codebox} \section{Directive extraction} \label{sec:directiveextraction} @@ -161,3 +163,7 @@ Total: 0.33 seconds \end{codebox} The logging feature provides a consistent framework for event recording. It is highly recommended to include at least the \opbox{{-}log} command line option (or enable it in the configuration file) in your typical automation workflow, as relevant information is gathered into a single consolidated report. + +\begin{messagebox}{Log paths}{araracolour}{\icok}{white} +From version 6.0 on, the log file may now be specified as path \emph{anywhere} on the file system. However, keep in mind that this behavior may be altered for future updates in safe mode. Please refer to Chapter~\ref{chap:configurationfile}, on page~\pageref{chap:configurationfile}, for more details. +\end{messagebox} diff --git a/Master/texmf-dist/doc/support/arara/chapters/methods.tex b/Master/texmf-dist/doc/support/arara/chapters/methods.tex index 7775d5e06bd..ef0652feb79 100644 --- a/Master/texmf-dist/doc/support/arara/chapters/methods.tex +++ b/Master/texmf-dist/doc/support/arara/chapters/methods.tex @@ -8,7 +8,7 @@ As seen in Chapter~\ref{chap:mvel}, on page~\pageref{chap:mvel}, Java and MVEL code be used interchangeably within expressions and orb tags, including instantiation of classes into objects and invocation of methods. However, be mindful of explicitly importing Java packages and classes through the classic \rbox{import} statement, as MVEL does not automatically handle imports, or an exception will surely be raised. Alternatively, you can provide the full qualified name to classes as well. \end{messagebox} -Methods are listed with their complete signatures, including potential parameters and corresponding types. Also, the return type of a method is denoted by \rrbox{type} and refers to a typical Java data type (either class or primitive). Do not worry too much, as there are illustrative examples. A method available in the directive conditional context will be marked by \ctbox{C} next to the corresponding signature. Similarly, an entry marked by \ctbox{R} denotes that the corresponding method is available in the rule context. +Methods are listed with their complete signatures, including potential parameters and corresponding types. Also, the return type of a method is denoted by \rrbox{type} and refers to a typical Java data type (either class or primitive). Do not worry too much, as there are illustrative examples. A method available in the directive conditional context will be marked by \ctbox{C} next to the corresponding signature. Similarly, an entry marked by \ctbox{R} denotes that the corresponding method is available in the rule context. At last, an entry marked by \ctbox{E} denotes that the corresponding method is available in the orb tag expansion within a special \rbox{options} parameter in the directive context. \section{Files} \label{sec:files} @@ -25,7 +25,7 @@ if (file == getOriginalFile()) { } \end{codebox} -\item[\mdbox{R}{getOriginalReference()}{File}] This method returns the original file reference, as a \rbox{File} object, regardless of a potential reference override indirectly through the special \abox{files} parameter in the directive mapping, as seen in Section~\ref{sec:directives}, on page~\pageref{sec:directives}. +\item[\mdddbox{C}{E}{R}{getOriginalReference()}{File}] This method returns the original file reference, as a \rbox{File} object, regardless of a potential reference override indirectly through the special \abox{files} parameter in the directive mapping, as seen in Section~\ref{sec:directives}, on page~\pageref{sec:directives}. \begin{codebox}{Example}{teal}{\icnote}{white} if (reference.equals(getOriginalFile())) { @@ -46,7 +46,7 @@ if (reference.equals(getOriginalFile())) { f = toFile('thesis.tex'); \end{codebox} -\item[\mdbox{R}{getBasename(File file)}{String}] This method returns the base name (i.e, the name without the associated extension) of the provided \rbox{File} reference, as a string. Observe that this method ignores a potential path reference when extracting the base name. Also, this method will throw an exception if the provided reference is not a proper file. +\item[\mdddbox{C}{E}{R}{getBasename(File file)}{String}] This method returns the base name (i.e, the name without the associated extension) of the provided \rbox{File} reference, as a string. Observe that this method ignores a potential path reference when extracting the base name. Also, this method will throw an exception if the provided reference is not a proper file. \begin{codebox}{Example}{teal}{\icnote}{white} basename = getBasename(toFile('thesis.tex')); @@ -511,6 +511,22 @@ if (isUnix()) { System.out.println('Running Unix.'); } if (isCygwin()) { System.out.println('Running Cygwin.'); } \end{codebox} +\begin{messagebox}{Cygwin paths}{attentioncolour}{\icattention}{black} +It is worth mentioning that Cygwin has its own path handling which is not reliable when (JVM) applications need to invoke system commands. For instance, the following invocation does not work: + +\begin{codebox}{Example}{teal}{\icnote}{white} +% arara: pdflatex +\end{codebox} + +Since \rbox{pdflatex} is a symbolic link to \rbox{pdftex} with the proper format, we encourage Cygwin users to rely on the following trick: + +\begin{codebox}{Example}{teal}{\icnote}{white} +% arara: pdftex: { options: [ '--fmt=pdflatex' ] } +\end{codebox} + +The same trick can be employed by other \TeX\ engines with appropriate \rbox{--fmt} flags as well. We are still investigating this issue and looking for potential alternatives. +\end{messagebox} + \item[\mdbox{R}{isWindows(Object yes, Object no)}{Object}] This method checks if the underlying operating system vendor is Microsoft Windows. If the result holds true, the first parameter is returned. Otherwise, the second parameter is returned. \begin{codebox}{Example}{teal}{\icnote}{white} @@ -622,28 +638,32 @@ Please make sure to \emph{always} check the returned integer status when using c \end{messagebox} \begin{description} -\item[\mddbox{C}{R}{loadClass(File file, String name)}{Pair<Integer, Class>}] This method loads a class based on the canonical name from the provided \rbox{File} reference and returns an ordered pair containing the status and the class reference itself. The file must contain the Java bytecode, either directly accessible from a \rbox{class} file or packaged inside a \rbox{jar} file. If an exception is raised, this method returns the \rbox{Object} class reference as second entry of the pair. +\item[\mddbox{C}{R}{\parbox{0.32\textwidth}{loadClass(File file,\\ \hspace*{1em}String name)}}{\parbox{0.43\textwidth}{Pair<ClassLoading.\\ +\hspace*{1em}ClassLoadingStatus, Object>}}] This method loads a class based on the canonical name from the provided \rbox{File} reference and returns an ordered pair containing the status and the class reference itself. The file must contain the Java bytecode, either directly accessible from a \rbox{class} file or packaged inside a \rbox{jar} file. If an exception is raised, this method returns the \rbox{Object} class reference as second entry of the pair. \begin{codebox}{Example}{teal}{\icnote}{white} result = loadClass(toFile('mymath.jar'), 'com.github.cereda.mymath.Arithmetic'); \end{codebox} -\item[\mddbox{C}{R}{loadClass(String reference, String name)}{Pair<Integer, Class>}] This method loads a class based on the canonical name from the provided \rbox{String} reference and returns an ordered pair containing the status and the class reference itself. The file must contain the Java bytecode, either directly accessible from a \rbox{class} file or packaged inside a \rbox{jar} file. If an exception is raised, this method returns the \rbox{Object} class reference as second entry of the pair. +\item[\mddbox{C}{R}{\parbox{0.32\textwidth}{loadClass(String ref,\\ \hspace*{1em}String name)}}{\parbox{0.43\textwidth}{Pair<ClassLoading.\\ +\hspace*{1em}ClassLoadingStatus, Object>}}] This method loads a class based on the canonical name from the provided \rbox{String} reference and returns an ordered pair containing the status and the class reference itself. The file must contain the Java bytecode, either directly accessible from a \rbox{class} file or packaged inside a \rbox{jar} file. If an exception is raised, this method returns the \rbox{Object} class reference as second entry of the pair. \begin{codebox}{Example}{teal}{\icnote}{white} result = loadClass('mymath.jar', 'com.github.cereda.mymath.Arithmetic'); \end{codebox} -\item[\mddbox{C}{R}{loadObject(File file, String name)}{Pair<Integer, Object>}] This method loads a class based on the canonical name from the provided \rbox{File} reference and returns an ordered pair containing the status and a proper corresponding object instantiation. The file must contain the Java bytecode, either directly accessible from a \rbox{class} file or packaged inside a \rbox{jar} file. If an exception is raised, this method returns an \rbox{Object} object as second entry of the pair. +\item[\mddbox{C}{R}{\parbox{0.32\textwidth}{loadObject(File file,\\ \hspace*{1em}String name)}}{\parbox{0.43\textwidth}{Pair<ClassLoading.\\ +\hspace*{1em}ClassLoadingStatus, Object>}}] This method loads a class based on the canonical name from the provided \rbox{File} reference and returns an ordered pair containing the status and a proper corresponding object instantiation. The file must contain the Java bytecode, either directly accessible from a \rbox{class} file or packaged inside a \rbox{jar} file. If an exception is raised, this method returns an \rbox{Object} object as second entry of the pair. \begin{codebox}{Example}{teal}{\icnote}{white} result = loadObject(toFile('mymath.jar'), 'com.github.cereda.mymath.Trigonometric'); \end{codebox} -\item[\mddbox{C}{R}{loadObject(String reference, String name)}{Pair<Integer, Object>}] This method loads a class based on the canonical name from the provided \rbox{String} reference and returns an ordered pair containing the status and a proper corresponding object instantiation. The file must contain the Java bytecode, either directly accessible from a \rbox{class} file or packaged inside a \rbox{jar} file. If an exception is raised, this method returns an \rbox{Object} object as second entry of the pair. +\item[\mddbox{C}{R}{\parbox{0.32\textwidth}{loadObject(String ref,\\ \hspace*{1em}String name)}}{\parbox{0.43\textwidth}{Pair<ClassLoading.\\ +\hspace*{1em}ClassLoadingStatus, Object>}}] This method loads a class based on the canonical name from the provided \rbox{String} reference and returns an ordered pair containing the status and a proper corresponding object instantiation. The file must contain the Java bytecode, either directly accessible from a \rbox{class} file or packaged inside a \rbox{jar} file. If an exception is raised, this method returns an \rbox{Object} object as second entry of the pair. \begin{codebox}{Example}{teal}{\icnote}{white} result = loadObject('mymath.jar', @@ -896,7 +916,7 @@ It is important to observe that the \rbox{Session} object provided by our tool f \end{messagebox} \begin{description} -\item[\mdbox{R}{getSession()}{Session}] This method, as the name implies, returns the \rbox{Session} object for data sharing across rule contexts. Keep in mind that a session cannot contain duplicate keys. Each key can map to at most one value. +\item[\mdddbox{C}{E}{R}{getSession()}{Session}] This method, as the name implies, returns the \rbox{Session} object for data sharing across rule contexts. Keep in mind that a session cannot contain duplicate keys. Each key can map to at most one value. \begin{codebox}{Example}{teal}{\icnote}{white} name = getSession().get('name'); @@ -933,10 +953,6 @@ According to the \href{https://en.wikipedia.org/wiki/PATH_(variable)}{Wikipedia result = unsafelyExecuteSystemCommand(getCommand('ls')); \end{codebox} -\begin{messagebox}{Important change in version 5.0}{araracolour}{\icattention}{white} -\textbf{Working directory support} -- \arara\ now executes commands obtained from \rbox{getCommandWithWorkingDirectory} correctly. Previously, the working directory got silently ignored. This makes \arara\ even more powerful but we decided to change this for the sake of consistency. -\end{messagebox} - \begin{messagebox}{Hic sunt leones}{attentioncolour}{\icattention}{black} Please \emph{do not abuse} this method! Keep in mind that this particular feature is included for very specific scenarios in which the command streams are needed ahead of time for proper decision making. \end{messagebox} @@ -946,20 +962,49 @@ Please \emph{do not abuse} this method! Keep in mind that this particular featur \begin{codebox}{Example}{teal}{\icnote}{white} valid = isSubdirectory(toFile('chapters/')); \end{codebox} + +\item[\mdbox{R}{getOrNull(List<String> list, int index)}{String}] This method attempts to retrieve +a list element based on an integer index. If the index is out of bounds, a \rbox{null} value is returned instead. + +\begin{codebox}{Example}{teal}{\icnote}{white} +list = [ 'a', 'b', 'c' ]; +third = getOrNull(list, 2); +\end{codebox} + +\item[\mdbox{R}{getOrNull(List<String> list)}{String}] This method attempts to retrieve +the first element of the provided list. If the list is empty, a \rbox{null} value is returned instead. + +\begin{codebox}{Example}{teal}{\icnote}{white} +list = [ 'a', 'b', 'c' ]; +first = getOrNull(list); +\end{codebox} \end{description} \begin{messagebox}{Flags and reserved storage in a session}{araracolour}{\icok}{white} -Within a session there are two ``reserved'' namespaces: \verb|arara| and \verb|environment|. The latter is quite intuitive: \arara\ will store the current state of the systems environment variables in its session. You may alter these values in the session storage but they will not be written back to the system configuration. To access an environment variable, you can use its usual name prefixed by \verb|environment:|. +From version 6.0 on, there are three reserved namespaces within a session. They are described as follows: + +\begin{description} +\item[{\rbox[araracolour]{environment}}] This namespace is quite intuitive: \arara\ will store the current state of the systems environment variables in its session. You may alter these values in the session storage but they will not be written back to the system configuration. To access an environment variable, you can use its usual name prefixed by \rbox[araracolour]{environment:}: \begin{codebox}{Example}{teal}{\icnote}{white} path = getSession().get('environment:PATH'); \end{codebox} -The \verb|arara| namespace is a bit different. It provides flags that control \arara s behaviour. Flags are used in rules and may be manipulated by the user. Be aware, that every change in this namespace will result in \arara\ acting like you know what you did. Use this power with care. Currently, there is only one relevant flag: \verb|arara:FILENAME:halt|. This will stop the currently run command execution on the file with the specified file name. The value of this map entry is the exit status you want \arara\ to have. +\item[{\rbox[araracolour]{arara}}] This namespace provides flags that control the underlying behaviour of \arara. Flags are used in rules and may be manipulated by the user. Be aware that every change in this namespace will result in the tool acting like you know what you did. Use this power with care. Currently, there is only one relevant flag: \rbox{arara:FILENAME:halt}. This will stop the currently run command execution on the file with the specified file name. The value of this map entry is the exit status you want \arara\ to have. \begin{codebox}{Example}{teal}{\icnote}{white} -path = getSession().put('arara:myfile.tex:halt', 42); +getSession().put('arara:myfile.tex:halt', 42); \end{codebox} + +\item[{\rbox[araracolour]{arg}}] This namespace acts as a bridge between contexts and the command line by providing access to key/value pairs defined at runtime by \opbox{{-}call-property} command line flags. + +\begin{codebox}{Example}{teal}{\icnote}{white} +key = getSession().get('arg:key'); +\end{codebox} + +Please refer to Chapter~\ref{chap:commandline}, on page~\pageref{chap:commandline} for more details on the \opbox{{-}call-property} command line flag. + +\end{description} \end{messagebox} The methods presented in this section provide interesting features for persistent data sharing, error handling, early command execution, and templating. It is important to note that more classes, objects and methods can be incorporated into \arara\ through class loading and object instantiation, extending the features and enhancing the overall user experience. 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): diff --git a/Master/texmf-dist/doc/support/arara/rules/quickstart.yaml b/Master/texmf-dist/doc/support/arara/rules/quickstart.yaml new file mode 100644 index 00000000000..fd2fd0f848d --- /dev/null +++ b/Master/texmf-dist/doc/support/arara/rules/quickstart.yaml @@ -0,0 +1,41 @@ +!config +identifier: quickstart +name: The arara quickstart guide +authors: +- Island of TeX +commands: +- name: The PDFLaTeX engine + command: > + @{ + return getCommand('pdflatex', reference); + } +- name: The PDFLaTeX engine + command: > + @{ + return getCommand('pdflatex', reference); + } +- name: File cleanup + command: > + @{ + matches = listFilesByExtensions('.', + [ 'aux' ], true); + prefix = []; + if (isUnix()) { + prefix = [ 'rm', '-f' ]; + } + else { + prefix = [ 'cmd', '/c', 'del' ]; + } + removals = []; + extensions = [ 'listing', 'log', 'toc', + 'out', 'synctex.gz' ]; + foreach (extension : extensions) { + removals.add(getCommand(prefix, getBasename(reference) + .concat('.').concat(extension))); + } + foreach (match : matches) { + removals.add(getCommand(prefix, match.getCanonicalPath())); + } + return removals; + } +arguments: [] diff --git a/Master/texmf-dist/doc/support/arara/version.tex b/Master/texmf-dist/doc/support/arara/version.tex new file mode 100644 index 00000000000..f4965a313a2 --- /dev/null +++ b/Master/texmf-dist/doc/support/arara/version.tex @@ -0,0 +1 @@ +6.0.0
\ No newline at end of file diff --git a/Master/texmf-dist/scripts/arara/arara.jar b/Master/texmf-dist/scripts/arara/arara.jar Binary files differindex 8c97b0e5463..72ac5fc879f 100644 --- a/Master/texmf-dist/scripts/arara/arara.jar +++ b/Master/texmf-dist/scripts/arara/arara.jar diff --git a/Master/texmf-dist/scripts/arara/arara.sh b/Master/texmf-dist/scripts/arara/arara.sh index 12efa361a6b..1582f531e77 100755 --- a/Master/texmf-dist/scripts/arara/arara.sh +++ b/Master/texmf-dist/scripts/arara/arara.sh @@ -14,4 +14,4 @@ if echo "$kernel" | grep CYGWIN >/dev/null; then jarpath=`cygpath -w "$jarpath"` fi -exec java -jar "$jarpath" "$@"
\ No newline at end of file +exec java -jar "$jarpath" "$@" diff --git a/Master/texmf-dist/scripts/arara/rules/animate.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-animate.yaml index 769ceaecee1..4e7acc9bfb0 100644 --- a/Master/texmf-dist/scripts/arara/rules/animate.yaml +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-animate.yaml @@ -13,7 +13,6 @@ commands: - name: The Convert program command: > @{ - prefix = []; input = getBasename(reference.getName()).concat('.pdf'); output = getBasename(reference.getName()).concat('.gif'); return getCommand(program, '-delay', delay, '-loop', diff --git a/Master/texmf-dist/scripts/arara/rules/asymptote.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-asymptote.yaml index 232213f73d4..232213f73d4 100644 --- a/Master/texmf-dist/scripts/arara/rules/asymptote.yaml +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-asymptote.yaml diff --git a/Master/texmf-dist/scripts/arara/rules/authorindex.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-authorindex.yaml index a7e32141a97..a7e32141a97 100644 --- a/Master/texmf-dist/scripts/arara/rules/authorindex.yaml +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-authorindex.yaml diff --git a/Master/texmf-dist/scripts/arara/rules/bib2gls.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-bib2gls.yaml index 513a7207f76..aaff9986ff1 100644 --- a/Master/texmf-dist/scripts/arara/rules/bib2gls.yaml +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-bib2gls.yaml @@ -12,7 +12,7 @@ commands: - name: The Bib2Gls software command: > @{ - if (isNotEmpty(clean)) + if (!clean.isEmpty()) { prefix = []; if (isUnix()) { @@ -31,9 +31,9 @@ commands: java.util.regex.Pattern.compile( "\\\\glsxtr@resource\\{.*\\}\\{([^\\}]+)\\}"); - if (isNotEmpty(trans)) + if (!trans.isEmpty()) { - if (trans == getOriginalFile()) + if (trans[0] == getOriginalFile()) { throwError('I cannot remove the main file reference.'); } diff --git a/Master/texmf-dist/scripts/arara/rules/biber.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-biber.yaml index 6399df64fbb..98c294a4998 100644 --- a/Master/texmf-dist/scripts/arara/rules/biber.yaml +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-biber.yaml @@ -12,7 +12,7 @@ commands: - name: The Biber reference management software command: > @{ - if (tool) { + if (isTrue(tool[0])) { return getCommand('biber', '--tool', options); } else { @@ -24,12 +24,9 @@ arguments: - identifier: tool flag: > @{ - return isTrue(parameters.tool); - } - default: > - @{ - return false; + return parameters.tool; } + default: false - identifier: options flag: > @{ diff --git a/Master/texmf-dist/scripts/arara/rules/bibtex.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-bibtex.yaml index a8457584406..a8457584406 100644 --- a/Master/texmf-dist/scripts/arara/rules/bibtex.yaml +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-bibtex.yaml diff --git a/Master/texmf-dist/scripts/arara/rules/bibtex8.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-bibtex8.yaml index 2526c82b5a4..2526c82b5a4 100644 --- a/Master/texmf-dist/scripts/arara/rules/bibtex8.yaml +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-bibtex8.yaml diff --git a/Master/texmf-dist/scripts/arara/rules/bibtexu.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-bibtexu.yaml index 708a3ebfb6d..708a3ebfb6d 100644 --- a/Master/texmf-dist/scripts/arara/rules/bibtexu.yaml +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-bibtexu.yaml diff --git a/Master/texmf-dist/scripts/arara/rules/clean.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-clean.yaml index aa07560cb90..aa07560cb90 100644 --- a/Master/texmf-dist/scripts/arara/rules/clean.yaml +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-clean.yaml diff --git a/Master/texmf-dist/scripts/arara/rules/context.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-context.yaml index bf5b1c5b041..49dc9e5f609 100644 --- a/Master/texmf-dist/scripts/arara/rules/context.yaml +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-context.yaml @@ -47,7 +47,7 @@ arguments: return p.get(parameters.purge); } else { - throwError('Invalid value, expected either partial or all.'); + throwError('Invalid value, expected partial, result or all.'); } } - identifier: modules @@ -168,4 +168,3 @@ arguments: throwError('I was expecting a list of options.'); } } - diff --git a/Master/texmf-dist/scripts/arara/rules/convert.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-convert.yaml index 7a2140d0a77..7a2140d0a77 100644 --- a/Master/texmf-dist/scripts/arara/rules/convert.yaml +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-convert.yaml diff --git a/Master/texmf-dist/scripts/arara/rules/arara-rule-copy.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-copy.yaml new file mode 100644 index 00000000000..b43ef1e28ac --- /dev/null +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-copy.yaml @@ -0,0 +1,36 @@ +!config +# Arara, the cool TeX automation tool +# Copyright (c) 2020, Island of TeX +# All rights reserved. +# +# This rule is part of arara. +identifier: copy +name: Copy +authors: +- Island of TeX +commands: +- name: The OS copy call + command: > + @{ + prefix = []; + if (isUnix()) { + prefix = [ 'cp', '-f' ]; + } + else { + prefix = [ 'cmd', '/c', 'copy', '/Y' ]; + } + t = isList(target) ? target[0] : target; + f = toFile(t).getCanonicalFile(); + if (getOriginalReference().equals(f)) { + throwError('I cannot overwrite the main file reference.'); + } + return getCommand(prefix, reference, t); + } +arguments: +- identifier: target + flag: > + @{ + return parameters.target; + } + required: true + diff --git a/Master/texmf-dist/scripts/arara/rules/csplain.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-csplain.yaml index 720cd0cc8fe..720cd0cc8fe 100644 --- a/Master/texmf-dist/scripts/arara/rules/csplain.yaml +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-csplain.yaml diff --git a/Master/texmf-dist/scripts/arara/rules/datatooltk.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-datatooltk.yaml index 13526dbc130..16c84dc439d 100644 --- a/Master/texmf-dist/scripts/arara/rules/datatooltk.yaml +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-datatooltk.yaml @@ -73,12 +73,9 @@ arguments: - identifier: noconsole flag: > @{ - [ '--noconsole-action', parameters.noconsole ] - } - default: > - @{ - [ '--noconsole-action', 'gui'] + [ '--noconsole-action', isEmpty(parameters.noconsole, 'gui', parameters.noconsole) ] } + default: '' - identifier: probsoln flag: > @{ diff --git a/Master/texmf-dist/scripts/arara/rules/detex.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-detex.yaml index f94c7a274e8..94fa359f833 100644 --- a/Master/texmf-dist/scripts/arara/rules/detex.yaml +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-detex.yaml @@ -1,6 +1,6 @@ !config # Arara, the cool TeX automation tool -# Copyright (c) 2020, Island of TeX +# Copyright (c) 2020, Island of TeX # All rights reserved. # # This rule is part of arara. @@ -14,13 +14,13 @@ commands: @{ c = getCommand('detex', references, mode, follow, math, spaces, words, environments, reference.getName()); - if (isEmpty(output)) { + if (output.isEmpty()) { return c; } else { p = unsafelyExecuteSystemCommand(c); if (p.first == 0) { - return writeToFile(toFile(output), p.second, false); + return writeToFile(toFile(output[0]), p.second, false); } else { return false; @@ -79,4 +79,3 @@ arguments: @{ return parameters.output; } - diff --git a/Master/texmf-dist/scripts/arara/rules/dvipdfm.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-dvipdfm.yaml index c4f44309b86..0f603a1a263 100644 --- a/Master/texmf-dist/scripts/arara/rules/dvipdfm.yaml +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-dvipdfm.yaml @@ -13,19 +13,16 @@ commands: command: > @{ base = getBasename(reference.getName()).concat('.dvi'); - out = getBasename(output).concat('.pdf'); + out = getBasename(output[0]).concat('.pdf'); return getCommand('dvipdfm', base, '-o', out, options); } arguments: - identifier: output flag: > @{ - parameters.output - } - default: > - @{ - reference.getName() + isEmpty(parameters.output, reference.getName(), parameters.output) } + default: '' - identifier: options flag: > @{ diff --git a/Master/texmf-dist/scripts/arara/rules/dvipdfmx.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-dvipdfmx.yaml index b9b73319e3f..b4d8e19afa5 100644 --- a/Master/texmf-dist/scripts/arara/rules/dvipdfmx.yaml +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-dvipdfmx.yaml @@ -13,19 +13,16 @@ commands: command: > @{ base = getBasename(reference.getName()).concat('.dvi'); - out = getBasename(output).concat('.pdf'); + out = getBasename(output[0]).concat('.pdf'); return getCommand('dvipdfmx', base, '-o', out, options); } arguments: - identifier: output flag: > @{ - parameters.output - } - default: > - @{ - reference.getName() + isEmpty(parameters.output, reference.getName(), parameters.output) } + default: '' - identifier: options flag: > @{ diff --git a/Master/texmf-dist/scripts/arara/rules/dvips.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-dvips.yaml index 78a2cff58dd..4cde26fa991 100644 --- a/Master/texmf-dist/scripts/arara/rules/dvips.yaml +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-dvips.yaml @@ -13,19 +13,16 @@ commands: command: > @{ base = getBasename(reference.getName()).concat('.dvi'); - out = getBasename(output).concat('.ps'); + out = getBasename(output[0]).concat('.ps'); return getCommand('dvips', base, '-o', out, options); } arguments: - identifier: output flag: > @{ - parameters.output - } - default: > - @{ - reference.getName() + isEmpty(parameters.output, reference.getName(), parameters.output) } + default: '' - identifier: options flag: > @{ diff --git a/Master/texmf-dist/scripts/arara/rules/dvipspdf.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-dvipspdf.yaml index 68c12dde345..d7e331873c4 100644 --- a/Master/texmf-dist/scripts/arara/rules/dvipspdf.yaml +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-dvipspdf.yaml @@ -20,19 +20,16 @@ commands: command: > @{ base = getBasename(reference.getName()).concat('.ps'); - out = getBasename(output).concat('.pdf'); + out = getBasename(output[0]).concat('.pdf'); return getCommand('ps2pdf', options2, base, '-o', out); } arguments: - identifier: output flag: > @{ - parameters.output - } - default: > - @{ - reference.getName() + isEmpty(parameters.output, reference.getName(), parameters.output) } + default: '' - identifier: options1 flag: > @{ diff --git a/Master/texmf-dist/scripts/arara/rules/arara-rule-dvisvgm.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-dvisvgm.yaml new file mode 100644 index 00000000000..92c7b4ea683 --- /dev/null +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-dvisvgm.yaml @@ -0,0 +1,57 @@ +!config +# Arara, the cool TeX automation tool +# Copyright (c) 2020, Island of TeX +# All rights reserved. +# +# This rule is part of arara. +identifier: dvisvgm +name: DVISVGM +authors: +- samcarter +- Pablo González +commands: +- name: The dvisvgm program + command: > + @{ + base = getBasename(reference.getName()). + concat('.').concat(entry[0]); + return getCommand('dvisvgm', getOrNull(entry, 1), pages, + options, base); + } +arguments: +- identifier: pages + flag: > + @{ + if (isList(parameters.pages)) { + q = []; + foreach (p : parameters.pages) q.add(p.toString()); + return [ '--page='.concat(String.join(',', q)) ]; + } + else { + throwError('I was expecting a list of pages.'); + } + } +- identifier: entry + flag: > + @{ + formats = [ 'dvi' : [ 'dvi' ], 'xdv' : [ 'xdv' ], + 'pdf' : [ 'pdf', '--pdf' ], + 'eps' : [ 'eps', '--eps' ] ]; + if (formats.keySet().contains(parameters.entry)) { + return formats.get(parameters.entry); + } + else { + throwError('The valid formats are: ' + formats.keySet()); + } + } + default: dvi +- identifier: options + flag: > + @{ + if (isList(parameters.options)) { + return parameters.options; + } + else { + throwError('I was expecting a list of options.'); + } + } diff --git a/Master/texmf-dist/scripts/arara/rules/etex.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-etex.yaml index e039b143dad..e039b143dad 100644 --- a/Master/texmf-dist/scripts/arara/rules/etex.yaml +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-etex.yaml diff --git a/Master/texmf-dist/scripts/arara/rules/fig2dev.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-fig2dev.yaml index 4e796e5c4d6..4e796e5c4d6 100644 --- a/Master/texmf-dist/scripts/arara/rules/fig2dev.yaml +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-fig2dev.yaml diff --git a/Master/texmf-dist/scripts/arara/rules/frontespizio.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-frontespizio.yaml index 2cabec38a0d..2cabec38a0d 100644 --- a/Master/texmf-dist/scripts/arara/rules/frontespizio.yaml +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-frontespizio.yaml diff --git a/Master/texmf-dist/scripts/arara/rules/arara-rule-ghostscript.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-ghostscript.yaml new file mode 100644 index 00000000000..7d3f26c6be7 --- /dev/null +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-ghostscript.yaml @@ -0,0 +1,44 @@ +!config +# Arara, the cool TeX automation tool +# Copyright (c) 2020, Island of TeX +# All rights reserved. +# +# This rule is part of arara. +identifier: ghostscript +name: GhostScript +authors: +- Island of TeX +commands: +- name: The command line tool + command: > + @{ + return getCommand(program, device, output, options); + } +arguments: +- identifier: program + flag: > + @{ + return parameters.program; + } + default: 'gs' +- identifier: options + flag: > + @{ + if (isList(parameters.options)) { + return parameters.options; + } + else { + throwError('I was expecting a list of options.'); + } + } + required: true +- identifier: device + flag: > + @{ + return '-sDEVICE='.concat(parameters.device); + } +- identifier: output + flag: > + @{ + return '-sOutputFile='.concat(parameters.output); + } diff --git a/Master/texmf-dist/scripts/arara/rules/arara-rule-gnuplot.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-gnuplot.yaml new file mode 100644 index 00000000000..e670099535e --- /dev/null +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-gnuplot.yaml @@ -0,0 +1,46 @@ +!config +# Arara, the cool TeX automation tool +# Copyright (c) 2020, Island of TeX +# All rights reserved. +# +# This rule is part of arara. +identifier: gnuplot +name: The Gnuplot program +authors: +- Island of TeX +commands: +- name: Gnuplot + command: > + @{ + c = []; + foreach (entry : input) { + c.add(getCommand('gnuplot', persist, default, commands, entry)); + } + return c; + } +arguments: +- identifier: persist + flag: > + @{ + return isTrue(parameters.persist, '--persist'); + } +- identifier: default + flag: > + @{ + return isTrue(parameters.default, '--default'); + } +- identifier: commands + flag: > + @{ + return [ '-e', parameters.commands ]; + } +- identifier: input + flag: > + @{ + if (isList(parameters.input)) { + return parameters.input; + } else { + throwError('I was expecting a list of input files.'); + } + } + required: true diff --git a/Master/texmf-dist/scripts/arara/rules/halt.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-halt.yaml index 3ac9106e909..3ac9106e909 100644 --- a/Master/texmf-dist/scripts/arara/rules/halt.yaml +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-halt.yaml diff --git a/Master/texmf-dist/scripts/arara/rules/indent.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-indent.yaml index b6dce8b2d53..b6dce8b2d53 100644 --- a/Master/texmf-dist/scripts/arara/rules/indent.yaml +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-indent.yaml diff --git a/Master/texmf-dist/scripts/arara/rules/knitr.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-knitr.yaml index a2e5fcd7bf5..2385589615a 100644 --- a/Master/texmf-dist/scripts/arara/rules/knitr.yaml +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-knitr.yaml @@ -14,14 +14,14 @@ commands: command: > @{ elements = []; - if (!isEmpty(tangle)) elements.add('tangle = ' + tangle); - if (!isEmpty(quiet)) elements.add('quiet = ' + quiet); - elements.add('envir = ' + envir); - elements.add('encoding = ' + encoding); + if (!tangle.isEmpty()) elements.add('tangle = ' + tangle[0]); + if (!quiet.isEmpty()) elements.add('quiet = ' + quiet[0]); + out = output.isEmpty() ? 'NULL' : '"' + output[0] + '"'; + elements.add('envir = ' + envir[0]); + elements.add('encoding = ' + encoding[0]); return getCommand('Rscript', '-e', 'library(knitr); knit("' + reference.getName() + '", ' + - 'output = ' + isEmpty(output, 'NULL', '"' + output + '"') + ', ' + - String.join(', ', elements) + ')'); + 'output = ' + out + ', ' + String.join(', ', elements) + ')'); } arguments: - identifier: output diff --git a/Master/texmf-dist/scripts/arara/rules/latex.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-latex.yaml index fc96395c233..519e609a278 100644 --- a/Master/texmf-dist/scripts/arara/rules/latex.yaml +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-latex.yaml @@ -26,7 +26,7 @@ arguments: throwError('The valid branch values are: ' + engines.keySet()); } } - default: 'latex' + default: 'stable' - identifier: interaction flag: > @{ diff --git a/Master/texmf-dist/scripts/arara/rules/latexmk.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-latexmk.yaml index 455f942fdb1..2b02e622b62 100644 --- a/Master/texmf-dist/scripts/arara/rules/latexmk.yaml +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-latexmk.yaml @@ -12,12 +12,12 @@ commands: - name: Tool LaTeXmk command: > @{ - if (isNotEmpty(clean)) { + if (!clean.isEmpty()) { return getCommand('latexmk', clean, options); } else { - return getCommand('latexmk', isEmpty(program, engine, - program), options, reference.getName()); + return getCommand('latexmk', isTrue(program.isEmpty(), + engine, program), options, reference.getName()); } } arguments: @@ -47,7 +47,11 @@ arguments: if ([ 'latex', 'pdflatex', 'xelatex', 'lualatex' ].contains(parameters.engine)) { flags = [ 'latex' : '-dvi', 'pdflatex' : '-pdf', - 'xelatex' : '-xelatex', 'lualatex' : '-lualatex' ]; + 'xelatex' : '-xelatex', 'lualatex' : '-lualatex', + 'latex-dev' : [ '-dvi', '-e', "$latex='latex-dev'" ], + 'pdflatex-dev' : [ '-pdf', '-e', "$pdflatex='pdflatex-dev'" ], + 'xelatex-dev' : [ '-xelatex', '-e', "$xelatex='xelatex-dev'" ], + 'lualatex-dev' : [ '-lualatex', '-e', "$lualatex='lualatex-dev'" ] ]; return flags[parameters.engine]; } else { diff --git a/Master/texmf-dist/scripts/arara/rules/arara-rule-llmk.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-llmk.yaml new file mode 100644 index 00000000000..1a6864225ae --- /dev/null +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-llmk.yaml @@ -0,0 +1,57 @@ +!config +# Arara, the cool TeX automation tool +# Copyright (c) 2020, Island of TeX +# All rights reserved. +# +# This rule is part of arara. +identifier: llmk +name: LLMK +authors: +- Island of TeX +commands: +- name: The automation tool + command: > + @{ + return getCommand('llmk', clean, debug, dry, + mode, reference.getName()); + } +arguments: +- identifier: clean + flag: > + @{ + goals = [ 'partial' : '--clean', 'all' : '--clobber' ]; + if (goals.keySet().contains(parameters.clean)) { + return goals.get(parameters.clean); + } + else { + throwError('The provided value is invalid.'); + } + } +- identifier: debug + flag: > + @{ + if (parameters.debug.equals('all')) { + return '-D'; + } + else { + return [ '-d', parameters.debug ]; + } + } +- identifier: dry + flag: > + @{ + return isTrue(parameters.dry, '--dry-run'); + } +- identifier: mode + flag: > + @{ + modes = [ 'quiet' : '-q', 'silent' : '-s', + 'verbose' : '-v' ]; + if (modes.keySet().contains(parameters.mode)) { + return modes.get(parameters.mode); + } + else { + throwError('Invalid mode name.'); + } + } + diff --git a/Master/texmf-dist/scripts/arara/rules/arara-rule-ltx2any.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-ltx2any.yaml new file mode 100644 index 00000000000..e60ff8902d4 --- /dev/null +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-ltx2any.yaml @@ -0,0 +1,110 @@ +!config +# Arara, the cool TeX automation tool +# Copyright (c) 2020, Island of TeX +# All rights reserved. +# +# This rule is part of arara. +identifier: ltx2any +name: LTX2any +authors: +- Island of TeX +commands: +- name: The automation tool + command: > + @{ + return getCommand('ltx2any', clean, engine, parameters, + tikzimages, jobname, logname, logformat, + loglevel, frequency, directory, synctex, + options, reference.getName()); + } +arguments: +- identifier: clean + flag: > + @{ + return isTrue(parameters.clean, '-c'); + } +- identifier: engine + flag: > + @{ + return [ '-e', parameters.engine ]; + } +- identifier: parameters + flag: > + @{ + if (isList(parameters.parameters)) { + return [ '-ep', String.join(' ', + parameters.parameters) ]; + } + else { + throwError('I was execting a list of parameters.'); + } + } +- identifier: tikzimages + flag: > + @{ + if (isList(parameters.tikzimages)) { + return [ '-ir', String.join(':', + parameters.tikzimages) ]; + } + else { + throwError('I was expecting a list of images.'); + } + } +- identifier: jobname + flag: > + @{ + return [ '-j', parameters.jobname ]; + } +- identifier: logname + flag: > + @{ + return [ '-l', parameters.logname ]; + } +- identifier: logformat + flag: > + @{ + fts = [ 'raw' : 'raw', 'markdown' : 'md', + 'pdf' : 'pdf' ]; + if (fts.keySet().contains(parameters.logformat)) { + return [ '-lf', fts.get(parameters.logformat) ]; + } + else { + throw('Invalid log format.'); + } + } +- identifier: loglevel + flag: > + @{ + ll = [ 'error', 'warning', 'info' ]; + if (ll.contains(parameters.loglevel)) { + return [ '-ll', parameters.loglevel ]; + } + else { + throwError('Invalid log level.'); + } + } +- identifier: frequency + flag: > + @{ + return [ '-n', parameters.frequency ]; + } +- identifier: directory + flag: > + @{ + return [ '-t', parameters.directory ]; + } +- identifier: synctex + flag: > + @{ + return isTrue(parameters.synctex, '-synctex'); + } +- identifier: options + flag: > + @{ + if (isList(parameters.options)) { + return parameters.options; + } + else { + throwError('I was expecting a list of options.'); + } + } diff --git a/Master/texmf-dist/scripts/arara/rules/luahbtex.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-luahbtex.yaml index cf4fde56e4e..cf4fde56e4e 100644 --- a/Master/texmf-dist/scripts/arara/rules/luahbtex.yaml +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-luahbtex.yaml diff --git a/Master/texmf-dist/scripts/arara/rules/lualatex.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-lualatex.yaml index de68a48b8ff..4eed7972c67 100644 --- a/Master/texmf-dist/scripts/arara/rules/lualatex.yaml +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-lualatex.yaml @@ -26,7 +26,7 @@ arguments: throwError('The valid branch values are: ' + engines.keySet()); } } - default: 'lualatex' + default: 'stable' - identifier: interaction flag: > @{ diff --git a/Master/texmf-dist/scripts/arara/rules/luatex.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-luatex.yaml index 03a726fa643..03a726fa643 100644 --- a/Master/texmf-dist/scripts/arara/rules/luatex.yaml +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-luatex.yaml diff --git a/Master/texmf-dist/scripts/arara/rules/make.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-make.yaml index afc83a6e9ca..26f2183c70a 100644 --- a/Master/texmf-dist/scripts/arara/rules/make.yaml +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-make.yaml @@ -12,7 +12,7 @@ commands: - name: The Make program command: > @{ - if (isNotEmpty(targets)) { + if (!targets.isEmpty()) { tasks = []; for (target : targets) { tasks.add(getCommand('make', target, options)); diff --git a/Master/texmf-dist/scripts/arara/rules/makeglossaries.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-makeglossaries.yaml index 7cb47cc5df8..fe39fa534a7 100644 --- a/Master/texmf-dist/scripts/arara/rules/makeglossaries.yaml +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-makeglossaries.yaml @@ -12,7 +12,7 @@ commands: - name: The MakeGlossaries software command: > @{ - if (isEmpty(clean)) + if (clean.isEmpty()) { return getCommand('makeglossaries', options, getBasename(reference.getName())); @@ -38,7 +38,7 @@ commands: "\\\\@newglossary\\{.*\\}\\{(.*)\\}\\{(.*)\\}\\{(.*)\\}"); java.util.regex.Pattern istPattern = - (clean == 'partial' ? null : + (clean[0] == 'partial' ? null : java.util.regex.Pattern.compile("\\\\@istfilename\\{(.*)\\}")); foreach (line: lines) diff --git a/Master/texmf-dist/scripts/arara/rules/makeglossarieslite.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-makeglossarieslite.yaml index c384179f44f..c384179f44f 100644 --- a/Master/texmf-dist/scripts/arara/rules/makeglossarieslite.yaml +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-makeglossarieslite.yaml diff --git a/Master/texmf-dist/scripts/arara/rules/makeindex.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-makeindex.yaml index 25b9e44c902..c0bf7a36c84 100644 --- a/Master/texmf-dist/scripts/arara/rules/makeindex.yaml +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-makeindex.yaml @@ -14,8 +14,8 @@ commands: @{ base = getBasename(reference.getName()); infile = base.concat('.').concat(input); - outfile = [ '-o', base.concat('.').concat(output) ]; - logfile = [ '-t', base.concat('.').concat(log) ]; + outfile = [ '-o', base.concat('.').concat(output[0]) ]; + logfile = [ '-t', base.concat('.').concat(log[0]) ]; return getCommand('makeindex', german, style, order, options, logfile, infile, outfile); } diff --git a/Master/texmf-dist/scripts/arara/rules/metapost.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-metapost.yaml index e334210ce5e..e334210ce5e 100644 --- a/Master/texmf-dist/scripts/arara/rules/metapost.yaml +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-metapost.yaml diff --git a/Master/texmf-dist/scripts/arara/rules/arara-rule-move.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-move.yaml new file mode 100644 index 00000000000..d11365ada0b --- /dev/null +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-move.yaml @@ -0,0 +1,39 @@ +!config +# Arara, the cool TeX automation tool +# Copyright (c) 2020, Island of TeX +# All rights reserved. +# +# This rule is part of arara. +identifier: move +name: Move +authors: +- Island of TeX +commands: +- name: The OS move call + command: > + @{ + prefix = []; + if (isUnix()) { + prefix = [ 'mv', '-f' ]; + } + else { + prefix = [ 'cmd', '/c', 'move', '/Y' ]; + } + if (getOriginalReference() == reference) { + throwError('I cannot move the main file reference.'); + } + t = isList(target) ? target[0] : target; + f = toFile(t).getCanonicalFile(); + if (getOriginalReference().equals(f)) { + throwError('I cannot overwrite the main file reference.'); + } + return getCommand(prefix, reference, t); + } +arguments: +- identifier: target + flag: > + @{ + return parameters.target; + } + required: true + diff --git a/Master/texmf-dist/scripts/arara/rules/nomencl.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-nomencl.yaml index 4672cb4ea98..8d66acdb303 100644 --- a/Master/texmf-dist/scripts/arara/rules/nomencl.yaml +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-nomencl.yaml @@ -20,12 +20,9 @@ arguments: - identifier: style flag: > @{ - [ '-s', parameters.style ] - } - default: > - @{ - [ '-s', 'nomencl.ist' ] + [ '-s', isEmpty(parameters.style, 'nomencl.ist', parameters.style) ] } + default: '' - identifier: options flag: > @{ diff --git a/Master/texmf-dist/scripts/arara/rules/pbibtex.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-pbibtex.yaml index a313b7fe922..a313b7fe922 100644 --- a/Master/texmf-dist/scripts/arara/rules/pbibtex.yaml +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-pbibtex.yaml diff --git a/Master/texmf-dist/scripts/arara/rules/arara-rule-pdfcrop.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-pdfcrop.yaml new file mode 100644 index 00000000000..8ad93fd513b --- /dev/null +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-pdfcrop.yaml @@ -0,0 +1,132 @@ +!config +# Arara, the cool TeX automation tool +# Copyright (c) 2020, Island of TeX +# All rights reserved. +# +# This rule is part of arara. +identifier: pdfcrop +name: PDFCrop +authors: +- Island of TeX +commands: +- name: The cropping tool + command: > + @{ + base = getBasename(reference.getName()); + input = base.concat('.pdf'); + return getCommand('pdfcrop', verbose, debug, engine, + margins, clip, hires, ini, restricted, papersize, + resolution, bbox, uncompress, options, input, output); + } +arguments: +- identifier: output + flag: > + @{ + return isEmpty(parameters.output, + getBasename(reference.getName()). + concat('-crop.pdf'), + parameters.output); + } + default: '' +- identifier: verbose + flag: > + @{ + return isTrue(parameters.verbose, '--verbose', '--noverbose'); + } +- identifier: debug + flag: > + @{ + return isTrue(parameters.debug, '--debug', '--nodebug'); + } +- identifier: engine + flag: > + @{ + engines = [ 'pdftex', 'xetex', 'luatex' ]; + if (engines.contains(parameters.engine)) { + return '--'.concat(parameters.engine); + } + else { + throwError('The provided engine is invalid.'); + } + } +- identifier: margins + flag: > + @{ + if (isList(parameters.margins)) { + if (parameters.margins.size() != 4) { + throwError('Margins require 4 elements.'); + } + else { + ms = []; + foreach (m : parameters.margins) + ms.add(m.toString()); + return [ '--margins', String.join(' ', ms) ]; + } + } + else { + throwError('I was expecting a list.'); + } + } +- identifier: clip + flag: > + @{ + return isTrue(parameters.clip, '--clip', '--noclip'); + } +- identifier: hires + flag: > + @{ + return isTrue(parameters.hires, '--hires', '--nohires'); + } +- identifier: ini + flag: > + @{ + return isTrue(parameters.ini, '--ini', '--noini'); + } +- identifier: restricted + flag: > + @{ + return isTrue(parameters.restricted, '--restricted'); + } +- identifier: papersize + flag: > + @{ + return [ '--papersize', parameters.papersize ]; + } +- identifier: resolution + flag: > + @{ + return [ '--resolution', parameters.resolution ]; + } +- identifier: bbox + flag: > + @{ + if (isList(parameters.bbox)) { + if (parameters.bbox.size() != 4) { + throwError('Bounding box require 4 elements.'); + } + else { + ms = []; + foreach (m : parameters.bbox) + ms.add(m.toString()); + return [ '--margins', String.join(' ', ms) ]; + } + } + else { + throwError('I was expecting a list.'); + } + } +- identifier: uncompress + flag: > + @{ + return isTrue(parameters.uncompress, '--uncompress'); + } +- identifier: options + flag: > + @{ + if (isList(parameters.options)) { + return parameters.options; + } + else { + throwError('I was expecting a list of options.'); + } + } diff --git a/Master/texmf-dist/scripts/arara/rules/pdfcsplain.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-pdfcsplain.yaml index 079440628a3..079440628a3 100644 --- a/Master/texmf-dist/scripts/arara/rules/pdfcsplain.yaml +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-pdfcsplain.yaml diff --git a/Master/texmf-dist/scripts/arara/rules/pdflatex.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-pdflatex.yaml index c1ee2f90773..2056885281d 100644 --- a/Master/texmf-dist/scripts/arara/rules/pdflatex.yaml +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-pdflatex.yaml @@ -26,7 +26,7 @@ arguments: throwError('The valid branch values are: ' + engines.keySet()); } } - default: 'pdflatex' + default: 'stable' - identifier: interaction flag: > @{ diff --git a/Master/texmf-dist/scripts/arara/rules/pdftex.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-pdftex.yaml index c6699b7dca4..c6699b7dca4 100644 --- a/Master/texmf-dist/scripts/arara/rules/pdftex.yaml +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-pdftex.yaml diff --git a/Master/texmf-dist/scripts/arara/rules/pdftk.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-pdftk.yaml index a457d67d531..a457d67d531 100644 --- a/Master/texmf-dist/scripts/arara/rules/pdftk.yaml +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-pdftk.yaml diff --git a/Master/texmf-dist/scripts/arara/rules/perltex.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-perltex.yaml index 09a838153d6..09a838153d6 100644 --- a/Master/texmf-dist/scripts/arara/rules/perltex.yaml +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-perltex.yaml diff --git a/Master/texmf-dist/scripts/arara/rules/platex.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-platex.yaml index edf5d4864ba..41fca5d771c 100644 --- a/Master/texmf-dist/scripts/arara/rules/platex.yaml +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-platex.yaml @@ -26,7 +26,7 @@ arguments: throwError('The valid branch values are: ' + engines.keySet()); } } - default: 'platex' + default: 'stable' - identifier: interaction flag: > @{ diff --git a/Master/texmf-dist/scripts/arara/rules/ps2pdf.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-ps2pdf.yaml index dcc49f87b9d..3469a57d390 100644 --- a/Master/texmf-dist/scripts/arara/rules/ps2pdf.yaml +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-ps2pdf.yaml @@ -13,19 +13,16 @@ commands: command: > @{ infile = getBasename(reference.getName()).concat('.ps'); - outfile = getBasename(output).concat('.pdf'); + outfile = getBasename(output[0]).concat('.pdf'); return getCommand('ps2pdf', options, infile, outfile); } arguments: - identifier: output flag: > @{ - parameters.output - } - default: > - @{ - reference.getName() + isEmpty(parameters.output, reference.getName(), parameters.output) } + default: '' - identifier: options flag: > @{ diff --git a/Master/texmf-dist/scripts/arara/rules/ptex.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-ptex.yaml index 9367704cb9e..9367704cb9e 100644 --- a/Master/texmf-dist/scripts/arara/rules/ptex.yaml +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-ptex.yaml diff --git a/Master/texmf-dist/scripts/arara/rules/pythontex.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-pythontex.yaml index 671d4abe34a..671d4abe34a 100644 --- a/Master/texmf-dist/scripts/arara/rules/pythontex.yaml +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-pythontex.yaml diff --git a/Master/texmf-dist/scripts/arara/rules/qpdf.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-qpdf.yaml index c2cb852a7d9..c2cb852a7d9 100644 --- a/Master/texmf-dist/scripts/arara/rules/qpdf.yaml +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-qpdf.yaml diff --git a/Master/texmf-dist/scripts/arara/rules/arara-rule-sage.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-sage.yaml new file mode 100644 index 00000000000..15e89a6a4ef --- /dev/null +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-sage.yaml @@ -0,0 +1,59 @@ +!config +# Arara, the cool TeX automation tool +# Copyright (c) 2020, Island of TeX +# All rights reserved. +# +# This rule is part of arara. +identifier: sage +name: Sage +authors: +- Island of TeX +commands: +- name: The command line tool + command: > + @{ + base = getBasename(reference.getName()); + e = isList(extension) ? extension[0] : extension; + input = base.concat('.').concat(e); + return getCommand(program, command, dotsage, + options, input); + } +arguments: +- identifier: program + flag: > + @{ + return parameters.program; + } + default: 'sage' +- identifier: extension + flag: > + @{ + exts = [ 'sage', 'py', 'spyx' ]; + if (exts.contains(parameters.extension)) { + return parameters.extension; + } + else { + throwError('The provided extension is invalid.'); + } + } + default: 'sage' +- identifier: command + flag: > + @{ + return [ '-c', parameters.command ]; + } +- identifier: dotsage + flag: > + @{ + return isFalse(parameters.dotsage, '--nodotsage'); + } +- identifier: options + flag: > + @{ + if (isList(parameters.options)) { + return parameters.options; + } + else { + throwError('I was expecting a list of options.'); + } + } diff --git a/Master/texmf-dist/scripts/arara/rules/sketch.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-sketch.yaml index e7bae9b329b..e7bae9b329b 100644 --- a/Master/texmf-dist/scripts/arara/rules/sketch.yaml +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-sketch.yaml diff --git a/Master/texmf-dist/scripts/arara/rules/songidx.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-songidx.yaml index a1cadae4310..7d5fa870deb 100644 --- a/Master/texmf-dist/scripts/arara/rules/songidx.yaml +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-songidx.yaml @@ -13,7 +13,7 @@ commands: - name: The SongIDX Lua script command: > @{ - infile = getBasename(input).concat('.sxd'); + infile = getBasename(input[0]).concat('.sxd'); return getCommand('texlua', script, options, infile); } arguments: diff --git a/Master/texmf-dist/scripts/arara/rules/dvisvgm.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-spix.yaml index d0bae984de0..f19345cec2e 100644 --- a/Master/texmf-dist/scripts/arara/rules/dvisvgm.yaml +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-spix.yaml @@ -4,18 +4,22 @@ # All rights reserved. # # This rule is part of arara. -identifier: dvisvgm -name: DVISVGM +identifier: spix +name: SpiX authors: -- samcarter +- Island of TeX commands: -- name: The dvisvgm program +- name: The automation tool command: > @{ - base = getBasename(reference.getName()).concat('.dvi'); - return getCommand('dvisvgm', base, options); + return getCommand('spix', dry, options, reference.getName()); } arguments: +- identifier: dry + flag: > + @{ + return isTrue(parameters.dry, '--dry-run'); + } - identifier: options flag: > @{ diff --git a/Master/texmf-dist/scripts/arara/rules/tex.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-tex.yaml index d036e5cb0dc..d036e5cb0dc 100644 --- a/Master/texmf-dist/scripts/arara/rules/tex.yaml +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-tex.yaml diff --git a/Master/texmf-dist/scripts/arara/rules/texcount.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-texcount.yaml index 694ac6d481b..85e26c42c6e 100644 --- a/Master/texmf-dist/scripts/arara/rules/texcount.yaml +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-texcount.yaml @@ -72,4 +72,3 @@ arguments: throwError('I was expecting a list of options.'); } } - diff --git a/Master/texmf-dist/scripts/arara/rules/texindy.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-texindy.yaml index 45c4637889c..6e27dfd90e8 100644 --- a/Master/texmf-dist/scripts/arara/rules/texindy.yaml +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-texindy.yaml @@ -13,9 +13,9 @@ commands: command: > @{ base = getBasename(reference.getName()); - infile = base.concat('.').concat(input); - outfile = [ '-o', base.concat('.').concat(output) ]; - logfile = [ '-t', base.concat('.').concat(log) ]; + infile = base.concat('.').concat(input[0]); + outfile = [ '-o', base.concat('.').concat(output[0]) ]; + logfile = [ '-t', base.concat('.').concat(log[0]) ]; return getCommand('texindy', quiet, markup, modules, codepage, language, logfile, outfile, options, infile); } diff --git a/Master/texmf-dist/scripts/arara/rules/tikzmake.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-tikzmake.yaml index 69e72c48852..69e72c48852 100644 --- a/Master/texmf-dist/scripts/arara/rules/tikzmake.yaml +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-tikzmake.yaml diff --git a/Master/texmf-dist/scripts/arara/rules/upbibtex.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-upbibtex.yaml index bb32250c6c6..bb32250c6c6 100644 --- a/Master/texmf-dist/scripts/arara/rules/upbibtex.yaml +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-upbibtex.yaml diff --git a/Master/texmf-dist/scripts/arara/rules/uplatex.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-uplatex.yaml index c2690d11052..18e2edb28e5 100644 --- a/Master/texmf-dist/scripts/arara/rules/uplatex.yaml +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-uplatex.yaml @@ -26,7 +26,7 @@ arguments: throwError('The valid branch values are: ' + engines.keySet()); } } - default: 'uplatex' + default: 'stable' - identifier: interaction flag: > @{ diff --git a/Master/texmf-dist/scripts/arara/rules/uptex.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-uptex.yaml index fb7a2282fdb..fb7a2282fdb 100644 --- a/Master/texmf-dist/scripts/arara/rules/uptex.yaml +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-uptex.yaml diff --git a/Master/texmf-dist/scripts/arara/rules/xdvipdfmx.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-xdvipdfmx.yaml index 6c569ef31c5..12c88da3298 100644 --- a/Master/texmf-dist/scripts/arara/rules/xdvipdfmx.yaml +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-xdvipdfmx.yaml @@ -12,20 +12,29 @@ commands: - name: The XDVIPDFMX program command: > @{ - infile = getBasename(reference.getName()).concat('.dvi'); - outfile = getBasename(output).concat('.pdf'); + infile = getBasename(reference.getName()). + concat('.').concat(entry[0]); + outfile = getBasename(output[0]).concat('.pdf'); return getCommand('xdvipdfmx', infile, '-o', outfile, options); } arguments: -- identifier: output +- identifier: entry flag: > @{ - parameters.output + if ([ 'dvi', 'xdv' ].contains(parameters.entry)) { + return parameters.entry; + } + else { + throwError('I was expecting either DVI or XDV.'); + } } - default: > + default: dvi +- identifier: output + flag: > @{ - reference.getName() + isEmpty(parameters.output, reference.getName(), parameters.output) } + default: '' - identifier: options flag: > @{ @@ -33,6 +42,6 @@ arguments: return parameters.options; } else { - throwError('I was expecting a list of options.') + throwError('I was expecting a list of options.'); } } diff --git a/Master/texmf-dist/scripts/arara/rules/xelatex.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-xelatex.yaml index 021f4cea6fd..f05da86dada 100644 --- a/Master/texmf-dist/scripts/arara/rules/xelatex.yaml +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-xelatex.yaml @@ -26,7 +26,7 @@ arguments: throwError('The valid branch values are: ' + engines.keySet()); } } - default: 'xelatex' + default: 'stable' - identifier: interaction flag: > @{ diff --git a/Master/texmf-dist/scripts/arara/rules/xetex.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-xetex.yaml index 687b08f200e..687b08f200e 100644 --- a/Master/texmf-dist/scripts/arara/rules/xetex.yaml +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-xetex.yaml diff --git a/Master/texmf-dist/scripts/arara/rules/xindex.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-xindex.yaml index 8ec73cf0688..26ade80d238 100644 --- a/Master/texmf-dist/scripts/arara/rules/xindex.yaml +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-xindex.yaml @@ -23,21 +23,15 @@ arguments: - identifier: config flag: > @{ - return [ '-c', parameters.config ]; - } - default: > - @{ - return [ '-c', 'cfg' ]; + return [ '-c', isEmpty(parameters.config, 'cfg', parameters.config) ]; } + default: '' - identifier: language flag: > @{ - return [ '-l', parameters.language ]; - } - default: > - @{ - return [ '-l', 'en' ]; + return [ '-l', isEmpty(parameters.language, 'en', parameters.language) ]; } + default: '' - identifier: options flag: > @{ diff --git a/Master/texmf-dist/scripts/arara/rules/xindy.yaml b/Master/texmf-dist/scripts/arara/rules/arara-rule-xindy.yaml index 161ae60158f..a55576c1f51 100644 --- a/Master/texmf-dist/scripts/arara/rules/xindy.yaml +++ b/Master/texmf-dist/scripts/arara/rules/arara-rule-xindy.yaml @@ -13,9 +13,9 @@ commands: command: > @{ base = getBasename(reference.getName()); - infile = base.concat('.').concat(input); - outfile = [ '-o', base.concat('.').concat(output) ]; - logfile = [ '-t', base.concat('.').concat(log) ]; + infile = base.concat('.').concat(input[0]); + outfile = [ '-o', base.concat('.').concat(output[0]) ]; + logfile = [ '-t', base.concat('.').concat(log[0]) ]; return getCommand('xindy', quiet, markup, modules, codepage, language, logfile, outfile, options, infile); } diff --git a/Master/texmf-dist/source/support/arara/arara-5.1.3-src.zip b/Master/texmf-dist/source/support/arara/arara-5.1.3-src.zip Binary files differdeleted file mode 100644 index 6a3830d644e..00000000000 --- a/Master/texmf-dist/source/support/arara/arara-5.1.3-src.zip +++ /dev/null diff --git a/Master/texmf-dist/source/support/arara/arara-6.0.0-src.zip b/Master/texmf-dist/source/support/arara/arara-6.0.0-src.zip Binary files differnew file mode 100644 index 00000000000..c097a34e733 --- /dev/null +++ b/Master/texmf-dist/source/support/arara/arara-6.0.0-src.zip |