rzerres / orbtk-book

(WIP) The OrbTk book

orbtk-book

This repository contains the text source for "The Orbital Widget Toolkit" book. We will further reference to it as the OrbTk-Book.

Online Book

The following link will provide an online accessible version of the english variant of the guide:

https://redox-os.github.io/orbtk-book/en/index.html

The CI/CD workflow will render an updated version, as soon as enhanced content is merged into the maaster branch. Translations to other lanuages will be uploaded, as soon as they are completed. You may find working links via the wiki page.

Offline Book

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.

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 OrbTk book aims to make translations as flawless as possible. We are using v0.4.15 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.

Go ahead and install that mdBook version like this:

TMPDIR=<your_temporary_directory>
mkdir -p $TMPDIR; cd $TMPDIR
git clone https://github.com/Ruin0x11/mdBook.git
cd mdBook
git checkout localization
cargo update
cargo install --path .

We do make use of process visualization, that will need mermaid. To download and compile it from source, please use the following commands:

cargo install mdbook-mermaid
mermaid install

Building the book

To build the book with the default language (here: 'en'), change into OrbTk-books root directory and type:

$ mdbook build --language en --dest-dir orbtk-book/en

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

Firefox:

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

Chrome:

$ google-chrome orbtk-book/en/html/index.html                 # Linux
$ open -a "Google Chrome" orbtk-book/en/html/index.html       # OS X
$ Start-Process "chrome.exe" .\orbtk-book\en\html\index.html  # Windows (PowerShell)
$ start chrome.exe .\orbtk-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.

Test and validation of the book

To run all available tests please call:

$ mdbook test

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 OrbTk-book root directory and type:

$ mdbook build --language de --dest-dir orbtk-book/de --open

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

Cargo handled README

We do make uses of the crate cargo-readme. This enables us, to use the rust source code as the single root for any generated documentation. The README.md is one of the possible output. The doc comments in our lib.rs is parsed to generate the README.md file you are reading now.

Install the create with the following command if you want to update or regenerate the README.md 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

Code of Conduct

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

Contributing

We'd love your help! Please see CONTRIBUTING.md to learn about the kinds of contributions we're looking for.

Translations

We'd love help translating 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

© 2021-2022 Ralf Zerres