WRI IT-Konzept

This repository contains the text source documenting the "IT-Konzept at WERNER RI". We will further reference to it as the IT-Konzept.

TLDR

To conveniently read an online version of this documentation, please open the link to the IT-Konzept.

Requirements

Building the rendered text requires the program mdBook and its helper tools. The consumed version should be ideally the same that rust-lang/rust uses. Install this tools with:

$ cargo install mdbook

This command will grep a suitable mdbook version with all needed dependencies from crates.io.

You may extend the call with

$ cargo install mdbook mdbook-linkchecker mdbook-mermaid

This will enable us to make use of alinkchecker to assure, 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 may use it to create graphs that visualize some process flows.

Multilingual version of mdBook

The documentation aims to make translations as flawless as possible. We are using mainline mdbook with following extensions from the [mdBook-i18n-helpers} crate.

This extension implements a multilingual extension, that consumes The gettext / xgettext subsystem.

As an alternative, there does exist a patch-set for version v0.4.15 that adds the needed salt to organize a book as a multilingual structure: All sources stored in a single hierarchical code tree. This work isn't finished yet, but good enough to make use of this branch for productive needs. Thank you Nutomic and Ruin0x11.

Cargo handled README

The README.md file you are reading now is auto generated via the cargo-readme crate. It resolves rust doc comments in src/lib.rs and generates the parsed code to a target README.md file. The installation is optional.

You need it, if you make changes to src/lib.rs and want to update or regenerate the target README like that:

$ cargo install cargo-readme
$ cargo readme > README.md

Building

Building the documentation

To build the documentation with the default language (here: 'de'), change into projects root directory and type:

$ mdbook build --dest-dir doc/de

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

Firefox:

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

Chrome:

$ google-chrome doc/en/index.html                 # Linux
$ open -a "Google Chrome" doc/en/index.html       # OS X
$ Start-Process "chrome.exe" .\doc\en\index.html  # Windows (PowerShell)
$ start chrome.exe .\doc\en\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 english version (language id: 'en'), change into documents root directory and type:

$ mdbook build --dest-dir doc/en --open

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

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

© 2025 Ralf Zerres