Version v0.14.0 of SILE has been released and is available for download! See the included CHANGELOG.md or review the commit history for more explicit details.

Summary of Improvements

Work to refactor SILE's internals into a more regular API has been in progress for some time. This release brings a big chunk of that work to light. Many/most of the changes are under the hood and won't show up in the appearance of documents. They do affect anybody writing classes or packages for SILE, hopefully for the better.

Most notably, 3rd party modules have much more robust support. A module may be a class, a package, a typesetter, a shapper, an inputter, an outputter, etc. This makes it easy for developers to extend SILE without needing to modify the core distribution. Modules can be packaged and installed using LuaRocks. LuaRocks.org may be used to host and distribute SILE addons. Rocks may also be distrusted independently. Either way they are easy to install with luarocks install and such installs will make the modules available for loading into SILE. The old built in package manager is still functional for now but deprecated.

The ergonomics of packages has changed a little. The overloaded \script command has gained some more specialized peers. For example Lua code may be passed in \lua commands. To load a package or other module, use \use[module=package.name]. This syntax also allows passing options to modules.

The inputters have been normalized a bit, and XML, SIL, and Lua are all first class input languages. Passing some content in XML format from a SIL format document is as easy as placing it in an \xml command. The same goes for SIL format content in an XML document.

3rd party developers may add new input formats as well! All that is required is an inputter module that returns an AST. Expect to see new inputters soon. Didier Willis has already been working on a new Markdown inputter module. Other XML based formats such Docbook have been supported for a while, but the new class and inputter APIs make them easier to add and use.

The CLI has gained several new options. As usual sile --help and man sile both have relevant information. Notably the -I/--include argument has been deprecated in favor of more explicit -u/--use, -p/--preamble, and -P/--postamble. As you might expect from those options this makes it possible to load an inputter, class, or package from the command line without having it set in the document. The preamble/postamble system has been cleaned up so content or code can easily be injected at the start or end of a document. This is a change from the previous 'preamble' system that actually became the master document and then included the original master as effectively a postamble.

Many old shims and deprecated functions have been completely removed. Most will still throw relevant warning messages with hints about how to update.

While I was busy moving cheese, several contributers were chipping in new features and fixes. Rolf Marvin Bøe Lindgren pitched in Norwegian localization and improved hyphenation. Mattéo Delabre contributed quite a few new features and fixes to the math package. Didier Willis did some data mining and came up with localization strings for a whole slew of languages. He also pitched in fixes to a number of packages. He also has pending contribution for many new packages and features. Be sure to checkout the PR scene on GitHub if you are looking for new features.

⚠ BREAKING CHANGES

• packages: The primary use was probably internal to SILE, but if by chance you have bibtex databases with formatting commands in SIL markup format rather than just plain text content the markup will cease to function and will need to be converted to XML syntax instead.

  This enables the use of declarative markup in Fluent localizations.

• classes: Each SILE package now inherits some interfaces from a common base package. This model allows packages easier access to SILE internals while at the same time tracking what they do so it is easier to enable/disable them. The package knows which document class instance it is attached to, and the document class knows which packages are loaded at any given time. Legacy style packages will continue to work for the time being but will not be tracked in the same way.

• core: The role of document commands has always been tightly scoped to classes. For example the book class has a \footnote command while plain does not—unless you manually load the package and setup the frames. In spite of this obvious functional scope, registering commands has been a global operation that stored them in a global registry. In order to allow SILE to be used more programmatically as a library with potentially more than one document and class being processed at at once, these need to be moved out of the global scope. This will also facilitate things like being able unload packages and revert to previous functionality for anything they over-rood on load. For now the functionality is shimmed, but code using the SILE.registerCommand() function should switch to the method of the same name on the current class, i.e. class:registerCommand().

• core: Some internal files and APIs got renamed with more structured name spaces. In particular the inputter, shaper, and outputter libraries all have a common naming scheme now and sensible inheritance chains. No functionality was harmed, but if you are overriding undocumented internal Lua methods you might have to update your name spaces to match.

• cli: The -I / --include option was overloaded for more than one purpose and is now deprecated in favor of more specific replacements: -r / --require for loading code into SILE before input processing, -p / --preamble for processing content prior to a document and -P / --postamble for processing content after a document.

• packages: The original package manager POC that used Git to clone packages into the SILE installation directory has been deprecated. It will continue to function for a while, but all new 3rd party packages should use the LuaRocks based installation process. Whether or not they use luarocks as a package manager or LuaRocks.org as a distribution channel they should install themselves to any usable the system or user Lua library path under a top level "sile" namespace.

• classes: The shims allowing classes designed for SILE releases v0.12.x and prior have now been removed and documents using them will now throw errors when rendering. Only the refactored class system introduced in SILE v0.13.0 is supported going forward.

