SILE

• Index

Contents

• Fields
• Modules
• Data tables
• User input
• Core functions

Library

• SILE
• SILE.font
• SILE.settings
• SU
• SU.ast
• SU.numbers
• SU.sorting
• globals
• packages.bibtex.support.isodatetime

Interfaces

• classes
• inputters
• languages
• outputters
• packages
• pagebuilders
• shapers
• typesetters

Types

• color
• length
• measurement
• node
• unit

Modules

• classes.bible
• classes.book
• classes.diglot
• classes.docbook
• classes.jbook
• classes.jplain
• classes.letter
• classes.plain
• classes.tbook
• classes.tbook
• classes.tplain
• classes.triglot
• packages.pdf

Topics

• README

Module SILE

The core SILE library.

Depending on how SILE was loaded, everything in here will probably be available under a top level SILE global. Note that an additional global SU is typically available as an alias to SILE.utilities. Also some 3rd party Lua libraries are always made available in the global scope, see globals.

Fields

version	Machine friendly short-form version.
features	Status information about what options SILE was compiled with.
lua_version	ABI version of Lua VM.
lua_isjit	Whether or not Lua VM is a JIT compiler.
full_version	User friendly long-form version string.
quiet	Default to verbose mode, can be changed from the CLI or by libraries

Modules

utilities

Utilities module, typically accessed via SU alias.

Data tables

Commands	Stash of all Lua functions used to power typesetter commands.
Help	Short usage messages corresponding to typesetter commands.
debugFlags	List of currently enabled debug flags.
scratch	The wild-west of stash stuff.
documentState	Data storage for typesetter, frame, and class information.
rawHandlers	Callback functions for handling types of raw content.

User input

input

All user-provided input collected before beginning document processing.

Core functions

init()	Initialize a SILE instance.
use(module[, options[, reload=false]])	Multi-purpose loader to load and initialize modules.
process(ast)	Process content.
processString(doc[, format[, filename[, options]]])	Process an input string.
processFile(filename[, format[, options]])	Process an input file Opens a file, converts the contents to an AST, then runs process on it.
resolveFile(filename[, pathprefix])	Resolve relative file paths to identify absolute resources locations.
call(command[, options={}[, content]])	Execute a registered SILE command.
registerCommand(name, func[, help[, pack]])	(Deprecated) Register a function as a SILE command.
setCommandDefaults(command, options)	Wrap an existing command with new default options.
finish()	Finalize document processing Signals that all the SILE.process() calls have been made and SILE should move on to finish up the output 1.

Fields

version

Machine friendly short-form version. Semver, prefixed with "v", possible postfixed with ".r" followed by VCS version information.

• version string

features

Status information about what options SILE was compiled with.

Fields:

• appkit boolean
• font_variations boolean
• fontconfig boolean
• harfbuzz boolean
• icu boolean

lua_version

ABI version of Lua VM. For example may be "5.1" or "5.4" or others. Note that the ABI version for most LuaJIT implementations is 5.1.

• lua_version string

lua_isjit

Whether or not Lua VM is a JIT compiler.

full_version

User friendly long-form version string. For example may be "SILE v0.14.17 (Lua 5.4)".

• full_version string

quiet

Default to verbose mode, can be changed from the CLI or by libraries

Modules

utilities

Utilities module, typically accessed via SU alias.

See also:

SU

Data tables

Commands

Stash of all Lua functions used to power typesetter commands.

Help

Short usage messages corresponding to typesetter commands.

debugFlags

List of currently enabled debug flags. E.g. { typesetter = true, frames, true }.

scratch

The wild-west of stash stuff. No rules, just right (or usually wrong). Everything in here should be somewhere else, but lots of early SILE code relied on this as a global key/value store for various class, document, and package values. Since v0.14.0 with many core SILE components being instances of classes –and especially with each package having it's own variable namespace– there are almost always better places for things. This scratch space will eventually be completely deprecated, so don't put anything new in here and only use things in it if there are no other current alternatives.

documentState

Data storage for typesetter, frame, and class information. Current document class instances, node queues, and other "hot" data can be found here. As with SILE.scratch everything in here probably belongs elsewhere, but for now it is what it is.

Fields:

• documentClass table The instantiated document processing class.
• thisPageTemplate table The frameset used for the current page.
• paperSize table The current paper size.
• orgPaperSize table The original paper size if the current one is modified via packages.

rawHandlers

Callback functions for handling types of raw content. All registered handlers for raw content blocks have an entry in this table with the type as the key and the processing function as the value. @ table rawHandlers

User input

input

All user-provided input collected before beginning document processing. User input values, currently from CLI options, potentially all the inuts needed for a user to use a SILE-as-a-library version to produce documents programmatically.

Fields:

