element-call-book

Welcome to the Element-Call book.

This repository contains the text source for "The Element-Call" book. We will further reference to it as the Element-Call Book.

☝ Requirements

mdBook

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!

✒ 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

© 2024 Ralf Zerres