155 lines
4.7 KiB
Markdown
155 lines
4.7 KiB
Markdown
# 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
|