├── .gitignore ├── book.toml ├── src ├── getting-started.md ├── SUMMARY.md ├── basic.md ├── install.md ├── syntax-basic.md └── introduction.md └── .travis.yml /.gitignore: -------------------------------------------------------------------------------- 1 | book 2 | -------------------------------------------------------------------------------- /book.toml: -------------------------------------------------------------------------------- 1 | [book] 2 | authors = ["Thomas Forgione"] 3 | multilingual = false 4 | src = "src" 5 | title = "SpanDex book" 6 | -------------------------------------------------------------------------------- /src/getting-started.md: -------------------------------------------------------------------------------- 1 | # Getting started 2 | 3 | The few next sections will guide you through the following things: 4 | - installing SpanDeX and its dependencies 5 | - starting a SpanDeX project and compiling it 6 | -------------------------------------------------------------------------------- /src/SUMMARY.md: -------------------------------------------------------------------------------- 1 | # Summary 2 | 3 | [Introduction](./introduction.md) 4 | - [Getting started](./getting-started.md) 5 | - [Installing SpanDeX](./install.md) 6 | - [Creating a basic SpanDeX project](./basic.md) 7 | - [SpanDeX syntax](./syntax-basic.md) 8 | -------------------------------------------------------------------------------- /.travis.yml: -------------------------------------------------------------------------------- 1 | language: rust 2 | sudo: false 3 | 4 | cache: 5 | - cargo 6 | 7 | rust: 8 | - stable 9 | 10 | 11 | before_script: 12 | - (test -x $HOME/.cargo/bin/mdbook || cargo install mdbook) 13 | 14 | 15 | script: 16 | - mdbook build 17 | 18 | deploy: 19 | provider: pages 20 | overwrite: true 21 | skip_cleanup: true 22 | github_token: $GITHUB_TOKEN 23 | repo: rust-spandex/rust-spandex.github.io 24 | target_branch: master 25 | local_dir: book 26 | on: 27 | branch: master 28 | 29 | notifications: 30 | email: 31 | on_success: never 32 | on_failure: always 33 | -------------------------------------------------------------------------------- /src/basic.md: -------------------------------------------------------------------------------- 1 | # Creating a basic SpanDeX project 2 | 3 | There are two ways of creating a SpanDeX project: 4 | - either you want to create it in a new directory, in which case you can run 5 | ``` bash 6 | spandex init 7 | ``` 8 | 9 | - or you already have in directory that you want to setup for a SpanDeX 10 | project, in which case you can simply run 11 | ``` bash 12 | spandex init 13 | ``` 14 | 15 | This will generate the default configuration file `spandex.toml` and an initial 16 | `main.dex` file. 17 | 18 | To compile your files into a PDF, you can simply run 19 | 20 | ``` bash 21 | spandex build 22 | ``` 23 | 24 | -------------------------------------------------------------------------------- /src/install.md: -------------------------------------------------------------------------------- 1 | # Installing SpanDeX 2 | 3 | SpanDeX is not (yet) tested on any other operating system other than Linux 4 | based. 5 | 6 | ## Install rust 7 | 8 | The first thing you need to do in order to run SpanDeX is to install rust. 9 | If you're on a Linux based system, it should be as simple as running 10 | 11 | ``` bash 12 | curl -sSf https://sh.rustup.rs | sh 13 | ``` 14 | 15 | in a terminal and answer the few questions that will be prompted. 16 | 17 | If you're on another operating system, we invite you to [read rust's 18 | documentation](https://doc.rust-lang.org/book/ch01-01-installation.html) to 19 | find out the best way of installing rust on your computer. 20 | 21 | ## Install SpanDeX 22 | 23 | If you have successfully installed rust, you should be able to install SpanDeX 24 | by simply running 25 | 26 | ``` 27 | cargo install --git https://github.com/tforgione/spandex -f 28 | ``` 29 | 30 | You can run this command again to update SpanDeX to the latest version. 31 | 32 | -------------------------------------------------------------------------------- /src/syntax-basic.md: -------------------------------------------------------------------------------- 1 | # SpanDeX syntax 2 | 3 | The syntax of DeX is inspired by 4 | [Markdown](https://en.wikipedia.org/wiki/Markdown) and, to a lesser 5 | extent, by [elm-markup](https://github.com/mdgriffith/elm-markup). 6 | 7 | ## Paragraphs 8 | 9 | In DeX, paragraphs are content that are not titles and that are separated 10 | by an empty line. 11 | 12 | ``` md 13 | This is a paragraph. 14 | This is still the same paragraph. 15 | 16 | This is a new paragraph. 17 | ``` 18 | 19 | ## Titles 20 | 21 | Titles are declared by prepending a line with `#`, just like Markdown. 22 | 23 | For example, you may make titles and subtitles like so: 24 | 25 | ``` none 26 | # My title 27 | 28 | ## My subtitle 29 | ``` 30 | 31 | In DeX, however, you need to leave an empty line following a title. 32 | 33 | If you try to compile this 34 | 35 | ``` none 36 | # My title 37 | ## My subtitle 38 | ``` 39 | 40 | the compiler will crash giving the following ouptut: 41 | 42 | ``` none 43 | error: titles must be followed by an empty line 44 | --> main.dex:2:1 45 | | 46 | 2 | ## My subtitle 47 | | ^ expected empty line here 48 | | 49 | ``` 50 | 51 | ## Inline 52 | 53 | Like many markup languages, DeX has inline elements that allow you to 54 | typeset your content. Inline elements cannot spread accross different paragraphs. 55 | If you want to do that, you will have to end your inline at the end of your 56 | paragraph, and start it again at the begining of the next one. 57 | 58 | ### Bold 59 | 60 | To put some content in bold, you need to put it between stars (`*`). For 61 | example, you can do: 62 | 63 | ``` none 64 | This is a *strong* element. 65 | ``` 66 | 67 | As described previously, trying to spread an inline over different paragaphs 68 | won't work, and the compiler will give an error saying that you haven't closed 69 | your inline tag. For example, the following code 70 | 71 | ``` none 72 | Hello *you 73 | 74 | how* are you? 75 | ``` 76 | 77 | will give the following errors: 78 | 79 | ``` none 80 | error: unmatched * 81 | --> main.dex:1:7 82 | | 83 | 1 | Hello *you 84 | | ^ bold content starts here but never ends 85 | | 86 | error: unmatched * 87 | --> main.dex:3:4 88 | | 89 | 3 | how* are you? 90 | | ^ bold content starts here but never ends 91 | | 92 | ``` 93 | 94 | However, since pargraphs can spread over multiple lines, you can totally do the 95 | following: 96 | 97 | ``` none 98 | Hello *you. 99 | How* are you? 100 | ``` 101 | 102 | ### Italic 103 | 104 | To put some content in italic, you neeed to put it between slashes (`/`). For 105 | example, you can do: 106 | 107 | ``` none 108 | This is an /emphasized/ element. 109 | ``` 110 | -------------------------------------------------------------------------------- /src/introduction.md: -------------------------------------------------------------------------------- 1 | # Introduction 2 | 3 | Welcome to the SpanDeX book. This book serves as a tutorial for SpanDeX. 4 | 5 | ## What is SpanDeX? 6 | 7 | SpanDeX is a modern alternative to LaTeX, carefully designed to be: 8 | 9 | - **ultra performant**, allowing lightning fast compilation and 10 | hot reloading with optimized algorithms; 11 | - **simple**, avoiding the need for users to learn a complex 12 | language before being able to do basic things; 13 | - **easy to debug**, not reproducing the tons of useless stuff LaTeX vomits 14 | every time something goes wrong and making it a breeze to find and fix simple 15 | mistakes. 16 | 17 | ## Main TeX's pitfalls being worked on 18 | 19 | Overall, SpanDeX aims at taking advantage of TeX's strengths while proposing 20 | novel approaches where it performs poorly. The core idea behind SpanDeX is to 21 | build things in a way that will allow the engine to take smarter decisions at 22 | every step. 23 | 24 | ### TeX's opaque syntax 25 | 26 | While nearly every academic paper involving some level of math is written in 27 | TeX and people became accustomed to it, its syntax can be quite a challenge to 28 | grasp for the newcomer. 29 | 30 | For instance, though it's pretty straightforward to typeset basic paragraphs and 31 | titles in TeX, it becomes extremely unhandy and clogged up with avoidable stuff 32 | as soon as you'd like to stylize your document somewhat. 33 | 34 | DeX proposes to instead invest on what's been done with the most recent 35 | languages that aim at being minimalistic while remaining explicit and easy to 36 | remember. 37 | 38 | ### TeX's unability to typeset paragraphs in a fully context aware manner 39 | 40 | TeX does not keep track of where it is when it tries typesetting paragraphs. 41 | This makes it nearly impossible to implement somewhat complicated layouts in a 42 | straightforward way. Moreover, this prevents TeX's core typesetting algorithm 43 | from having the opportunity to take smarter decisions when breaking down 44 | paragraphs into lines, /e.g/ to avoid orphans and widows. 45 | 46 | SpanDeX implements a novel approach based on the concept of layouts. In this 47 | paradigm, a paragraph "typesets itself" inside of a layout that tells the 48 | paragraph where it is and where it can go next. This gives the paragraph the 49 | possibility to make smart decisions and even go back, if necessary. Being 50 | context-dependent, this approach also unveils opportunities for improved caching 51 | and thus, performance. 52 | 53 | It then becomes extremely simple to define and configure arbitrary layouts, 54 | dissect them into columns, etc. 55 | 56 | ## WIP 57 | 58 | This project is still very recent, and very (very) few functionnalities are 59 | supported. This is not production ready in any way, it's simply here if you 60 | want to have fun and play around. 61 | 62 | ## API documentation 63 | 64 | The API documentation is available [here](/spandex). 65 | 66 | ## Source code 67 | 68 | [The source code is available on GitHub](https://github.com/rust-spandex/spandex). 69 | --------------------------------------------------------------------------------