• deps: We previously deprecated all use of stdlib. This release stops providing it entirely. If you use it in your own projects you will now need to provide and require() it directly.

• build: The C modules compiled as shared libraries (.so files on Linux, .dll on Windows) are now installed to the project root shared directory instead of it's 'core' subdirectory. Distro packages that split the library into its own package will need to adjust this path. People installing from their distro packages or from source should be unaffected, but this will bring us one step closer to being able to install and use SILE as a library.

Features

• classes: Add \use command to help deconflate \script usage (eb298c3)
• classes: Track loaded packages per document class (32bd87b)
• cli: Add CLI argument -E for evaluating Lua code after input (5948aca)
• cli: Add usage hints and cleanup output of errors (cc58824)
• cli: Allow loading custom inputters from -r option (a212e83)
• cli: Allow passing options to any modules specified from --use (4cdcae7)
• cli: Change --require to --use to match declarative markup (2411328)
• core: Add ability to pass args to modules via \use and other commands that load modules (9e54bad)
• core: Add ability to pass args to modules via \use and other commands that load modules (e64ce0f)
• core: Add inline-escaping in SIL-language (f09b135)
• core: Support loading classes/packages installed with luarocks (232e72b)
• i18n: Add more Russion localizations (350cf14)
• i18n: Add support for as many languages as possible (da57577)
• i18n: Fallback to messages from 'und' language if no localized (9f47715)
• i18n: Parse XML style SILE commands in Fluent messages (989290b)
• inputters: Allow arbitrary root elements from XML input without a preamble (ad46a92)
• inputters: Allow CLI to mandate inputter used for master document (1b9009f)
• inputters: Promote Lua to first class input filetype, improve input type detection (3540943)
• languages: Add Norwegian localizations (76b8f84)
• languages: Add Norwegian Nynorsk hyphenation exceptions (520cd3f)
• languages: Handle 'nb' code for Norwegian Bokmål, linked to 'no' rules (373bd17)
• math: Add modulus operator support (429b162)
• math: Allow forcing the atom type of an operator (14d384c)
• math: Express lengths in “mu” (math units) (39c7efc)
• math: Macros no longer wrap their replacement into s (d1f24b3)
• math: Print resulting mbox tree to debug log (f2e7c33)
• math: Support relative units in spaces and add standard spaces (4f2bee2)
• packages: Add new method to export package functions to class (07a28a4)
• packages: Allow configuring target folio frame from options (74e3924)
• packages: Provide API for registering commands linked to packages (4875972)

Bug Fixes

• build: Update Flake to work with Nix >= 2.10 (effb0dc)
• classes: Reset default font direction if document direction changed (11bb0f9)
• cli: Avoid throwing extra error on error without message (0d530a5)
• core: Avoid error when outputting overflow warnings with specific measurements (49ef650), closes #945
• debug: Flatten content if necessary to process and debug location (c753bd2)
• debug: Re-implement option display in trace stacks lost with std (01d2379)
• inputs: Drop Lua path handling duplicated in core (8abb0f2)
• math: Fix caching of getMathMetrics (3332698)
• math: Fix debug logs in TeX-like parsing (a686f90)
• math: Fix spacing before integral operators (bc847b3)
• math: Fix tostring functions in mbox subclasses (7a7c6bc)
• math: Set math elements to inherit hbox node properties (0279556)
• math: Turn font name printing into debug log (068ec4b)
• outputter: Non-RGB colors shall work with the debug outputter (#1469) (e68dee3)
• packages: Correct URL formatting when backend is not libpdftex (fc4212d)
• packages: Ensure grid hook is ineffective when grid is off (b99482b), closes /github.com/sile-typesetter/sile/issues/1174#issuecomment-1173141699
• packages: Make \script command properly initialize packages (#1479) (9723d0d)
• packages: Parse height argument to \raise / \lower as measurement (#1506) (7196fda)
• packages: Stop legacy package manager from adding empty paths (cf9b9fa)
• packages: Stricter color parsing and improved color documentation (f7b919a)
• packages: The autodoc package could choke on some inputs (#1491) (c7db5d5)
• utilities: Correct traceback output for SILE.error() to show parent, not itself (16b8900)

Miscellaneous Chores

• build: Move C modules to same relative location in source directory as installed (55ad795)
• classes: Remove stdlib class shims (c4210da)
• cli: Deprecate CLI argument -I in favor of -r, -p, and -P (d63a484)
• deps: Stop providing Lua stdlib (8a8c0e9)
• packages: Deprecate legacy package manager (b72653c)

Code Refactoring

• core: Move inputters/shapers/outputters to isolated classes (14329ce)

• core: Move registerCommand() out of global to classes (bc527ea)

• packages: Process bibtex content as XML not SIL (a259b32)