All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project tries to adhere to Semantic Versioning from version 5.0.0 on.

Important: This CHANGELOG documents the technical nature of changes. While it is written for users, it does not attempt to provide migration guides. For these, please read the announcement blog posts on our website at https://islandoftex.gitlab.io/arara/news/.

Unreleased

7.1.5 - 2024-05-06

Fixed

• arara failed to run on Windows, macOS and Linux on certain JVM versions due to a wrong method call. (see #124)

7.1.4 - 2024-05-02

Added

• A new pdftocairo rule to convert pdf's into various formats (thanks to @samcarter). (see !57)

Fixed

• Documentation for imagemagick options (thanks to @samcarter). (see !58)

7.1.3 - 2024-02-13

Added

• A new rmdir rule to remove directories (thanks to @hackbaellchen). (see !53)

7.1.2 - 2023-10-01

Fixed

• arara failed to run on Windows, fixed by including JNA classes into the JAR (thanks to @hackbaellchen). (see #119)

7.1.1 - 2023-09-29

Fixed

• arara would raise an error when running on Java 21. (see #118)

7.1.0 - 2023-05-05

Added

• A new mkdir rule to create directories (thanks to @hackbaellchen). (see !48)
• The MPPPath public API has been extended with a new method: createDirectories which creates a directory and all relevant parents at the current path. It can be used in rules by going through toFile(file).createDirectories() access.

Fixed

• Copyright dates have been outdated throughout the codebase. (see #108)

7.0.5 - 2023-04-17

Fixed

• Various typos and style issues in the documentation (PDF and website). Thanks to @muzimuzhi for spotting and fixing most of these. (see !38, !39, !40, !43, !44, !46, #100, #102)
• A vulnerable (but in arara not realistically dangerous) log4j version caused errors in some screening tools and has been updated. (see #107)

7.0.4 - 2022-06-28

Fixed

• copy and move rules were fixed to properly normalise relative paths. (see #91)

7.0.3 - 2022-05-12

Fixed

• arara did not use the correct file separator on Windows. (see #84)

7.0.2 - 2022-05-05

Fixed

• arara used Java File objects in rules instead of the new path API in nearly all cases except when using the files parameter. It is now again compliant with documented behavior and rules have been adjusted.

7.0.1 - 2022-05-03

Fixed

• arara failed to load rules on Windows due to path problems when resolving the application's path. (see #83)
• CTAN demands source files for the PDF which we did not provide since having the HTML-based PDF. Now they are included.
• The CTAN zip missed the sources for the Lua DSL component.

7.0.0 - 2022-05-01

Added

• arara now accepts .lua files as input files. These are treated as project specification and will let arara run all files specified in the project(s). When run as arara project.yaml you cannot run on multiple files. If you run Lua files with arara directives they will continue to work as before. (see #11)

Changed

• The MVEL API now uses our MPPPath object instead of java.io.File. That way we are in control of the actual methods called which makes maintenance easier. There are substitutes for the most common file operations. Users of the toFile() method are safe as this is properly casted. (breaking change)
• The error message for IO errors has been changed to indicate potential encoding problems. (see #68)
• Use header-mode by default instead of scanning the whole document for directives. The -H flag has been removed, to get the old behavior back use arara -w. This change is experimental, and we might return to the old behavior based on user feedback. (see #63; breaking change)
• arara's manual is now built from the markdown sources powering the website using the weasyprint converter. Hence, all TeX files related to documentation and quickstart guide have been removed from the repository. (see #60)

Fixed

• The manual on the website now offers scrolling on long table of contents. (see #80)

6.1.7 - 2022-04-16

Added

• Documentation is now available on arara's homepage in addition to the PDF manual.

Changed

• xelatex and xetex rules were updated to include the unsafe execution branch. (see #79)

Fixed

• Fix shell script permissions for CTAN-distributed shell scripts.

6.1.6 - 2022-02-27

Changed

• Updated dependencies.

6.1.5 - 2021-12-21

Fixed

• Fix shipping a vulnerable log4j version. (see #78)

6.1.4 - 2021-12-14

Fixed

• Fix shipping a vulnerable log4j version. (see #77)

6.1.3 - 2021-11-17

Fixed

• The indent rule did not honour subdirectories. Only file names were used (paths were stripped) and thus the system command failed on such scenarios. (see #76)

6.1.2 - 2021-10-17

Added

• The indent rule was updated to include three new switches. (see #73)

6.1.1 - 2021-06-26

Changed

• Updated dependencies.

Fixed

• The arara logo has been printed into the completion script output. This caused failures when sourcing directly. The logo has been removed from the completion script output. (see #70)
• Configuration files have been loaded after files have been resolved which conflicts with the configuration options for file resolution. (see #71)

6.1.0 - 2021-04-04

Added

• The CLI now supports generating shell completions for bash, zsh and fish using --generate-completions.

Fixed

• arara would raise a null pointer exception when running from the root directory in the underlying file system hierarchy. (see #69)

6.0.2 - 2021-03-31

Fixed

• The clean rule did not use the list size property as required by v6. (see https://chat.stackexchange.com/transcript/message/57489291#57489291)
• Documentation for Pair now refers to its values as first and second property accessors.

6.0.1 - 2021-03-30

Added

• The quickstart guide has been integrated in the website as a first step towards providing web based documentation.

Fixed

• The help message did not mention the tool's purpose. (see #65)
• The makeindex rule did not use the list access syntax as required by v6. (see https://chat.stackexchange.com/transcript/message/57484552#57484552)

6.0.0 - 2021-02-26

Added

• arara now features an API and a library to ease developing an own TeX compilation workflow.
• The new command line parameter -P allows specifying command-line options to be passed to arara's session map. In a rule, you may now retrieve value by calling getSession().get('arg:key') if you called arara with arara -P key=value myfile.tex. (see #38)
• Configuration files now honor an option defaultPreamble which 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 meaning preambles from local configurations will take precedence over global preambles. (see #55)
• The new configuration option prependPreambleIfDirectivesGiven allows you to specify a boolean value indicating whether preambles should be applied to all files or only those without directives. It defaults to true to avoid breaking existing workflows.
• arara now expands @{} orb tags within options parameter to directives. Supported methods are getBasename, getSession and getOriginalReference with their documented meanings. (see #38, #46)
• The methods above (getBasename, getSession and getOriginalReference) have also been added to the conditional context, i.e. you may use them in conditional expressions in directives.
• A new safe mode (-S or --safe-run) protects the system by disallowing certain user actions. (see #18) Currently, the following features are restricted:
  • file lookup will only perform explicit file resolution
  • unsafelyExecuteSystemCommand will raise an exception and abort the run (although rules are still allowed to construct arbitrary commands using a return getCommand(…) approach so this only disallows arbitrary system commands that would not get logged and are thus invisible to the user)
  • the options parameter does not expand orb tags in any directive.
• -dev formats are now available within the latexmk rule. (see #48)
• The rule context has now a getOrNull(…) method, which attempts to retrieve a list element based on an index (default is zero). If the index is out of bounds, a null value is returned instead.
• Multiple rules have been added. Most of them are untested and we are open for feedback and enhancements: ghostscript, copy, move, ltx2any, llmk, spix, pdfcrop, sage. (see #47 and https://github.com/cereda/arara/issues/83)
• A new quickstart guide has been written to complement to the reference manual. (see #9 and #59)
• A new website at https://islandoftex.gitlab.io/arara/ presents arara briefly and is to be extended with future releases.

Changed

• arara is now split into an API, a core implementation (library) and the implementation of the executable (cli). Projects relying on code in the arara JAR distributions have to be updated. (breaking change)
• 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 (see deprecation notice in v5). (see #32)
• Languages have to be passed as IETF BCP 47 codes. The old system has been removed. Hence, please use en-QN instead of qn etc.
• Localization is provided by classes as library instead of property files in arara's resources.
• 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 a helper tool's (that is what arara is) output was considered inappropriate. (breaking change)
• The log file may now be specified as path anywhere on the file system. Warning: This behavior may be altered for a future safe mode. (see https://github.com/cereda/arara/issues/133).
• The method signatures of loadObject and loadClass have been altered to return a Pair<ClassLoading.ClassLoadingStatus, Object> instead of a Pair<Integer, Object>. You can now access the status values as enumeration.
• The implementation of methods available within rules has been moved to Kotlin causing null values to be handled differently. Previously undefined behavior will now cause an error. (breaking change)
• Preambles are now a client-only feature. This feature will neither make it to core nor to the mvel library because libraries should not deal with prepending content to a file which is what the preambles feature does.
• All flags are consistently transformed into a List<String>. If a List is returned, it will be flattened and all values will be turned into string. If a string is returned, a single list with only that string will be returned. Other values are not encouraged but if returned transformed into a string. If you need interoperability of complex command code with older versions, use isList(variable) ? variable[0] : variable to get the value of previously non-List values. (breaking change)
• default values now are treated as values like user input. This means, no orb tags are interpreted within this field anymore. The default value will be processed by the flag if specified, just as user input would be. If no flag is present, it will be returned as a (list of; cf. previous item) string. Previous rules have to be rewritten if they make use of orb tags. (breaking change)
• The dvisvgm rule now supports dvi, xdv, eps and pdf extensions as input, as well as the inclusion of a page range. (see #53)
• The xdvipdfmx rule now supports both dvi and xdv extensions as input. (see #53)

Fixed

• The exit status handling now conforms to the documentation. We only differentiate the exit values 0, 1 and 2 as detailed in the docs.
• The correct behavior of currentFile and getOriginalReference has been restored as version 5 incorrectly used the same object for both. (see #45)

Removed

• Removed the <arara> shorthand notation which has been deprecated in version 5.0.0. (see #26; breaking change)

5.1.3 - 2020-04-23

Added

• New rule for the authorindex package/perl script). (see this StackExchange post)

Fixed

• In version 5.1.2, we introduced a different loading order for configuration files. This has fixed the loading of preambles but broke the loading of other settings. We accounted for that in v5.1.3. (see #44)

5.1.2 - 2020-04-19

Added

• New rules for PythonTeX and PerlTeX have been added on user request. (see #42)

Fixed

• The configuration file has been loaded too late. That's why preambles did not work any longer. (see #43)

5.1.1 - 2020-04-14

Fixed

• TeX-related rules were updated to use reference.getName() instead of reference due to some issues when using absolute paths.

5.1.0 - 2020-04-03

Added

• New rules for ConTeXt, fig2dev, qpdf, convert, texcount and detex. (see #10)

Fixed

• unsafelyExecuteSystemCommand failed to execute in the current directory.

5.0.2 - 2020-03-07

Fixed

• Running arara failed on Windows due to wrong path encodings. (see #35)

5.0.1 - 2020-03-05

Changed

• The CI builds now produce a CTAN-ready zip file instead of running the documentation build separately

Fixed

• Multiple rules did use a file reference where it should have used reference instead.
• Documentation still mentioned file although it should have been marked removed since version 5.0.0.

5.0.0 - 2020-03-03

Added

• Working directory support has been added. Users may now specify their working directory by passing a command-line option. (see #13)
• arara features support for processing multiple files. Prerequisite: They are located within the same working directory.
• The most important update release notes are shown when calling arara with the version flag. (see #25)
• Multiple rules have been added. All of them are untested and we are open for feedback and enhancements: asymptote, luahbtex, metapost, pbibtex, platex, ptex, upbibtex, uplatex, uptex, xindex. (see #10)

Changed

• The build process is now based on Gradle instead of Maven. This includes new tasks providing all necessary tooling to create CTAN uploads. (see #8)
• The application has been rewritten in Kotlin and the code has been streamlined to its use cases. That includes we now run a test suite (which is far from exhaustive).
• The application is now hosted on GitLab. From now on, support will be provided there.
• The file lookup now performs an additional lookup step. File names ending on a period will ignore the period (use case: command-line completion by various shells) in the second lookup. So arara file. will resolve file..tex etc. first and then (if no luck yet) try to resolve file.tex.
• arara does not use a XML database anymore. File changes are recorded in a YAML database instead.
• The biber rule is now aware of the biber option tool. (see https://github.com/cereda/arara/issues/136)

Deprecated

• The <arara> shorthand notation will be removed in the next major release. (see #26)
• The file names of distributed rules being public should not be relied upon anymore because there are plans to rename them. (see #32)

Removed

• Removed triggers and introduced session namespaces as a replacement (see #15, #2, #17; breaking change)
• Removed velocity and with it all support for templating languages for now. It is not planned to reintroduce such a dependency to the core. But rules supporting templating tools are welcome. (see #8; breaking change)
• Removed string-based commands. Guessing the intention of a string is a strong kind of opinionating syntax which will not be followed further. (see #2; breaking change)
• Removed support for user.dir; no lookup will be performed on this variable. (see #16; breaking change)
• Removed auxiliary tools such as the separate CTAN packager, language checker and rule converter. They have been merged into the test suite or build process or lost relevance.
• Removed file reference. The replacement reference is correctly typed and available since version 4.0.

Fixed

• unsafelyExecuteSystemCommand now respects getCommandWithWorkingDirectory (previously, working directories have been ignored; see #21).

4.0.0 - 2018-07-10

Added

• Support for multiline directives was added.
• The exit status checking can be adjusted.
• Partial directive extraction mode has been added (only scan until the first non-comment line is encountered).
• The user may define preambles to share common preambles between files that require the same compilation setup.
• Support for running code from class and jar files has been added.
• Commands and Triggers have been introduced as abstraction layers.

Changed

• arara follows a REPL workflow (rule evaluation on demand as opposed to prior to execution).
• The rule format has been reworked, e.g. command has become commands (breaking change).
• The lookup strategy for configuration files has been altered and extended.

Deprecated

• String-based commands require guesswork and opinionated syntax. Hence, they will be removed in version 5.0.

Removed

• Cross-platform installers have been retired. arara is available in all major TeX distributions.

3.0 - 2013-02-07

Added

• Localized messages in English, Brazilian Portuguese, German, Italian, Spanish, French, Turkish and Russian.
• Friendly and very detailed messages instead of generic ones.
• An optional configuration file is now available in order to customize and enhance the application behaviour.
• Now rules are unified in a plain format. No more compiled rules.
• Rules can allow an arbitrary number of commands instead of just one.
• Built-in functions in the rule context to ease the writing process.

Fixed

• Improved error analysis for rules and directives.
• Improved rule syntax, new keys added.
• Improved expansion mechanism.

2.0 - 2012-07-24

Added

• Added the --timeout n flag to allow setting a timeout for every task. If the timeout is reached before the task ends, arara will kill it and interrupt the processing. The n value is expressed in milliseconds.
• There's no need of noninteractive commands anymore. arara can now handle user input through the --verbose tag. If the flag is not set and the command requires user interaction, the task execution is interrupted.
• Added the @{SystemUtils} orb tag to provide specific operating system checks. The orb tag maps the SystemUtils class from the amazing Apache Commons Lang library and all of its methods and properties.

Fixed

• Fixed the --verbose flag to behave as a realtime output.
• Fixed the execution of some script-based system commands to ensure cross-platform compatibility.

1.0.1 - 2012-04-24

Added

• Added support for .tex, .dtx and .ltx files. When no extension is provided, arara will automatically look for these extensions in this specific order.
• Added the --verbose flag to allow printing the complete log in the terminal. A short -v tag is also available. Both stdout and stderr are printed.
• Fixed exit status when an exception is thrown. Now arara also returns a non-zero exit status when something wrong happened. Note that this behaviour happens only when arara is processing a file.

1.0 - 2012-04-24

• Initial release

For versions previous to version 5.0.0, there has not been any persistent record of changes. Please refer to the commit history for details.