Initial commit
Commit
This commit is contained in:
Ralf Zerres
155
README.md
155
README.md
@@ -1,3 +1,154 @@
|
||||
# IT-Konzept
|
||||
# WRI IT-Konzept
|
||||
|
||||
Dokumentation zur IT-Konzeption bei WERNER RI
|
||||
<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
|
||||
|
||||
Reference in New Issue
Block a user