156 lines
5.3 KiB
Rust
156 lines
5.3 KiB
Rust
#![crate_name = "WRI IT-Koncept"]
|
|
#![crate_type = "lib"]
|
|
|
|
//! <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
|