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.

If you need a given version of mdbook, you may force it's installation the following call:

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

Multilingual version of mdBook

The Element-Call book aims to make translations as flawless as possible. With mdbook-i18n-helpers you gain Gettext Translation Support with three extensions.

$ cargo install mdbook-i18n-helpers

It will install three binaries:

mdbook-xgettext: This program extracts the source text. It is an mdbook renderer.
mdbook-gettext: This program translates the book into a target language. It is an mdbook preprocessor.
mdbook-i18n-normalize: This program normalizs a PO file. Use it after breaking changes.

Please have a look to the online documentation on howto actually use the Gettext subsystem.

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

🛠️ 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%