diff --git a/.gitignore b/.gitignore index e232813..e262f0d 100644 --- a/.gitignore +++ b/.gitignore @@ -2,12 +2,13 @@ # Files *.zip +INHALT.md +.gitkeep desktop.ini -# Folders -build/** -!build/.gitkeep +# Pandoc +missfont.log -# Lokale Branch-Kennzeichnung (nicht tracken) -# Git-Hook aus ./tools/dev-setup.sh -BRANCH-* +# Folders +#.vscode/** +build/** diff --git a/.vscode/cspell.json b/.vscode/cspell.json index 88cea74..dca3a0c 100644 --- a/.vscode/cspell.json +++ b/.vscode/cspell.json @@ -27,13 +27,22 @@ ".git" ], "words": [ + "abschranken", "adoc", + "allpolig", "AsciiDoc", "autochapter", + "Autorenrechtlich", + "DGUV", + "Effizienzkritischen", + "Funkengefahr", + "gitcopy", "kapitel", "makefile", "PDFTheme", "realAscot", - "Skotarczak" + "Schottky", + "Skotarczak", + "tocgen" ] } diff --git a/.vscode/extensions.json b/.vscode/extensions.json new file mode 100644 index 0000000..53dcdd9 --- /dev/null +++ b/.vscode/extensions.json @@ -0,0 +1,11 @@ +{ + "recommendations": [ + "streetsidesoftware.code-spell-checker", + "streetsidesoftware.code-spell-checker-german", + "streetsidesoftware.code-spell-checker", + "streetsidesoftware.code-spell-checker-german", + "davidanson.vscode-markdownlint", + "yzane.markdown-pdf", + "yzhang.markdown-all-in-one" + ] +} diff --git a/.vscode/keybindings.json b/.vscode/keybindings.json new file mode 100644 index 0000000..18e7ad1 --- /dev/null +++ b/.vscode/keybindings.json @@ -0,0 +1,8 @@ +[ + { + "key": "ctrl+alt+p", + "command": "workbench.action.tasks.runTask", + "args": "Markdown → PDF (Pandoc via WSL)", + "when": "editorLangId == markdown" + } +] diff --git a/.vscode/settings.json b/.vscode/settings.json index 65d6193..bbc07af 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -16,5 +16,50 @@ "[asciidoc]": { "files.eol": "\n" }, - "files.encoding": "utf8" + "files.encoding": "utf8", + + "makefile.configureOnOpen": false, + + "cSpell.language": "de,de-DE,en", + "cSpell.dictionaries": ["de_DE", "en"], + "cSpell.enabled": true, + "[markdown]": { + "editor.wordWrap": "on", + "editor.quickSuggestions": { + "other": true, + "comments": true, + "strings": true + }, + "editor.renderWhitespace": "all", + }, + "markdownlint.config": { + "default": true, + "MD013": false, + "MD033": false, + "MD041": false + }, + "markdown-pdf.puppeteerLaunchOptions": { + "args": ["--no-sandbox", "--disable-setuid-sandbox"] + }, + "markdown-pdf.note": "Tastenkombi 'Ctrl+Alt+P' startet WSL-Build → PDF", + "cSpell.words": [ + "Betriebsystem", + "Buildchain", + "Buildversion", + "CLI", + "epub", + "GitHub", + "LaTeX", + "Markdown", + "newpage", + "pandoc", + "Pandoc", + "Printversion", + "Projektinterne", + "reintext", + "Rust", + "Skotarczak", + "Texlive", + "UTF" + ] } diff --git a/.vscode/tasks.json b/.vscode/tasks.json new file mode 100644 index 0000000..45ea062 --- /dev/null +++ b/.vscode/tasks.json @@ -0,0 +1,19 @@ +{ + "version": "2.0.0", + "tasks": [ + { + "label": "Markdown → PDF (Pandoc via WSL)", + "type": "shell", + "command": "wsl make pdf", + "group": { + "kind": "build", + "isDefault": true + }, + "problemMatcher": [], + "presentation": { + "reveal": "always", + "panel": "shared" + } + } + ] +} diff --git a/CHANGELOG.md b/CHANGELOG.md index 53e762c..dd5dda6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,10 @@ -# Changelog TS-Tutorial +# Changelog - Elektrotechnik Handbuch -- **2025-05-13** - - v0.1.0 - Style und Struktur überarbeitet - - initial commit +- **2025-05-19** + - **Hinzugefügt:** + - basis Konfiguration + - **Geändert:** + - [X] Verzeichnistiefe über Makefile nun einstellbar (TOCDEPTH) + +- **2025-05-18** + - initial commit diff --git a/LICENSE b/LICENSE index e69de29..06e14c8 100644 --- a/LICENSE +++ b/LICENSE @@ -0,0 +1,56 @@ +# **LICENSE** + +*(Version 1.0 – April 2025)* + +--- + +**Buchlizenz – "Autorenrechtlich geschützt, freie Lesbarkeit – keine kommerzielle Nutzung"** + +Copyright © 2025 Adam Skotarczak +Alle Rechte vorbehalten. + +Dieses Buchprojekt ist urheberrechtlich geschützt. +Es darf **kostenfrei gelesen, geteilt und verlinkt** werden, solange folgende Bedingungen eingehalten werden: + +--- + +## 🔒 Rechte und Kontrolle + +- Das Urheberrecht am gesamten Inhalt liegt ausschließlich beim Autor. +- Beiträge (z. B. via GitHub Pull Requests) sind willkommen, werden jedoch nur mit Zustimmung des Autors übernommen. +- Mit der Einreichung eines Beitrags überträgt der Beitragende dem Autor ein einfaches Nutzungsrecht für die Veröffentlichung im Buch. + Es entsteht **kein Miturheberrecht** und keine Ansprüche auf spätere Verwendung. + +--- + +## ✅ Erlaubt + +- Nichtkommerzielle Nutzung (z. B. Lesen, Weitergeben, Zitieren) bei Namensnennung. +- Teilen des unveränderten Inhalts (z. B. als PDF, auf Webseiten, im Unterricht etc.). +- Verlinkung auf das GitHub-Repository oder andere offizielle Quellen. + +--- + +## ❌ Nicht erlaubt + +- Kommerzielle Nutzung (z. B. Verkauf, Druckexemplare gegen Entgelt, Verwendung in kostenpflichtigen Produkten oder Kursen). +- Veränderung oder Bearbeitung des Buchinhalts ohne ausdrückliche Genehmigung. +- Veröffentlichung abgewandelter Fassungen unter eigenem Namen. + +--- + +## ℹ️ Hinweis zur Lizenzform + +Diese Lizenz basiert inhaltlich auf der Creative Commons Lizenz +**CC BY-NC-ND 4.0 International**, jedoch mit zusätzlichen Klarstellungen zur Beitragspolitik und Urheberrolle. + +Für juristische Auslegung gilt deutsches Urheberrecht. + +--- + +**Kontakt:** +Adam Skotarczak +✉️ +🔗 + +--- diff --git a/Makefile b/Makefile index cc78a06..14a57d7 100644 --- a/Makefile +++ b/Makefile @@ -1,35 +1,104 @@ -# Makefile für Markdown-eBook-Projekt mit Pandoc +# Makefile für Markdown-eBook-Projekt Rust Handbuch mit Pandoc +# (C) 2025 - Adam Skotarczak - 19/06/2025 # === Allgemeine Konfiguration === -TITLE := dateiname_aus_makefile -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_256x256.png + +# === Titel des eBooks === +TITLE := Vorlage_eBook + +# === Verzeichnis mit Markdown-Dateien === +MANUSCRIPT := manuscript + +# === Ausgabeordner für Builds === +OUTPUT := build + +# === Metadaten für das eBook === +METADATA := metadata/ebook.yaml + +# === CSS-Datei für das eBook === +CSS := styles/ebook.css + +# === LaTeX-Vorlage für das eBook === +TEX_EBOOK := styles/ebook-template.tex + +# === LaTeX-Vorlage für den Druck === +TEX_PRINT := styles/print-template.tex + +# === Logo für das eBook === +LOGO := media/logo/logo.png + +# === Pfad zu Hilfswerkzeugen === +TOOLPATH := tools + +# === LaTeX Geometrie-Einstellungen (z.B. A5-Papier) === +GEOMETRY := geometry:a5paper + +# === Schriftart für LaTeX === +FONT := Noto Sans CJK SC + +# === Python Index für make toc === +INDEXFILE := INHALT + +# === Verzeichnistiefe im eBook === +TOCDEPTH := 3 + +# === Automatische Konfiguration === +VERSION := $(shell cat VERSION) +PYTHON := $(shell command -v python3 || command -v python) # === Nur wsl oder Linux === # ifeq ($(OS),Windows_NT) set_codepage: @if [ "$(OS)" = "Windows_NT" ]; then chcp 65001 >nul; fi $(error [⚠] Windows wird nicht unterstützt. Bitte WSL oder Linux verwenden.) + exit(1) endif # === Quelldateien (geordnet nach Nummerierung) === -MD_FILES := $(wildcard $(MANUSCRIPT)/*.md) -MD_SORTED := $(sort $(MD_FILES)) + +# Standard: prod, falls nicht durch CLI überschrieben +MODE ?= prod + +MD_ALL = $(wildcard $(MANUSCRIPT)/*.md) + +# Dateien auslassen im MODE prod +MD_FILES_prod = $(filter-out \ + $(MANUSCRIPT)/00_Deckblatt.md, \ + $(MD_ALL)) +MD_FILES_dev = $(MD_ALL) + +# Dynamische Auswahl je nach MODE +define set_md_files +$(eval MD_FILES := $(MD_FILES_$(MODE))) +$(eval MD_SORTED := $(sort $(MD_FILES))) +endef + + +# === Standardziel: Setze Codepage und führe alle Builds aus === +.DEFAULT_GOAL := all + + +# === Abhängigkeiten prüfen === +check-deps: check-python check-fonts +.PHONY: check-deps + # === Standardziel: Alles bauen === -all: epub pdf html docx +all: clean plain epub pdf html docx toc + + +# === Hier ist geplant make zu missbrauchen, die notwendigen Abhängigkeiten zu installieren === +install: + @echo "\n⚠ - Noch nicht implementiert!\n" + # === EPUB-Ausgabe === epub: $(OUTPUT) + $(call set_md_files) pandoc $(MD_SORTED) \ --metadata-file=$(METADATA) \ --resource-path=media \ - --toc --toc-depth=2 \ + --toc --toc-depth=$(TOCDEEP) \ --css=$(CSS) \ --epub-chapter-level=1 \ --epub-cover-image=$(LOGO) \ @@ -50,19 +119,28 @@ epub: $(OUTPUT) #| `haddock` | Stil von Haddock-Dokumentation | #| `breezedark` | KDE-Breeze-Dark-inspiriert (dunkel, modern) | -pdf: - pandoc $(MD_SORTED) \ +# === PDF Generierung === +pdf: $(OUTPUT) + $(call set_md_files) + @echo "Verwende MODE=$(MODE)" + @echo "Dateien: $(MD_FILES)" + @pandoc $(MD_SORTED) \ --columns=1000 \ --metadata-file=$(METADATA) \ + --metadata version="$(VERSION)" \ --resource-path=media \ - --toc --number-sections \ + --toc --number-sections --toc-depth=$(TOCDEPTH) \ --template=$(TEX_PRINT) \ --pdf-engine=xelatex \ --highlight-style=tango \ + -V toc-depth=$(TOCDEPTH) \ + -V $(GEOMETRY) \ + -V buildmode=$(MODE) \ -o $(OUTPUT)/$(TITLE).pdf # === HTML-Vorschau oder Export === html: $(OUTPUT) + $(call set_md_files) pandoc $(MD_SORTED) \ --metadata-file=$(METADATA) \ --resource-path=media \ @@ -70,15 +148,19 @@ html: $(OUTPUT) --css=$(CSS) \ -o $(OUTPUT)/$(TITLE).html + # === Word-Version (Lektorat etc.) === docx: $(OUTPUT) + $(call set_md_files) pandoc $(MD_SORTED) \ --metadata-file=$(METADATA) \ --resource-path=media \ --toc --number-sections \ -o $(OUTPUT)/$(TITLE).docx + plain: $(OUTPUT) + $(call set_md_files) pandoc $(MD_SORTED) \ --metadata-file=$(METADATA) \ --resource-path=media \ @@ -86,16 +168,48 @@ plain: $(OUTPUT) -t plain \ -o $(OUTPUT)/$(TITLE)_reintext.txt + # === Vorschau im Terminal (reines Markdown) === preview: cat $(MD_SORTED) | less + # === Sicherstellen, dass der Ausgabeordner existiert === $(OUTPUT): - mkdir -p $(OUTPUT) + @mkdir -p $(OUTPUT) + @echo "[i] Verzeichnis $(OUTPUT) erstellt!" + + +# === Python-Check === +check-python: + @$(PYTHON) --version || (echo "❌ Python nicht gefunden, wsl gestartet?" && exit 1) + + +# === Fonts testen === +check-fonts: + @fc-match "$(FONT)" >/dev/null || (echo "❌ Schriftart $(FONT) nicht gefunden!" && exit 1) + + +# === Erstellt aus einem vordefinierten Verzeichnis mit Markdown-Dateien einen Inhaltsverzeichnis === +toc: + @echo "📚 Generiere Inhaltsverzeichnis in .\$(INDEXFILE).md ..." + @$(PYTHON) $(TOOLPATH)/tocgen.py -d $(MANUSCRIPT) -o $(INDEXFILE).md + @echo "📚 Inhaltsverzeichnis in .\$(INDEXFILE).md erstellt." + @echo "✅ Fertig." + # === Bereinigen der Ausgaben === clean: - rm -rf $(OUTPUT)/* + @rm -rf $(OUTPUT)/* + @echo "🧹 alle Builds unter $(OUTPUT)\ gelöscht." + @rm -f $(INDEXFILE).md + @echo "🧹 $(INDEXFILE).md gelöscht." -.PHONY: all epub pdf html docx preview clean +clear: clean + +# === Hilfe === +help: + @echo "\n⚠ - Noch nicht implementiert!\n" + + +.PHONY: all toc epub check-python pdf html docx preview clean diff --git a/NOTES.md b/NOTES.md new file mode 100644 index 0000000..7f7f4ba --- /dev/null +++ b/NOTES.md @@ -0,0 +1 @@ +# Notizen des Autors diff --git a/README.md b/README.md index 5f35ddd..973282b 100644 --- a/README.md +++ b/README.md @@ -1,20 +1,31 @@ -# eBook Vorlage +# Vorlage eBook -![Buch-Logo](./media/logo/logo_256x256.png) +![Buch-Logo](./media/logo/logo.png) ## Inhalt -- [eBook Vorlage](#ebook-vorlage) +- [Vorlage eBook](#vorlage-ebook) - [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) --- @@ -27,36 +38,37 @@ ```plaintext -book/ -│ -├── manuscript/ # Hauptinhalt in Markdown-Dateien -│ ├── 00_vorwort.md -│ ├── 01_einleitung.md -│ ├── 02_kapitel1.md -│ ├── ... -│ └── 99_anhang.md -│ -├── media/ # Bilder, Grafiken, Diagramme usw. -│ ├── kapitel1/ -│ │ └── bild1.png -│ └── kapitel2/ -│ └── diagramm.svg -│ -├── styles/ # Pandoc-Templates, LaTeX-Vorlagen, CSS -│ ├── ebook-template.tex -│ ├── ebook.css -│ └── print-template.tex -│ -├── build/ # Ausgabeordner (wird vom Build-Prozess befüllt) -│ -├── metadata/ # Metadaten für eBook, Titelblatt, Autoreninfo -│ ├── title.txt -│ ├── author.txt -│ └── ebook.yaml -│ -├── Makefile # Automatisierter Build-Prozess mit Pandoc etc. -├── README.md # Projektdokumentation -└── LICENSE # Lizenz für das Buch (z. B. CC-BY) +📁 . # +├── 📁 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) ``` @@ -70,20 +82,20 @@ book/ 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. +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. +>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:** +- **✅ Pandoc installieren:** ```sh sudo apt install pandoc ``` -- **✅ Empfohlene Installation: TeX Live Full** (ca.8GB) +- **✅ Empfohlene Installation: TeX Live Full** (ca.8GB) ```sh sudo apt install texlive-full @@ -116,19 +128,17 @@ Falls der Build trotzdem scheitert oder du dir den Aufwand sparen möchtest, lad Built for x86_64-pc-linux-gnu ``` +#### Schriftarten + +```sh +sudo apt install fonts-noto-color-emoji fonts-firacode +sudo apt install fonts-symbola +``` + ### Templates -Informationen zu den Templates und ihre Konfiguration - #### PDF -- [x] Konfigurationsfile für die PDF-Aussgabe ist die [./styles/print-template.tex](./styles/print-template.tex) - - Dateiname für Einbandlogo erfolgt aus dieser Datei: - - ```tex - \includegraphics[width=0.3\textwidth]{media/logo/logo-einband.png} \\[2em] - ```` - #### eBook (epub) #### DOCX (Office/ Word) @@ -143,6 +153,98 @@ Schau mal ins [`Makefile`](./Makefile), dort findest Du einige Kandidaten um aus 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** + -> + +Oder `hexdump` aus: + +```sh +sudo apt install bsdmainutils +``` + --- ## Lizenz diff --git a/manuscript/00_deckblatt.md b/manuscript/00_deckblatt.md index e69de29..d75918c 100644 --- a/manuscript/00_deckblatt.md +++ b/manuscript/00_deckblatt.md @@ -0,0 +1,76 @@ +# Informationen zu dieser Ausgabe {-} + +- **Dieses Buch hat digitale Anlagen zum Download** +- **Diese findest Du hier:** + + +--- + +- **Updates:** + + Auf dem Cover dieses Buchs im PDF-Format, findest Du eine `Buildversion`. + Diese gibt Dir Auskunft wie aktuell Deine Ausgabe ist. + Kleine Änderungen und Berichtigungen, werden in der Onlineversion sofort durchgeführt und Du kannst diese herunterladen. + Mit jeder vollen Versionsbezeichnung, gibt es eine neue Printversion des Buchs (1.0.0 ... 2.0.0 etc.). + +--- + +- **Information zur Buildversion des Buchs** + +```plaintext + v1.0.0 + │ │ └─ Fehlerkorrektur + │ └─── Inhaltliche Änderung + └───── Erweiterung, neues Kapitel +``` + +## LaTEx und Pandoc tests {-} + +Nachfolgend ein paar Tests, die eigentlich nur wärend der Entwicklung dieses Buchs hier vorhanden sein sollten. + +- **Fußnote - Test[^test]** + +[^test]: Diese Ausgabe sollte als Fussnote erscheinen. + +--- + +\newpage + +- **Codebeispiele** + Ich versuche Codebeispiele, die länger als 2-3 Zeilen sind stets auf einer neuen Seite zu beginnen. + + ```rust + let test: i16 = 4711; + + pub fn add(left: u64, right: u64) -> u64 { + left + right + } + + #[cfg(test)] + mod tests { + use super::*; + + #[test] + fn it_works() { + let result = add(2, 2); + assert_eq!(result, 4); + } + } + ``` + +--- + +- **Symboltest** + + - Symbole normal: + ✓ ✗ ⚠ ➤ ✎ ☑ + + - Symbole im Codeblock: + + ```text + ✓ ✗ ⚠ ➤ ✎ ☑ + ``` + +Es folgt ein Seitenumbruch: + +\newpage diff --git a/manuscript/05_vorwort.md b/manuscript/05_vorwort.md index 42746ae..889524e 100644 --- a/manuscript/05_vorwort.md +++ b/manuscript/05_vorwort.md @@ -1,3 +1,5 @@ -# Vorwort +# Vorwort {-} -Vorwort ... +Vorwort + +\newpage diff --git a/manuscript/10_Einfuegung.md b/manuscript/10_Einfuegung.md new file mode 100644 index 0000000..1551402 --- /dev/null +++ b/manuscript/10_Einfuegung.md @@ -0,0 +1,67 @@ +# Einführung + +Einführung + +## Hinweise + +### Warnhinweise zum Arbeiten mit elektrischem Strom + +**Achtung! Lebensgefahr durch elektrischen Strom.** +Alle in diesem Buch beschriebenen Experimente und Aufbauten dürfen nur unter Einhaltung anerkannter Sicherheitsregeln durchgeführt werden. +Sie richten sich ausschließlich an Personen mit elektrotechnischen Grundkenntnissen oder unter Aufsicht sachkundiger Personen. + +#### Allgemeine Sicherheitshinweise + +- Bereits Spannungen ab **50 V AC** oder **120 V DC** gelten nach DIN VDE 0100-410 als **gefährlich für Menschen**. +- Auch **niedrigere Spannungen** können bei bestimmten Bedingungen (z. B. feuchte Haut, Metallkontakt) lebensbedrohlich sein. +- **Elektrische Energie ist unsichtbar und geruchslos** – das macht Fehler besonders gefährlich. + +#### Gesetzliche Grundlagen + +- **DGUV Vorschrift 3** (ehemals BGV A3): Unfallverhütungsvorschrift „Elektrische Anlagen und Betriebsmittel“. +- **DIN VDE 0100**, **VDE 0105-100**, sowie **EN 50110-1**: Bestimmungen für den Betrieb elektrischer Anlagen. +- **Straf- und zivilrechtliche Konsequenzen** sind möglich bei Missachtung der Sicherheitsregeln. + +#### Die 5 Sicherheitsregeln nach VDE 0105-100 + +Jede Arbeit an elektrischen Anlagen darf **nur bei Einhaltung dieser Regeln** durchgeführt werden: + +1. **Freischalten** + - Stromkreis allpolig abschalten (z. B. Leitungsschutzschalter). +2. **Gegen Wiedereinschalten sichern** + - Schalter mit Schloss oder Hinweisschild sichern. +3. **Spannungsfreiheit feststellen** + - Mit einem geeigneten zweipoligen Spannungsprüfer prüfen. +4. **Erden und kurzschließen** + - Besonders bei Mittel- und Hochspannung unverzichtbar. +5. **Benachbarte, unter Spannung stehende Teile abdecken oder abschranken** + - Gefahren aus dem Umfeld ausschließen. + +#### Zusätzliche Hinweise für Experimente + +- Experimente nur auf **nicht leitfähigem Untergrund** durchführen. +- **Netzspannung (230 V/400 V)** darf **niemals direkt** verwendet werden – nur galvanisch getrennte Kleinspannungsquellen (z. B. Labornetzgeräte, Akkus). +- Bei **Baugruppen mit Netzanschluss**: immer **Trenntrafo** oder **FI-Schutzschalter** mit geringem Auslösestrom (≤ 30 mA) einsetzen. +- **Kinder und Jugendliche** dürfen Experimente nur unter Aufsicht durchführen. + +#### Persönliche Schutzausrüstung (PSA) + +- Isolierende Handschuhe +- Schutzbrille (bei Funkengefahr) +- Rutschfeste Schuhe mit isolierender Sohle +- Ggf. antistatische Arbeitskleidung + +#### Haftungsausschluss + +Der Autor übernimmt **keine Haftung für Personen- oder Sachschäden**, die durch unsachgemäßen Aufbau, Nachbau oder Missachtung geltender Vorschriften entstehen. + +> **Sicherheit steht immer an erster Stelle.** + +#### Quellen / weiterführende Literatur + +- DGUV Vorschrift 3 – [https://publikationen.dguv.de](https://publikationen.dguv.de) +- DIN VDE 0105-100: Betrieb von elektrischen Anlagen +- VDE-Schriftenreihe: Sicherheit in der Elektrotechnik +- EN 50110-1: Betrieb elektrischer Anlagen – Europäische Norm + +\newpage diff --git a/manuscript/20_kapitel2.md b/manuscript/20_kapitel2.md deleted file mode 100644 index b45cf91..0000000 --- a/manuscript/20_kapitel2.md +++ /dev/null @@ -1,7 +0,0 @@ -# Kapitel 2 - -Kapitel 2 - -## Unterkapitel 2.1 - -Unterkapitel diff --git a/manuscript/30_kapitel2.md b/manuscript/30_kapitel2.md deleted file mode 100644 index c6602f0..0000000 --- a/manuscript/30_kapitel2.md +++ /dev/null @@ -1,3 +0,0 @@ -# Kapitel 3 - -## Unterkapitel 3 diff --git a/manuscript/90_Glossar.md b/manuscript/90_Glossar.md new file mode 100644 index 0000000..33fc80d --- /dev/null +++ b/manuscript/90_Glossar.md @@ -0,0 +1,3 @@ +# Glossar {-} + +Glossar optional diff --git a/media/icon.png b/media/icon.png new file mode 100644 index 0000000..be0262a Binary files /dev/null and b/media/icon.png differ diff --git a/media/logo/logo.png b/media/logo/logo.png new file mode 100644 index 0000000..4a23ae8 Binary files /dev/null and b/media/logo/logo.png differ diff --git a/media/logo/logo_512x512.png b/media/logo/logo_512x512.png new file mode 100644 index 0000000..fe430d3 Binary files /dev/null and b/media/logo/logo_512x512.png differ diff --git a/metadata/author.txt b/metadata/author.txt index b242a68..bedb31d 100644 --- a/metadata/author.txt +++ b/metadata/author.txt @@ -1,10 +1,7 @@ -Adam Skotarczak -Elektroniker, Programmierer, Tüftler +Autor: Adam Skotarczak +Beschreibung: Elektroniker, CAD-Konstrukteur und FullStack Programmierer Node.js und Rust -Autor dieses Buches mit Fokus auf praxisnahe Softwareentwicklung, Systemintegration und moderne Technologien. -Besonderes Interesse gilt dem Zusammenspiel aus effizientem Code, durchdachtem Design und reproduzierbaren Workflows – bevorzugt unter Linux. +Kontakt: elektrotechnik-buch@skotarczak.net +Web: https://local.ionivation.com/realAscot/handbuch-elektrotechnik -Kontakt: adam@skotarczak.net -Web: https://www.ionivation.com - -© 2025 Adam Skotarczak. Alle Rechte vorbehalten. +© 2025 - Autor. Alle Rechte vorbehalten. diff --git a/metadata/ebook.yaml b/metadata/ebook.yaml index 2d8ae7c..0967268 100644 --- a/metadata/ebook.yaml +++ b/metadata/ebook.yaml @@ -1,8 +1,8 @@ -title: "Vorlage eBook: Titel aus ebook.yaml" -subtitle: "Untertitel aus ebook.yaml - Logo aus .tex" +title: "Elektrotechnik - Elektronik" +subtitle: "für Hobby, DIY und Beruf" author: "Adam Skotarczak" lang: de-DE -rights: "© 2000 Adam Skotarczak. CC BY-SA 4.0" -date: 2000-01-01 +rights: "© 2025 Adam Skotarczak. CC BY-SA 4.0" +date: 2025-01-01 description: | - Dieses Buch ist eine Vorlage. + Handbuch für Elektrotechnik und Elektronik. diff --git a/styles/print-template.tex b/styles/print-template.tex index 6dda64b..9094d59 100644 --- a/styles/print-template.tex +++ b/styles/print-template.tex @@ -1,16 +1,29 @@ +% Tex Template für Rust Handbuch + \documentclass[11pt,a4paper]{article} +% Workaround für Pandoc: tightlist definieren +\providecommand{\tightlist}{% + \setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}} + \usepackage{xfp} % <-- ganz nach oben! \usepackage{expl3} % <-- optional, bei manchen TeX-Installationen nötig +% Schriftarten \usepackage{fontspec} \setmainfont{DejaVu Sans} +\setmonofont{DejaVu Sans Mono} +%\setmonofont{Symbola} +%\setmonofont{Fira Code} +%\newfontfamily\emoji{Noto Color Emoji} \usepackage[ngerman]{babel} \usepackage{parskip} \usepackage{geometry} \geometry{margin=2.5cm} \usepackage{graphicx} +\usepackage[utf8]{inputenc} +\usepackage{xcolor} \usepackage{titlesec} \usepackage{fancyhdr} \usepackage{hyperref} @@ -18,6 +31,13 @@ \usepackage{longtable} \usepackage{booktabs} \usepackage{calc} +\usepackage{amssymb} % Mathematische Sonderzeichen wie \boxtimes, \triangle +\usepackage{pifont} % Dingbats (z. B. \ding, \XSolidBrush) +\usepackage{marvosym} % Zusätzliche Symbole wie \CircledR +\usepackage{wasysym} % Wetter-, Smileys und andere graphische Symbole + +% Verzeichnistiefe (aus Makefile TOCDEEP) +\setcounter{tocdepth}{$toc-depth$} % Fallback-Makros für Pandoc Highlighting $if(highlighting-macros)$ @@ -35,14 +55,23 @@ $endif$ % Titel \title{ - \includegraphics[width=0.3\textwidth]{media/logo/logo_256x256.png} \\[2em] + \includegraphics[width=0.3\textwidth]{media/logo/logo.png} \\[2em] {\Huge $title$} \\ \vspace{1em} \Large $subtitle$ } \author{$for(author)$$author$$sep$ \and $endfor$} -\date{$date$} +\date{ + $date$\\ + \vspace{1ex} + {\color{gray}\small Buildversion: v$version$ ($buildmode$)} +} + +% --- Schriftart für Codeblöcke verkleinern --- +\makeatletter +\def\verbatim@font{\scriptsize\ttfamily} +\makeatother \begin{document} diff --git a/tools/cli-emojis.md b/tools/cli-emojis.md index 0c889c1..546413b 100644 --- a/tools/cli-emojis.md +++ b/tools/cli-emojis.md @@ -1,18 +1,8 @@ -# 📁 CLI Emojis (CLI Programmer Emojis) +# CLI Emojis (CLI Programmer Emojis) -> Adam Skotarczak private Emojis for monochrome Display - Diese Liste ist Teil des "Become-Writer-Projekt" +> Adam Skotarczak private Emojis for monochrome Display -## 📁 Inhalt - -- [📁 CLI Emojis (CLI Programmer Emojis)](#-cli-emojis-cli-programmer-emojis) - - [📁 Inhalt](#-inhalt) - - [📝 Commonly Used Emoji for CLI/Terminal Applications](#-commonly-used-emoji-for-cliterminal-applications) - - [📝 1-2 Bye - Unicode Basic Symbols for CLI or Monochrome Safe Emojis](#-1-2-bye---unicode-basic-symbols-for-cli-or-monochrome-safe-emojis) - - [📁 Anleitung: Unicode in CLI-Programmen richtig behandeln](#-anleitung-unicode-in-cli-programmen-richtig-behandeln) - - [📝 Wichtig für CLI-Projekte:](#-wichtig-für-cli-projekte) - -## 📝 Commonly Used Emoji for CLI/Terminal Applications +## Commonly Used Emoji for CLI/Terminal Applications Eine Liste von Emojis, die in fast jeder CLI (Terminal/Konsole) problemlos funktionieren, weil sie UTF-8 kompatibel sind und keine Sonderbehandlungen wie Farbcodes brauchen: @@ -57,7 +47,7 @@ Eine Liste von Emojis, die in fast jeder CLI (Terminal/Konsole) problemlos funkt --- -## 📝 1-2 Bye - Unicode Basic Symbols for CLI or Monochrome Safe Emojis +## 1-2 Bye - Unicode Basic Symbols for CLI or Monochrome Safe Emojis **CLI-Safe Unicode Symbols oder Terminal-Safe Emojis.** @@ -113,9 +103,9 @@ Eine minimalistische Emoji-Liste (nur mit extrem simplen Unicode-Symbolen, oft 1 --- -## 📁 Anleitung: Unicode in CLI-Programmen richtig behandeln +## Anleitung: Unicode in CLI-Programmen richtig behandeln -### 📝 Wichtig für CLI-Projekte: +### Wichtig für CLI-Projekte - **Python**: Sicherstellen, dass `stdout` auf UTF-8 eingestellt ist (sonst Encoding-Fehler möglich): diff --git a/tools/gitcopy.bat b/tools/gitcopy.bat new file mode 100644 index 0000000..e1d5b5b --- /dev/null +++ b/tools/gitcopy.bat @@ -0,0 +1,161 @@ +@echo off +setlocal enabledelayedexpansion +chcp 65001 >nul + +REM Skript, um aus einem Projekt mit git-repo, ein portables .zip zu erstellen +REM +REM (C) 2025 MIT - Adam Skotarczak +REM +REM Version: v1.1.2 +REM Github: https://github.com/realAscot/gitcopy +REM ------------------------------------------------------------------- + + +rem --- Git-Verfügbarkeit prüfen --- +where git >nul 2>nul +if errorlevel 1 ( + echo. + echo [⚠️] Git ist nicht installiert oder nicht im PATH. + echo [📦] Bitte installiere Git von https://git-scm.com/download/win + call :show_help + echo. + exit /b 1 +) + +rem --- Git-Version anzeigen --- +for /f "tokens=*" %%i in ('git --version') do set "GIT_VERSION=%%i" + +if defined GIT_VERSION ( + echo. + echo [✅] Gefundene Git-Version: %GIT_VERSION% +) else ( + echo([⚠️] Konnte Git-Version nicht ermitteln. +) + +rem Prüfe auf optionalen Parameter "--debug" +set DEBUG=0 + +if NOT "%~1"=="" ( + if "%~1"=="--debug" ( + set DEBUG=1 + echo [⚠️] Debug-Modus aktiv: Ignoriere offene Commits. + exit /b 0 + ) else if "%~1"=="-d" ( + set DEBUG=1 + echo [⚠️] Debug-Modus aktiv: Ignoriere offene Commits. + exit /b 0 + ) else if "%~1"=="-h" ( + call :show_help + exit /b 0 + ) else if "%~1"=="--help" ( + call :show_help + exit /b 0 + ) else ( + rem Parameter vorhanden aber nicht erkannt. + call :kein_Parameter "%~1" + exit /b 1 + ) +) else ( + call :go "%~1" +) + +exit /b 0 + +:go + +call :generate_timestamp +set ZIP_NAME=projektarchiv-%TIMESTAMP%.zip + +rem ------------------------------------------------------------------- + +pushd %~dp0 + +if %DEBUG%==0 ( + echo [🔍] Prüfe auf uncommitted oder ungetrackte Änderungen... + set "hasChanges=" + for /f "delims=" %%i in ('git status --porcelain') do ( + set "hasChanges=1" + goto :has_changes + ) + echo [✅] Arbeitsverzeichnis ist sauber. +) else ( + echo [⚠️] Prüfschritt übersprungen. +) + +goto :create_zip + +:has_changes +echo. +echo [⚠️] Es sind uncommitted oder ungetrackte Änderungen vorhanden: +echo. +git status --short +echo. +echo [❌] Bitte committe oder stash diese Änderungen, bevor du ein ZIP erstellst. +echo [⚠️] versuche --debug um diese Prüfung zu umgehen aber dann wird das Archiv unvollständig. +echo. +endlocal +pause +exit /b 1 + +:create_zip +echo [💾] Erstelle ZIP-Archiv von HEAD... +git archive --format=zip --output="%ZIP_NAME%" HEAD +if errorlevel 1 ( + echo [⚠️] Fehler beim Erstellen des Archivs. + pause + exit /b 1 +) +echo [✅] Archiv erfolgreich erstellt: %CD%\%ZIP_NAME% +popd +endlocal +pause +exit /b 0 + +:generate_timestamp +rem Erzeugt einen Zeitstempel TTMMJJHHMM sicher und universell +for /f "tokens=1-4 delims=. " %%d in ('echo %DATE%') do ( + set "TAG=0%%d" + set "MONAT=0%%e" + set "JAHR=%%f" +) + +for /f "tokens=1-2 delims=: " %%g in ('echo %TIME%') do ( + set "STUNDE=0%%g" + set "MINUTE=0%%h" +) + +set "TAG=!TAG:~-2!" +set "MONAT=!MONAT:~-2!" +set "JAHR=!JAHR:~-2!" +set "STUNDE=!STUNDE:~-2!" +set "MINUTE=!MINUTE:~-2!" + +set "TIMESTAMP=!TAG!!MONAT!!JAHR!!STUNDE!!MINUTE!" +goto :eof + +:kein_Parameter +echo. +echo [⚠️] Unbekannter Parameter: "%~1" abbruch ... +echo. +call :show_help +exit /b 1 + +:show_help +echo. +echo ℹ️ GitCopy – Hilfe +echo ===================== +echo Erstellt ein ZIP-Archiv vom aktuellen HEAD-Stand des Git-Repositories. +echo (C) MIT 2025 - Adam Skotarczak +echo. +echo Verwendung: +echo gitcopy.bat [Option] +echo. +echo Optionen: +echo --debug / -d Überspringt die Prüfung auf uncommitted oder ungetrackte Änderungen. +echo -h / --help Zeigt diese Hilfe an. +echo. +endlocal +pause +goto :eof + +endlocal \ No newline at end of file diff --git a/tools/tocgen.py b/tools/tocgen.py new file mode 100644 index 0000000..97d1263 --- /dev/null +++ b/tools/tocgen.py @@ -0,0 +1,75 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- + +import argparse + +"""tocgen.py + + Erstellt aus einem vordefinierten Verzeichnis mit Markdown-Dateien ein Inhaltsverzeichnis. + + (C) 2025 - Adam Skotarczak - Version: 1.0.0 - stand 20/05/2025 +""" + +MANUSKRIPT_DIR = "manuscript" +OUTPUT_PATH = "INHALT2.md" + +from pathlib import Path +import re + +def slugify(text): + return re.sub(r"[^\w\- ]", "", text.lower()).strip().replace(" ", "-") + +def parse_headings(md_file: Path, max_level=3): + lines = md_file.read_text(encoding="utf-8").splitlines() + headings = [] + in_codeblock = False + + for line in lines: + # Umschalten bei ```, egal ob mit oder ohne Sprache + if line.strip().startswith("```"): + in_codeblock = not in_codeblock + continue + if in_codeblock: + continue + + match = re.match(r"^(#{1,3})\s+(.*)", line) + if match: + level = len(match.group(1)) + if level <= max_level: + title = match.group(2).strip() + anchor = slugify(title) + headings.append((level, title, anchor)) + return headings + +def main(): + parser = argparse.ArgumentParser( + description="Erstellt aus einem Verzeichnis mit Markdown-Dateien ein Inhaltsverzeichnis." + ) + parser.add_argument( + "-d", "--dir", default=MANUSKRIPT_DIR, help="Verzeichnis mit Markdown-Dateien (Standard: manuscript)" + ) + parser.add_argument( + "-o", "--output", default=OUTPUT_PATH, help="Pfad für die Ausgabedatei (Standard: INHALT.md)" + ) + args = parser.parse_args() + + generate_toc(args.dir, args.output) + +def generate_toc(manuskript_dir=MANUSKRIPT_DIR, output_path=OUTPUT_PATH): + manuskript_dir = Path(manuskript_dir) + index_path = Path(output_path) + toc_lines = ["# **Inhalt**\n"] + + for md_file in sorted(manuskript_dir.glob("*.md")): + rel_path = md_file.as_posix() + headings = parse_headings(md_file) + for level, title, anchor in headings: + indent = " " * (level - 1) + link = f"{rel_path}#{anchor}" if level > 1 else rel_path + toc_lines.append(f"{indent}- [{title}]({link})") + + index_path.write_text("\n".join(toc_lines) + "\n", encoding="utf-8") + +if __name__ == "__main__": + main() +