Building the book requires mdBook and its helper tools. The used version should be ideally the same that rust-lang/rust uses in this file. Install this tools with:

$ cargo install mdbook mdbook-linkchecker mdbook-mermaid

This command will grep the latest mdbook version from crates.io in combination with the add-on tools mdbook-linkchecker and mdbook-mermaid. With the linkchecker we are able to asure, that the used links inside the markdown source can resolve to valid targets. mkbook-mermaid is a preprocessor for mdbook to add mermaid.js support. We do use it to create graphs that visiulize some process flows.

Multilingual version of mdBook

The Element-Call book aims to make translations as flawless as possible. We are using v0.4.12 that will do the job. There is a patch available that adds the needed salt to organize a book as a multilingual structure: All sources stored in a single hirachical code tree. This work isn't finished yet, but good enough to make use of this branch for our productive needs. Thank you Nutomic and Ruin0x11.

You can force the installation of a given version number with:

console $ cargo install mdbook --vers 0.4.12 mdbook-linkchecker mdbook-mermaid

Cargo handled README

We do make uses of the crate cargo-readme. It resolves rust doc comments to generate the README.md file you are reading now. Install the create with the following command if you want to update or regenerate this README yourself.

$ cargo install cargo-readme

Once the cargo-readme binary is available, you can render the README.md. Change into the document-root and type:

$ cargo readme > README.md

Building

Building the book

To build the book with the default language (here: 'en'), change into the root directory of the element-call submodule and type:

$ mdbook build --dest-dir book/en

The rendered HTML output will be placed underneath the book/en subdirectory. To check it out, open it in your web browser.

Firefox:

$ firefox book/en/html/index.html                       # Linux
$ open -a "Firefox" book/en/html/index.html             # OS X
$ Start-Process "firefox.exe" .\book\en\html\index.html # Windows (PowerShell)
$ start firefox.exe .\book\en\html\index.html           # Windows (Cmd)

Chrome:

$ google-chrome book/en/html/index.html                 # Linux
$ open -a "Google Chrome" book/en/html/index.html       # OS X
$ Start-Process "chrome.exe" .\book\en\html\index.html  # Windows (PowerShell)
$ start chrome.exe .\book\en\html\index.html            # Windows (Cmd)

Executing mdbook serve will have mdbook act has a web service which can be accessed opening the following URL: http://localhost:3000.

To run the tests:

$ mdbook test

Building a language variant of the book

Translated version of the book will be placed inside the code tree in the subdirectory src/<language id.

E.g. if you like to render the german version (language id: 'de'), change into Element-Call books root directory and type:

$ MDBOOK_BOOK__src=src/de mdbook build --dest-dir book/de --open

The rendered HTML output will be placed underneath the book/de subdirectory. Since we appended the --open parameter, your default browser should be fired up and ... tada!

🛠️ Development

==================

We welcome contributions to the Element-Call book from the community! The best place to get started is our [guide for contributors][contributors-guide].

This is part of our larger [`documentation][element-documentation], which includes information for Element-Call developers and translaters. We'd love your help! Please see [CONTRIBUTING.md][contrib] to learn about the kinds of contributions we're looking for.

Alongside all that, join our [developercommunity][element-call-room-matrix] on Matrix, featuring real humans!

Translations

We'd love help to translate the book! See the Translations label to join in efforts that are currently in progress. Open a new issue to start working on a new language! We're waiting on mdbook support for multiple languages to be finalized, but feel free to start! A pull request looks promising. The mainline version (we do depend on v0.4.12) is capable to render the existing versions where sources are installed in the intended final structure.

Spellchecking

To scan source files for spelling errors, you can use the spellcheck.sh script. It needs a dictionary of valid words, which is provided in dictionary.txt. If the script produces a false positive (say, you used word BTreeMap which the script considers invalid), you need to add this word to dictionary.txt (keep the sorted order for consistency).

License

This work is licensed under a Creative Common License 4.0

Languages

Rust 71.3%

XSLT 14.7%

Shell 9.8%

CSS 2.3%

JavaScript 1.9%