• filenames table Path names of file(s) intended for processing. Files are processed in the order provided. File types may be mixed of any formaat for which SILE has an inputter module.
• evaluates table List of strings to be evaluated as Lua code snippets before processing inputs.
• evaluateAfters table List of strings to be evaluated as Lua code snippets after processing inputs.
• uses table List of strings specifying module names (and optionally optionns) for modules to load before processing inputs. For example this accommodates loading inputter modules before any input of that type is encountered. Additionally it can be used to process a document using a document class other than the one specified in the document itself. Document class modules loaded here are instantiated after load, meaning the document will not be queried for a class at all.
• options table Extra document class options to set or override in addition to ones found in the first input document.

Core functions

init()

Initialize a SILE instance. Presumes CLI args have already been processed and/or library inputs are set.

1. If no backend has been loaded already (e.g. via --use) then assumes libtexpdf.
2. Loads and instantiates a shaper and outputter module appropriate for the chosen backend.
3. Instantiates a pagebuilder.
4. Starts a Lua profiler if the profile debug flag is set.
5. Instantiates a dependency tracker if we've been asked to write make dependencies.
6. Runs any code snippents passed with --eval.

Does not move on to processing input document(s).

use(module[, options[, reload=false]])

Multi-purpose loader to load and initialize modules. This is used to load and initialize core parts of SILE and also 3rd party modules. Module types supported bay be an inputter, outputer, shaper, typesetter, pagebuilder, or package.

Parameters:

• module string or table The module spec name to load (dot-separated, e.g. "packages.lorem") or a table with a module that has already been loaded.
• options table Startup options as key/value pairs passed to the module when initialized. (optional)
• reload boolean whether or not to reload a module that has been loaded and initialized before. (default false)

process(ast)

Process content. This is the main 'action' SILE does. Once input files are parsed into an abstract syntax tree, then we recursively iterate through the tree handling each item in the order encountered.

Parameters:

• ast table SILE content in abstract syntax tree format (a table of strings, functions, or more AST trees).

processString(doc[, format[, filename[, options]]])

Process an input string. First converts the string to an AST, then runs process on it.

Parameters:

• doc string Input string to be converted to SILE content.
• format nil or string The name of the formatter. If nil, defaults to using each intputter's auto detection. (optional)
• filename nil or string Pseudo filename to identify the content with, useful for error messages stack traces. (optional)
• options nil or table Options to pass to the inputter instance when instantiated. (optional)

processFile(filename[, format[, options]])

Process an input file Opens a file, converts the contents to an AST, then runs process on it. Roughly equivalent to listing the file as an input, but easier to embed in code.

Parameters:

• filename string Path of file to open string to be converted to SILE content.
• format nil or string The name of the formatter. If nil, defaults to using each intputter's auto detection. (optional)
• options nil or table Options to pass to the inputter instance when instantiated. (optional)

resolveFile(filename[, pathprefix])

Resolve relative file paths to identify absolute resources locations. Makes it possible to load resources from relative paths, relative to a document or project or SILE itself.

Parameters:

• filename string Name of file to find using the same order of precedence logic in require().
• pathprefix nil or string Optional prefix in which to look for if the file isn't found otherwise. (optional)

call(command[, options={}[, content]])

Execute a registered SILE command. Uses a function previously registered by any modules explicitly loaded by the user at runtime via --use, the SILE core, the document class, or any loaded package.

Parameters:

• command string Command name.
• options nil or table Options to pass to the command. (default {})
• content nil or table Any valid AST node to be processed by the command. (optional)

registerCommand(name, func[, help[, pack]])

(Deprecated) Register a function as a SILE command. Takes any Lua function and registers it for use as a SILE command (which will in turn be used to process any content nodes identified with the command name.

Note that alternative versions of this action are available as methods on document classes and packages. Those interfaces should be preferred to this global one.

Parameters:

• name string Name of cammand to register.
• func function Callback function to use as command handler.
• help nil or string User friendly short usage string for use in error messages, documentation, etc. (optional)
• pack nil or string Information identifying the module registering the command for use in error and usage messages. Usually auto-detected. (optional)

See also:

setCommandDefaults(command, options)

Wrap an existing command with new default options. Modifies an already registered SILE command with a new table of options to be used as default values any time it is called. Calling options still take precedence.

Parameters:

• command string Name of command to overwrite.
• options table Options to set as updated defaults.

finish()

Finalize document processing Signals that all the SILE.process() calls have been made and SILE should move on to finish up the output

1. Tells the document class to run its :finish() method. This method is typically responsible for calling the :finish() method of the outputter module in the appropriate sequence.
2. Closes out anything in active memory we don't need like font instances.
3. Evaluate any snippets in SILE.input.evalAfter table.
4. Stops logging dependencies and writes them to a makedepends file if requested.
5. Close out the Lua profiler if it was running.
6. Output version information if versions debug flag is set.