codesys-st-handbuch/README.md

# Codesys ST Handbuch

![Buch-Logo](./media/logo/logo.png)  

**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**  

---