diff --git a/Makefile b/Makefile index d8daa33..c95d228 100644 --- a/Makefile +++ b/Makefile @@ -45,12 +45,32 @@ YELLOW = \033[1;33m BLUE = \033[0;34m NC = \033[0m # No Color +# Docker Compose command detection +# Support both docker-compose (standalone) and docker compose (plugin) +DOCKER_COMPOSE := $(shell command -v docker-compose 2> /dev/null) +ifdef DOCKER_COMPOSE + DOCKER_COMPOSE_CMD = docker-compose + DOCKER_COMPOSE_TYPE = standalone +else + DOCKER_COMPOSE_CMD = docker compose + DOCKER_COMPOSE_TYPE = plugin +endif + +# Docker availability check +DOCKER_AVAILABLE := $(shell command -v docker 2> /dev/null) + # ------------------------------------------------------------------------------ # Main Targets # ------------------------------------------------------------------------------ +# Default target: Use Docker for compilation if available .PHONY: all -all: compile view - @echo -e "$(GREEN)✓ Document built and opened successfully$(NC)" +all: docker-build + @echo -e "$(GREEN)✓ Document built successfully using Docker$(NC)" + +# Alternative: Local build without Docker +.PHONY: local +local: compile view + @echo -e "$(GREEN)✓ Document built and opened successfully (local)$(NC)" .PHONY: compile compile: @@ -76,6 +96,79 @@ view: exit 1; \ fi +# ------------------------------------------------------------------------------ +# Docker Targets +# ------------------------------------------------------------------------------ +.PHONY: docker-info +docker-info: + @echo -e "$(BLUE)=== Docker Configuration ===$(NC)" + @if command -v docker >/dev/null 2>&1; then \ + echo -e "$(GREEN)✓ Docker:$(NC) $$(docker --version | cut -d' ' -f3 | tr -d ',')"; \ + else \ + echo -e "$(RED)✗ Docker:$(NC) Not found"; \ + fi + @echo -e "$(GREEN)✓ Docker Compose:$(NC) $(DOCKER_COMPOSE_CMD) ($(DOCKER_COMPOSE_TYPE))" + @if command -v docker >/dev/null 2>&1 && docker info >/dev/null 2>&1; then \ + echo -e "$(GREEN)✓ Docker Daemon:$(NC) Running"; \ + echo -e "$(GREEN)✓ Containers:$(NC) $$(docker ps -q | wc -l) running, $$(docker ps -aq | wc -l) total"; \ + echo -e "$(GREEN)✓ Images:$(NC) $$(docker images -q | wc -l) available"; \ + else \ + echo -e "$(YELLOW)⚠ Docker Daemon:$(NC) Not running or not accessible"; \ + fi + @echo "" + +.PHONY: check-docker +check-docker: + @command -v docker >/dev/null 2>&1 || { \ + echo -e "$(RED)✗ Docker is not installed or not in PATH$(NC)"; \ + echo -e "$(YELLOW) Please install Docker from https://docs.docker.com/get-docker/$(NC)"; \ + exit 1; \ + } + @docker info >/dev/null 2>&1 || { \ + echo -e "$(RED)✗ Docker daemon is not running$(NC)"; \ + echo -e "$(YELLOW) Please start Docker Desktop or the Docker daemon$(NC)"; \ + exit 1; \ + } + @echo -e "$(GREEN)✓ Docker is available$(NC)" + @echo -e "$(YELLOW)→ Using Docker Compose command: $(DOCKER_COMPOSE_CMD)$(NC)" + +.PHONY: docker-build +docker-build: check-docker + @echo -e "$(BLUE)=== Building LaTeX Document with Docker ===$(NC)" + @echo -e "$(YELLOW)→ Starting Docker container...$(NC)" + @$(DOCKER_COMPOSE_CMD) up --build || { \ + echo -e "$(RED)✗ Docker build failed$(NC)"; \ + echo -e "$(YELLOW) Try 'make docker-clean' and rebuild$(NC)"; \ + exit 1; \ + } + @echo -e "$(GREEN)✓ Docker build completed$(NC)" + @echo -e "$(GREEN)✓ PDF created: $(PDF_TARGET)$(NC)" + +.PHONY: docker-build-cached +docker-build-cached: check-docker + @echo -e "$(BLUE)=== Building LaTeX Document with Docker (cached) ===$(NC)" + @echo -e "$(YELLOW)→ Starting Docker container (using cache)...$(NC)" + @$(DOCKER_COMPOSE_CMD) up || { \ + echo -e "$(RED)✗ Docker build failed$(NC)"; \ + echo -e "$(YELLOW) Try 'make docker-build' to rebuild the image$(NC)"; \ + exit 1; \ + } + @echo -e "$(GREEN)✓ Docker build completed$(NC)" + +.PHONY: docker-clean +docker-clean: check-docker + @echo -e "$(YELLOW)→ Removing Docker containers...$(NC)" + @$(DOCKER_COMPOSE_CMD) down --remove-orphans || true + @echo -e "$(GREEN)✓ Docker containers removed$(NC)" + +.PHONY: docker-shell +docker-shell: check-docker + @echo -e "$(BLUE)→ Opening shell in Docker container...$(NC)" + @$(DOCKER_COMPOSE_CMD) run --rm --entrypoint /bin/bash latex || { \ + echo -e "$(RED)✗ Failed to start Docker shell$(NC)"; \ + exit 1; \ + } + # ------------------------------------------------------------------------------ # Clean Targets # ------------------------------------------------------------------------------ @@ -204,11 +297,20 @@ help: @echo -e "===============================================================================$(NC)" @echo "" @echo -e "$(GREEN)Main Targets:$(NC)" - @echo " make - Build document and open PDF" - @echo " make compile - Build the LaTeX document" + @echo " make - Build document using Docker (default)" + @echo " make local - Build document locally and open PDF" + @echo " make compile - Build the LaTeX document (local)" @echo " make full - Clean and rebuild everything" @echo " make view - Open the PDF file" @echo "" + @echo -e "$(GREEN)Docker Targets:$(NC)" + @echo " make docker-info - Show Docker configuration and status" + @echo " make check-docker - Check if Docker is available" + @echo " make docker-build - Build with Docker (rebuild image)" + @echo " make docker-build-cached - Build with Docker (use cached image)" + @echo " make docker-shell - Open shell in Docker container" + @echo " make docker-clean - Remove Docker containers" + @echo "" @echo -e "$(GREEN)Chapter Management:$(NC)" @echo " make chapter NUM=02 NAME=methodology - Create a new chapter" @echo " make chapters - List all chapters" @@ -237,5 +339,5 @@ help: @echo " make show-chapter NAME=01_introduction" @echo "" -# Default target -.DEFAULT_GOAL := help +# Default target - use Docker build +.DEFAULT_GOAL := all diff --git a/README.md b/README.md index 367244c..7c3019b 100644 --- a/README.md +++ b/README.md @@ -25,15 +25,29 @@ The HSRTReport class is a customized LaTeX document class based on KOMA-Script's - **Professional Typography**: Configured for optimal readability with proper font settings - **Automatic Title Page Generation**: Customizable title page with university branding -- **Bibliography Management**: Integrated BibLaTeX support for citations +- **Bibliography Management**: Integrated BibLaTeX support for APA-style citations - **Glossary Support**: Built-in glossary and acronym management -- **Code Highlighting**: Syntax highlighting for source code listings +- **Code Highlighting**: Syntax highlighting for multiple programming languages - **Word Count**: Automatic word counting functionality - **Cross-referencing**: Smart referencing with hyperref +- **Advanced Page Break Control**: Intelligent section and listing page break management +- **Docker Support**: Containerized build environment for consistent compilation +- **Enhanced Spacing**: Optimized vertical spacing for sections and subsections +- **Smart TOC Grouping**: Automatic chapter grouping in table of contents ## 🔧 Prerequisites -### Required Software +### Option 1: Docker (Recommended) + +- **Docker**: [Install Docker](https://docs.docker.com/get-docker/) +- **Docker Compose**: Supports both variants: + - `docker-compose` (standalone tool) + - `docker compose` (Docker plugin, included with Docker Desktop) + - The Makefile automatically detects which version is available + +This is the easiest way to get started, as all LaTeX dependencies are handled automatically in a container. + +### Option 2: Local Installation - **XeLaTeX**: This template requires XeLaTeX for compilation (included in most TeX distributions) - **TeX Distribution**: One of the following: @@ -41,6 +55,7 @@ The HSRTReport class is a customized LaTeX document class based on KOMA-Script's - [MiKTeX](https://miktex.org/) (Windows) - [MacTeX](https://www.tug.org/mactex/) (macOS) - **GNU make**: Automates compilation and cleaning tasks +- **Inkscape**: For SVG to PDF conversion (optional, but needed for SVG graphics) ### Required LaTeX Packages @@ -103,6 +118,7 @@ SAT-WiSe-25-26/ ├── Main.bib # Bibliography database ├── Makefile # Build automation ├── .latexmkrc # Latexmk configuration +├── docker-compose.yml # Docker configuration └── QUICKSTART.md # Quick start guide ``` @@ -232,23 +248,52 @@ Removes the chapter and creates a backup in `.chapter_backups/`. ## 🔨 Building the Document -### Using Make (Recommended) +### Using Docker (Recommended - Default) + +The template now uses Docker by default for consistent builds across all platforms. The Makefile automatically detects whether you have `docker-compose` (standalone) or `docker compose` (plugin) installed: ```bash -# Full build with bibliography and glossary – open after +# Show Docker configuration and which compose variant is used +make docker-info + +# Default build using Docker make -# Just build +# Docker build with image rebuild (after Dockerfile changes) +make docker-build + +# Docker build using cached image (faster) +make docker-build-cached + +# Open shell in Docker container for debugging +make docker-shell + +# Clean Docker containers +make docker-clean +``` + +### Using Local Installation + +If you have a local LaTeX installation: + +```bash +# Local build with automatic PDF viewing +make local + +# Just compile without opening make compile # Clean auxiliary files make clean + +# Full clean including output +make distclean ``` -### Using latexmk +### Using latexmk directly ```bash -latexmk -xelatex -bibtex Main.tex +latexmk -xelatex -shell-escape -bibtex Main.tex ``` ## 🐛 Troubleshooting @@ -258,15 +303,29 @@ latexmk -xelatex -bibtex Main.tex 1. **"This class can only be used with XeLaTeX" error** - Solution: Ensure you're using XeLaTeX, not pdfLaTeX - Check your editor's compiler settings + - Use Docker build (`make`) to avoid this issue 2. **Bibliography not appearing** - Run `biber Main` after the first XeLaTeX compilation - Check for errors in `Main.bib` + - The Docker build handles this automatically 3. **Glossary entries not showing** - Run `makeglossaries Main` after adding new entries - Ensure entries are referenced in the document using `\gls{term}` +4. **Docker build not working** + - Ensure Docker Desktop is running + - Run `make docker-info` to check your Docker setup + - Check that port is not blocked by firewall + - Try `docker-compose build --no-cache` or `docker compose build --no-cache` for a fresh build + - The Makefile supports both `docker-compose` and `docker compose` automatically + +5. **SVG images not converting** + - Inkscape is required for SVG support + - Docker build includes Inkscape automatically + - For local builds: Install Inkscape separately + ## 📄 License This template is licensed under the Creative Commons Attribution-ShareAlike 4.0 International License (CC BY-SA 4.0). @@ -290,4 +349,26 @@ For questions, issues, or suggestions: --- -*Last updated: October 2025* +## 🆕 Recent Updates + +### Version 2.0 (October 2024) +- Added Docker support for containerized compilation +- Implemented advanced page break control system +- Enhanced section spacing (4.5ex before sections, 3.5ex before subsections) +- Added smart TOC chapter grouping for short chapters +- Updated header format with em-dash separator (e.g., "1 – Introduction") +- Fixed page numbering (TOC now starts at page 1) +- Added comprehensive bibliography with academic writing references +- Improved listing and itemize environment protection from page breaks + +### Key Configuration Changes +- **Page Margins**: Unified 2cm on all sides +- **Base Font Size**: 11pt +- **Line Spacing**: 1.5x (`baselinestretch=1.5`) +- **Paragraph Spacing**: 6pt +- **Section Minimum Content**: 12 baseline skips (~2 paragraphs) +- **Citation Style**: APA format via BibLaTeX + +--- + +*Last updated: October 2024* diff --git a/docker-compose.yml b/docker-compose.yml index e4426c6..bf024ba 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -1,14 +1,50 @@ +# ============================================================================== +# Docker Compose Configuration for LaTeX Compilation +# ============================================================================== +# Description: This Docker Compose file sets up a containerized LaTeX build +# environment with all necessary dependencies for compiling the +# HSRTReport template documents. +# Usage: docker-compose up (or make docker-build) +# ============================================================================== + services: + # ------------------------------------------------------------------------------ + # LaTeX Compilation Service + # ------------------------------------------------------------------------------ + # This service provides a complete TeXLive environment for document compilation latex: + # Base image: Full TeXLive distribution (latest version) + # Note: The image line is commented out because we're using a custom build #image: texlive/texlive:latest + + # Custom build configuration to add additional dependencies build: + # Build context is the current directory context: . + # Inline Dockerfile definition for additional packages dockerfile_inline: | + # Start from the full TeXLive image (includes XeLaTeX, Biber, etc.) FROM texlive/texlive:latest + + # Update package lists to ensure we get the latest versions RUN apt update -y + + # Install Inkscape for SVG to PDF conversion + # Required for processing SVG graphics in the document RUN apt install inkscape -y + + # Volume mappings volumes: + # Mount the entire project directory to /data in the container + # This allows the container to access all project files and write outputs - ./:/data + + # Working directory configuration + # Previous project-specific path (kept for reference): # working_dir: /data/Projektbeschreibung-MKI-METI-Projekt + # Current: Set to /data root for general use working_dir: /data + + # Default command when container starts + # Executes 'make compile' to build the LaTeX document entrypoint: ["make", "compile"]