# element-call-book

![Welcome to the element-call book.][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`.

[element_call_book]: https://gitea.networkx.de/rzerres/element-call-book/src/branch/main/src/img/element-call-1.png
<!--
	WIP: once it is ready to be shipped
	[The book is available in dead-tree form from No Starch Press][nostarch].

	[nostarch]: https://nostarch.com/

	You can read the book for free online. Please see the book as shipped with
	the latest [stable], or [develop] ELement-Call releases. Be aware that issues
	in those versions may have been fixed in this repository already, as those
	releases are updated less frequently.

	[stable]: https://element.io/element-call/stable/book/
	[develop]: https://ekenebt.io/element-call/book/

	See the [releases] to download just the code of all the code listings that appear in the book.

	[releases]: https://element.io/element-call/book/releases
-->

#### 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][rust-mdbook]. Install this tools with:

```console
$ 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.

[crates.io]: https://crates.io/crates/cargo-readme

##### 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][mdbook localization].

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

```rust
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-readme]: https://github.com/livioribeiro/cargo-readme

```console
$ cargo install cargo-readme
```

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

```console
$ cargo readme > README.md
```

[mdBook]: https://github.com/rust-lang-nursery/mdBook
[mdBook localization]: https://github.com/Nutomic/mdBook/tree/localization
[rust-mdbook]: https://github.com/rust-lang/rust/blob/master/src/tools/rustbook/Cargo.toml

#### 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:

```console
$ 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:_
```console
$ 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:_
```console
$ 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:

```console
$ 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:

```console
$ 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!

<!--
	WIP: once it is ready to be shipped
#### Code of Conduct

We are committed to providing a friendly, safe and welcoming
environment. Read more about our policy in the [code-of-conduct][coc] page.

[coc]: https://element-hq.github.io/element-call/book/policies/code-of-conduct.md

[contrib]: https://element-hq.github.io/element-call/book/blob/main/CONTRIBUTING.md
[contributors-guide]: https://element-hq.github.io/element-call/book/latest/development/contributing_guide.html
[element-documentation]: https://element-hq.github.io/element-call/book/latest>
[element-call-room-matrix]: https://matrix.to/#/#element-call-dev:matrix.org>`_`
-->

##### 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.

[Translations]: https://gitea.networkx.de/rzerres/element-call/book/issues?q=is%3Aopen+is%3Aissue+label%3ATranslations
[mdbook support]: https://github.com/rust-lang-nursery/mdBook/issues/5
[pull request]: https://github.com/rust-lang/mdBook/pull/1306

#### 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

<!-- License source -->
[Logo-CC_BY]: https://i.creativecommons.org/l/by/4.0/88x31.png "Creative Common Logo"
[License-CC_BY]: https://creativecommons.org/licenses/by/4.0/legalcode "Creative Common License"

This work is licensed under a [Creative Common License 4.0][License-CC_BY]

![Creative Common Logo][Logo-CC_BY]

© 2024 Ralf Zerres