Introduction

Welcome to the SpanDeX book. This book serves as a tutorial for SpanDeX.

What is SpanDeX?

SpanDeX is a modern alternative to LaTeX, carefully designed to be:

ultra performant, allowing lightning fast compilation and hot reloading with optimized algorithms;
simple, avoiding the need for users to learn a complex language before being able to do basic things;
easy to debug, not reproducing the tons of useless stuff LaTeX vomits every time something goes wrong and making it a breeze to find and fix simple mistakes.

Main TeX's pitfalls being worked on

Overall, SpanDeX aims at taking advantage of TeX's strengths while proposing novel approaches where it performs poorly. The core idea behind SpanDeX is to build things in a way that will allow the engine to take smarter decisions at every step.

TeX's opaque syntax

While nearly every academic paper involving some level of math is written in TeX and people became accustomed to it, its syntax can be quite a challenge to grasp for the newcomer.

For instance, though it's pretty straightforward to typeset basic paragraphs and titles in TeX, it becomes extremely unhandy and clogged up with avoidable stuff as soon as you'd like to stylize your document somewhat.

DeX proposes to instead invest on what's been done with the most recent languages that aim at being minimalistic while remaining explicit and easy to remember.

TeX's unability to typeset paragraphs in a fully context aware manner

TeX does not keep track of where it is when it tries typesetting paragraphs. This makes it nearly impossible to implement somewhat complicated layouts in a straightforward way. Moreover, this prevents TeX's core typesetting algorithm from having the opportunity to take smarter decisions when breaking down paragraphs into lines, /e.g/ to avoid orphans and widows.

SpanDeX implements a novel approach based on the concept of layouts. In this paradigm, a paragraph "typesets itself" inside of a layout that tells the paragraph where it is and where it can go next. This gives the paragraph the possibility to make smart decisions and even go back, if necessary. Being context-dependent, this approach also unveils opportunities for improved caching and thus, performance.

It then becomes extremely simple to define and configure arbitrary layouts, dissect them into columns, etc.

WIP

This project is still very recent, and very (very) few functionnalities are supported. This is not production ready in any way, it's simply here if you want to have fun and play around.

API documentation

The API documentation is available here.

Source code

The source code is available on GitHub.

Getting started

The few next sections will guide you through the following things:

installing SpanDeX and its dependencies
starting a SpanDeX project and compiling it

Installing SpanDeX

SpanDeX is not (yet) tested on any other operating system other than Linux based.

Install rust

The first thing you need to do in order to run SpanDeX is to install rust. If you're on a Linux based system, it should be as simple as running

curl -sSf https://sh.rustup.rs | sh

in a terminal and answer the few questions that will be prompted.

If you're on another operating system, we invite you to read rust's documentation to find out the best way of installing rust on your computer.

Install SpanDeX

If you have successfully installed rust, you should be able to install SpanDeX by simply running

cargo install --git https://github.com/tforgione/spandex -f

You can run this command again to update SpanDeX to the latest version.

Creating a basic SpanDeX project

There are two ways of creating a SpanDeX project:

either you want to create it in a new directory, in which case you can run
```
spandex init <project_name>
```
or you already have in directory that you want to setup for a SpanDeX project, in which case you can simply run
```
spandex init
```

This will generate the default configuration file spandex.toml and an initial main.dex file.

To compile your files into a PDF, you can simply run

spandex build

SpanDeX syntax

The syntax of DeX is inspired by Markdown and, to a lesser extent, by elm-markup.

Paragraphs

In DeX, paragraphs are content that are not titles and that are separated by an empty line.

This is a paragraph.
This is still the same paragraph.

This is a new paragraph.

Titles

Titles are declared by prepending a line with #, just like Markdown.

For example, you may make titles and subtitles like so:

# My title

## My subtitle

In DeX, however, you need to leave an empty line following a title.

If you try to compile this

# My title
## My subtitle

the compiler will crash giving the following ouptut:

error: titles must be followed by an empty line
 --> main.dex:2:1
  |
2 | ## My subtitle
  | ^ expected empty line here
  |

Inline

Like many markup languages, DeX has inline elements that allow you to typeset your content. Inline elements cannot spread accross different paragraphs. If you want to do that, you will have to end your inline at the end of your paragraph, and start it again at the begining of the next one.

Bold

To put some content in bold, you need to put it between stars (*). For example, you can do:

This is a *strong* element.

As described previously, trying to spread an inline over different paragaphs won't work, and the compiler will give an error saying that you haven't closed your inline tag. For example, the following code

Hello *you

how* are you?

will give the following errors:

error: unmatched *
 --> main.dex:1:7
  |
1 | Hello *you
  |       ^ bold content starts here but never ends
  |
error: unmatched *
 --> main.dex:3:4
  |
3 | how* are you?
  |    ^ bold content starts here but never ends
  |

However, since pargraphs can spread over multiple lines, you can totally do the following:

Hello *you.
How* are you?

Italic

To put some content in italic, you neeed to put it between slashes (/). For example, you can do:

This is an /emphasized/ element.

SpanDex book