# WRI IT-Konzept

<img src="src/assets/Logo_WERNER_RI.png" width="40%" loading="lazy"/>


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][IT-Konzept-Doc].

[IT-Konzept-Doc]: ./doc/en/index.html

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

```console
$ cargo install mdbook
```

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

You may extend the call with

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

[crates.io]: https://crates.io/search?q=mdbook

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

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

[cargo-readme]: https://github.com/livioribeiro/cargo-readme

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

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

[mdBook]: https://github.com/rust-lang-nursery/mdBook
[mdBook-i18n-helpers]: https://github.com/google/mdbook-i18n-helpers
[mdBook localization]: https://github.com/Ruin0x11/mdbook/tree/localization

### Building

#### Building the documentation

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

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

```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 english version (language id: 'en'), change
into documents root directory and type:

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

<!-- 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]

© 2025 Ralf Zerres