Skip to content
Omikhleia edited this page Jun 29, 2024 · 5 revisions

The SILE FAQ

Questions about SILE

SILE and TeX

So, is this, like, the new TeX? A rewrite of TeX? Better than TeX?

No. Forget TeX. We only mention TeX because that's the easiest way to explain to people what a typesetting engine is. SILE is a typesetting engine. It uses some of TeX's algorithms because they are the best way we know of to get computers to typeset. But it's not TeX.

But if I have TeX, why would I want this?

The first thing that should be said is that if TeX works for you, use TeX. We don't see the need to take over the world. TeX has a lot of benefits including decades of work, community building and the CTAN code repository. TeX is great.

But there are some things where TeX doesn't do what you want, and since SILE is written in Lua, an interpreted language, it gives you the ability to make substantial changes to the underlying typesetting algorithms.

For document class and package authors, it also gives you the ability to write your class and formatting code in a high-level language, instead of grubbing around in TeX's macro language.

If you've never had to write a LaTeX package yourself, you probably won't find SILE interesting. And that's OK.

But I can do those things with LuaTeX, right?

To a certain degree, yes, but whereas LuaTeX provides you with certain hooks to interact with certain parts of the system, the whole of the SILE typesetter is written in Lua and so can be interacted with. As an example, typesetting on a grid in TeX is a hard problem (ConTeXt solves some of it reasonably well, but will not give you flowed frame support) but it is a very simple package to implement in SILE.

The other compelling two features of SILE are its support for complex frame-based layouts - you can change how a page is laid out on the fly, creating columns, frames, insertions and so on - and the decoupling of the input format from the typesetting process; (you can't read TeX files without processing the macros) the practical effect of which is that you can feed SILE XML files and it will process them.

SILE and mathematics

Does it support mathematics?

Yes, both in TeX-like format and in (as a subset of) MathML, although not all possible mathematical notations are implemented yet. See the documentation of the math package in the manual for more information.

SILE and input formats

So I must learn a custom/proprietary language for typesetting with SILE?

Not necessarily.

The default SILE distribution includes an input language known as "SIL," which actually comes in two different "flavors":

  • The "TeX-like" SIL syntax flavor, loosely inspired by LaTeX but with notable deviations and different design choices.
  • The "XML" SIL syntax flavor, presented in XML format (obviously) for direct processing.

It is true that SIL is a proprietary language. If you want, say, to emphasize some text, you would use \em{...} (in TeX-like SIL flavor) or <em>...</em> (in XML syntax)...

But wait! SILE actually supports other input formats, and 3rd-party packages can also add their own input formats. Thus, SILE is quite versatile and not tied to the default SIL syntax.

Which XML schemas are supported?

Well, arbitrary XML content may be processed with appropriate package support. It sounds easy when put in those terms, and it is quite true. But of course, most XML document formats are fairly large and complex specifications. Thus, implementing support for them may not be as straightforward as it initially appears.

Yet, the SILE distribution includes support for (a subset of) the DocBook specification. There are also existing 3rd-party packages providing support for other XML schemas, such as:

  • Specific subsets of the TEI specifications,
  • USX Unified Scripture XML.

Can I rather use a simpler lightweight markup language?

Absolutely! SILE is flexible and can be extended to support other markup languages, beyond XML.

For instance, there is a 3rd-party collection of modules for Markdown and Djot. Additionally, other third-party components enable support for other input formats, such as a YAML-based "master document" format.

SILE and output formats

Can I go from SILE to HTML/EPUB/etc.?

Electronic publishing is definitely the way of the future, so this is an important question. It's certainly possible to create a package which replaces the print "outputter" with something which emits HTML instead of PDF. (It would probably need lots of monkey-patching into the insertion/headers/etc. classes too.)

But it would be like drilling a hole with a screwdriver. SILE is designed to implement the print part of production workflow; if you have a SILE document which needs to be transformed for electronic publishing, then something has probably gone wrong somewhere. Redesign your workflow so that you are authoring in a format that can be converted to HTML/EPUB, and then write SILE classes for that format.

So can I go from HTML/EPUB to print?

There aren't classes for HTML/EPUB at the moment, and partly that's because I don't need them. It would not be hard to base something off the existing DocBook classes to cover the HTML element set. The biggest problem (as with all open source projects) is user expectation management - people would call you names if you didn't implement CSS, and the CSS Print Extensions, and there would be no end of it.

SILE and Lua

Why Lua?

We wanted an interpreted language to allow for modifying the internals on the fly. Initial drafts were done in JavaScript (and this can still be found in the repository history!) but Lua allowed for easier interface with external shaping and output libraries, and of course the fact that there is already a community of people messing about with typesetting in Lua is quite helpful.

Questions on "ugly" output

Some lines are overflowing my page margin!

Sometimes, a line cannot be broken in a way that would fit the line width, and overflows the margin (i.e. right margin in LTR writing systems).

It is a common issue, especially with small line/column widths, and long words.

The standard line breaking algorithm in SILE is based on the constraints-based Knuth-Plass algorithm. Overflows occur when a line cannot be adjusted within the defined constraints.

Depending on the language, suitable hyphenation points are not always available. In the classical scenario, the only elements that can shrink or stretch are the spaces.

Sometimes, this issue is caused by an unknown or foreign word.

  • Switching to a language with appropriate hyphenation patterns can help.
  • Adding hyphenation patterns can also help: \hyphenator:add-exceptions{lower-case-word}

Most of the time, the only solution is to allow more stretching and shrinking, by relaxing some constraints.

Several parameters control the line breaking algorithm. This includes:

  • linebreak.tolerance (default: 500)
  • linebreak.emergencyStretch (default: disabled)

So you can try setting the tolerance to 1000 or 2000, and/or enabling the emergency stretch.

\set[parameter=linebreak.emergencyStretch,value=1em]
\set[parameter=linebreak.tolerance,value=2000]

the emergency stretch is applied only when the line would otherwise have failed to be within the tolerance, so it often gives better results. The tolerance is global, applied to all lines in a paragraph, so it is better to keep it unchanged, unless you have no other choice.

Refer to the SILE manual for more details on the line breaking algorithm and its parameters. Happy tuning!

The space between lines is inconsistent!

Yes; I bet you never noticed that TeX does this too. Spacing between lines is governed by the descenders in the upper line, the value of the baselineskip and lineskip parameters, and the stretch value of the parskip parameter. If you want consistent interline spacing, you could set parskip's stretch component to zero; you could also try turning on grid typesetting.

Clone this wiki locally