257 lines
9.5 KiB
Markdown
257 lines
9.5 KiB
Markdown
# Codesys ST Handbuch
|
||
|
||
|
||
|
||
**Version:** [VERSION](VERSION)
|
||
|
||
## Inhalt
|
||
|
||
- [Codesys ST Handbuch](#codesys-st-handbuch)
|
||
- [Inhalt](#inhalt)
|
||
- [Infos](#infos)
|
||
- [Struktur](#struktur)
|
||
- [Installation und Build](#installation-und-build)
|
||
- [Nötige Software für den Build](#nötige-software-für-den-build)
|
||
- [Schriftarten](#schriftarten)
|
||
- [Templates](#templates)
|
||
- [PDF](#pdf)
|
||
- [eBook (epub)](#ebook-epub)
|
||
- [DOCX (Office/ Word)](#docx-office-word)
|
||
- [Build](#build)
|
||
- [Erklärung zum Makefile](#erklärung-zum-makefile)
|
||
- [Struktur beim schreiben des Buchs](#struktur-beim-schreiben-des-buchs)
|
||
- [Schreiben mit VS-Code](#schreiben-mit-vs-code)
|
||
- [Projektinterne Tastenkombinationen mit `.vscode/keybindings.json`](#projektinterne-tastenkombinationen-mit-vscodekeybindingsjson)
|
||
- [Zweck](#zweck)
|
||
- [Einbindung in Visual Studio Code](#einbindung-in-visual-studio-code)
|
||
- [🔧 Vorgehen](#-vorgehen)
|
||
- [Empfehlung](#empfehlung)
|
||
- [Hinweis zur Konsistenz](#hinweis-zur-konsistenz)
|
||
- [Nützliche Links und Tipps für den Author](#nützliche-links-und-tipps-für-den-author)
|
||
- [Lizenz](#lizenz)
|
||
|
||
---
|
||
|
||
## Infos
|
||
|
||
---
|
||
|
||
## Struktur
|
||
|
||
```plaintext
|
||
|
||
📁 . #
|
||
├── 📁 build # Ausgabeordner (wird vom Build-Prozess befüllt)
|
||
├── 📁 manuscript #
|
||
│ ├── 📄 00_deckblatt.md #
|
||
│ ├── 📄 05_vorwort.md #
|
||
│ ├── 📄 10_kapitel1.md #
|
||
├── 📁 media # Bilder, Grafiken, Diagramme usw. NICHT im Manuskript enthalten sind.
|
||
│ ├── 📁 logo #
|
||
│ │ ├── 📄 logo.png #
|
||
│ └── 📄 favicon.ico #
|
||
├── 📁 metadata # Metadaten für eBook, Titelblatt, Author etc
|
||
│ ├── 📄 author.txt #
|
||
│ └── 📄 ebook.yaml #
|
||
├── 📁 styles # Pandoc-Templates, LaTeX-Vorlagen, CSS
|
||
│ ├── 📄 ebook-template.tex #
|
||
│ ├── 📄 ebook.css #
|
||
│ ├── 📄 print-template.tex #
|
||
│ └── 📄 reference.docx #
|
||
├── 📁 tools #
|
||
│ ├── 📄 bmp-emojis.md #
|
||
│ ├── 📄 cli-emojis.md #
|
||
│ ├── 📄 dev-setup.sh #
|
||
│ ├── 📄 gitcopy.bat #
|
||
│ └── 📄 tocgen.py #
|
||
├── 📄 .gitignore #
|
||
├── 📄 CHANGELOG.md #
|
||
├── 📄 desktop.ini #
|
||
├── 📄 LICENSE # Lizenz für das Buch (z. B. CC-BY)
|
||
├── 📄 Makefile # Automatisierter Build-Prozess mit Pandoc etc.
|
||
├── 📄 README.md # Diese Datei - Erklärung zum Build des Buchs
|
||
└── 📄 VERSION # Paketversion (ohne Zeilenumbruch einzeilig 0.0.0)
|
||
|
||
```
|
||
|
||
---
|
||
|
||
## Installation und Build
|
||
|
||
### Nötige Software für den Build
|
||
|
||
**Hinweis: TeX unter Windows?**
|
||
|
||
Obwohl es grundsätzlich möglich ist, TeX unter Windows zu installieren – und auch entsprechende Distributionen wie MiKTeX oder TeX Live für Windows existieren – rate ich dringend davon ab, auf diesem Weg zu starten.
|
||
|
||
Für einen stabilen und reproduzierbaren Build-Prozess empfiehlt sich stattdessen der Einsatz eines Linux-Systems. Wenn du kein dediziertes Linux verwendest, ist das Windows Subsystem for Linux (`WSL`) eine ausgezeichnete Alternative.
|
||
|
||
>Voraussetzung:
|
||
>Du solltest mit `apt` umgehen können und wissen, dass ein `update` vor dem `install` obligatorisch ist.
|
||
|
||
Falls der Build trotzdem scheitert oder du dir den Aufwand sparen möchtest, lade dir einfach die fertige PDF-Version herunter – oder bestelle dir direkt ein gedrucktes Exemplar des Buchs.
|
||
|
||
- **✅ Pandoc installieren:**
|
||
|
||
```sh
|
||
sudo apt install pandoc
|
||
```
|
||
|
||
- **✅ Empfohlene Installation: TeX Live Full** (ca.8GB)
|
||
|
||
```sh
|
||
sudo apt install texlive-full
|
||
```
|
||
|
||
Wenn NICHT `texlive-full`, dann aber:
|
||
|
||
- Zusätzlich deutsche Sprache (falls babel fehlt):
|
||
|
||
```bash
|
||
sudo apt install texlive-lang-german
|
||
```
|
||
|
||
Ich empfehle aber dringend `texlive-full` zu installieren da man erfahrungsgemäss am Anfang auf viele Fehler mit fehlenden Abhängigkeiten stößt wenn man Templates testet.
|
||
|
||
- **✅ Make installieren:**
|
||
|
||
Make oder besser die Anwendung `make` wird benötigt um die Erstellung der Ziele wie PDF zu automatisiern.
|
||
Dafür liegt auch das vorbereitete Skript `Makefile` im Hauptverzeichnis. Die ist nur optional und man kann es selbstverständlich auch manuell durchführen.
|
||
|
||
```sh
|
||
sudo apt install make
|
||
```
|
||
|
||
Ich verwende Version:
|
||
|
||
```sh
|
||
> make -v
|
||
GNU Make 4.3
|
||
Built for x86_64-pc-linux-gnu
|
||
```
|
||
|
||
#### Schriftarten
|
||
|
||
```sh
|
||
sudo apt install fonts-noto-color-emoji fonts-firacode
|
||
sudo apt install fonts-symbola
|
||
```
|
||
|
||
### Templates
|
||
|
||
#### PDF
|
||
|
||
#### eBook (epub)
|
||
|
||
#### DOCX (Office/ Word)
|
||
|
||
### Build
|
||
|
||
Schau mal ins [`Makefile`](./Makefile), dort findest Du einige Kandidaten um aus dem vorliegenden Markdown Manuskript eine entsprechende Version zu konvertieren. Es stehen zum aktuellen Zeitpunkt folgende zur Verfügung:
|
||
|
||
```sh
|
||
make pdf
|
||
make epub
|
||
make docx
|
||
```
|
||
|
||
Du musst im Kopfbereich der Datei zwingend ein paar Einstellungen vornehmen:
|
||
|
||
| Parameter | Beschreibung |
|
||
|-------------------------------------------|-------------------------------------------------------------|
|
||
| `# === Allgemeine Konfiguration ===` | |
|
||
| `TITLE := rust-tutorial` | Dateiname ohne Erweiterung für die Ausgabe nach dem Build |
|
||
| `MANUSCRIPT := manuscript` | |
|
||
| `MANUSCRIPT := manuscript` | |
|
||
| `OUTPUT := build` | |
|
||
| `METADATA := metadata/ebook.yaml` | |
|
||
| `CSS := styles/ebook.css` | |
|
||
| `TEX_EBOOK := styles/ebook-template.tex` | |
|
||
| `TEX_PRINT := styles/print-template.tex` | |
|
||
| `LOGO := media/logo/logo.png` | Logo für den epub Build |
|
||
|
||
---
|
||
|
||
#### Erklärung zum Makefile
|
||
|
||
---
|
||
|
||
## Struktur beim schreiben des Buchs
|
||
|
||
1. Kapitel sind in Dateien die jeweils von 00 aufsteigend sortiert sind. Pandoc baut sie aufsteigend ins Buch.
|
||
Kapitel 1 zB in `10_kapitel1.md`. Die vorstehende 10 steht für 1. Sollte zB Kapitel 1.1 hinzukommen,
|
||
dann man diese `11_kapitel1.md` benennen. Hoffe es ist verständlich.
|
||
2. Bilder sind nach Kapitel und fortlaufender Nummer sowie einem Hinweis benannt.
|
||
|
||
---
|
||
|
||
## Schreiben mit VS-Code
|
||
|
||
### Projektinterne Tastenkombinationen mit `.vscode/keybindings.json`
|
||
|
||
Zur Vereinfachung und Vereinheitlichung der Bedienung ist in diesem Projekt eine Datei `.vscode/keybindings.json` enthalten. Diese Datei definiert projektweit gültige Tastenkombinationen, die bestimmte Aufgaben in Visual Studio Code auslösen – beispielsweise den PDF-Build aus Markdown heraus.
|
||
|
||
> ⚠ Diese Datei ist **verpflichtender Bestandteil des Projekts** und muss bei jeder lokalen Arbeitskopie vorhanden sein.
|
||
|
||
---
|
||
|
||
#### Zweck
|
||
|
||
Die `keybindings.json` im Projektordner ermöglicht es, projektbezogene Aktionen wie das Erzeugen von PDF-Dokumenten über eine einfache Tastenkombination aufzurufen. Sie ergänzt die zentrale Datei `tasks.json`, in der die ausführbaren Aktionen definiert sind.
|
||
|
||
Ein typischer Anwendungsfall ist die Kombination mit einem WSL-basierten Build-Befehl:
|
||
|
||
```json
|
||
{
|
||
"key": "ctrl+alt+p",
|
||
"command": "workbench.action.tasks.runTask",
|
||
"args": "Markdown → PDF (Pandoc via WSL)",
|
||
"when": "editorLangId == markdown"
|
||
}
|
||
```
|
||
|
||
Diese Tastenkombination führt den Build-Task `Markdown → PDF (Pandoc via WSL)` aus, der wiederum intern `wsl make pdf` ausführt.
|
||
|
||
#### Einbindung in Visual Studio Code
|
||
|
||
Visual Studio Code erlaubt von Haus aus keine automatische Nutzung Projektinterne `keybindings.json`-Dateien. Daher muss der Inhalt aus `.vscode/keybindings.json` **manuell** in das globale Benutzerprofil übernommen werden:
|
||
|
||
#### 🔧 Vorgehen
|
||
|
||
1. Öffne in VS Code die Tastenkombination `Strg + Shift + P`
|
||
2. Wähle:
|
||
`Preferences: Open Keyboard Shortcuts (JSON)`
|
||
3. Kopiere den Inhalt aus der Datei `.vscode/keybindings.json` ins geöffnete Profil
|
||
4. Speichern, fertig
|
||
|
||
> 💬 Alternativ kann die Datei bei einer Neuinstallation auch einfach in den globalen Pfad kopiert werden. Unter Windows befindet sich dieser unter `%APPDATA%\Code\User\keybindings.json`.
|
||
|
||
#### Empfehlung
|
||
|
||
Es wird empfohlen, regelmäßig zu prüfen, ob die Projektinterne `keybindings.json` aktualisiert wurde (z. B. durch einen Pull). Neue Funktionen oder Workflows können dort neue Tastenkombinationen erhalten.
|
||
|
||
#### Hinweis zur Konsistenz
|
||
|
||
Um eine konsistente Bedienbarkeit zu gewährleisten, sollte **ausschließlich die im Projekt enthaltene `keybindings.json` verwendet werden**. Eigene globale Kürzel sollten nach Möglichkeit vermieden oder dokumentiert angepasst werden.
|
||
|
||
---
|
||
|
||
## Nützliche Links und Tipps für den Author
|
||
|
||
- **Zeichen Testen**
|
||
-> <https://r12a.github.io/uniview/>
|
||
|
||
Oder `hexdump` aus:
|
||
|
||
```sh
|
||
sudo apt install bsdmainutils
|
||
```
|
||
|
||
---
|
||
|
||
## Lizenz
|
||
|
||
**(C) 2025 - Adam Skotarczak**
|
||
|
||
---
|