# HSRTReport LaTeX Template

[![Build LaTeX Document](https://github.com/frederikbeimgraben/HSRT-Report/actions/workflows/release.yml/badge.svg)](https://github.com/frederikbeimgraben/HSRT-Report/actions/workflows/release.yml)
[![GitHub release](https://img.shields.io/github/release/frederikbeimgraben/HSRT-Report.svg)](https://github.com/frederikbeimgraben/HSRT-Report/releases/latest)
[![License: CC BY-SA 4.0](https://img.shields.io/badge/License-CC%20BY--SA%204.0-lightgrey.svg)](https://creativecommons.org/licenses/by-sa/4.0/)

A professional LaTeX report template for academic papers and theses at the University of Applied Sciences Reutlingen (Hochschule Reutlingen).

## 📋 Table of Contents

- [Overview](#-overview)
- [Features](#-features)
- [Prerequisites](#-prerequisites)
- [Installation](#-installation)
- [Project Structure](#-project-structure)
- [Usage](#-usage)
- [Document Class Options](#-document-class-options)
- [Customization](#-customization)
- [Building the Document](#-building-the-document)
- [Troubleshooting](#-troubleshooting)
- [License](#-license)

## 📖 Overview

The HSRTReport class is a customized LaTeX document class based on KOMA-Script's `scrreprt` class, specifically designed for creating professional academic reports, seminar papers, and bachelor/master theses at the University of Applied Sciences Reutlingen. It provides a consistent, professional layout with minimal configuration required.

## ✨ Features

- **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 APA-style citations
- **Glossary Support**: Built-in glossary and acronym management
- **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

### Option 1: Docker (Recommended)

- **ENV**: Copy the `.env.example` and rename it to `.env`
- **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:
  - [TeX Live](https://www.tug.org/texlive/) (Linux/Windows/macOS)
  - [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

The template automatically loads all necessary packages. Key dependencies include:
- KOMA-Script bundle
- BibLaTeX with Biber backend
- glossaries-extra
- fontspec (for font management)
- TikZ (for graphics)
- listings (for code)

## 📁 Project Structure

```sh
HSRT-Report/
│
├── HSRTReport/             # Document class files
│   ├── HSRTReport.cls      # Main class definition
│   ├── Assets/             # Fonts and images
│   │   ├── Fonts/          # Custom fonts
│   │   └── Images/         # Logo and graphics
│   ├── Config/             # Configuration modules
│   │   ├── Fonts.tex       # Font settings
│   │   ├── PageSetup.tex   # Page layout
│   │   └── ...             # Other configurations
│   ├── Imports/            # Package imports
│   │   ├── Core.tex        # Core packages
│   │   ├── Document.tex    # Document structure
│   │   └── ...             # Other imports
│   ├── Modules/            # Feature modules
│   │   ├── Content/        # Content-related features
│   │   ├── Layout/         # Layout features
│   │   └── Tools/          # Utility tools
│   └── Pages/              # Page templates
│       └── Titlepage.tex   # Title page definition
│
├── Content/                # Document content
│   ├── 00_toc.tex          # Table of contents and lists
│   ├── 01_content.tex      # Chapter loader (auto-managed)
│   ├── 99_bibliography.tex # Bibliography
│   ├── Chapters/           # Individual chapter files
│   │   ├── 01_introduction.tex
│   │   ├── example_chapter.tex
│   │   └── ...
│   └── Images/             # Document images
│
├── Settings/               # Document settings
│   ├── General.tex         # General settings
│   ├── CleverefNames.tex   # \cref names configuration
│   └── Logos.tex           # Logo configuration
│
├── scripts/                # Chapter management scripts
│   ├── create_chapter.sh   # Create new chapters
│   ├── list_chapters.sh    # List all chapters
│   ├── delete_chapter.sh   # Delete chapters
│   └── show_chapter.sh     # View chapter content
│
├── Main.tex                # Main document file
├── Preamble.tex            # Document preamble
├── Glossary.tex            # Glossary definitions
├── Main.bib                # Bibliography database
├── Makefile                # Build automation
├── .latexmkrc              # Latexmk configuration
└── docker-compose.yml      # Docker configuration
```

## 📝 Usage

### Basic Document Setup

1. **Configure document metadata** in `Settings/General.tex`:
   ```latex
   % Document title
   \title{Your Document Title}

   % Title page information
   \AddTitlePageDataLine{Thema}{Your Topic}
   \AddTitlePageDataLine{Vorgelegt von}{Your Name}
   \AddTitlePageDataLine{Studiengang}{Your Study Program}
   % ... additional fields
   ```

2. **Add your content** using one of these methods:
   - **Automatic (Recommended)**: Use scripts to manage chapters
     ```bash
     ./scripts/create_chapter.sh 02 methodology
     ./scripts/create_chapter.sh 03 results
     ./scripts/list_chapters.sh
     ```
   - **Manual**: Create files in `Content/Chapters/` and add them to `Content/01_content.tex`

3. **Manage bibliography** in `Main.bib` using BibTeX format (I recommend using a tool like [Zotero](https://www.zotero.org/))

4. **Define glossary entries** in `Glossary.tex`:
   ```latex
   \newglossaryentry{term}{
       name=Term,
       description={Description of the term}
   }

   \newacronym{abbr}{ABBR}{Full Form of Abbreviation}
   ```

## ⚙️ Document Class Options

The HSRTReport class accepts all standard KOMA-Script `scrreprt` options plus:

| Option | Description | Values |
|--------|-------------|---------|
| `paper` | Paper size | `a4`, `letter`, etc. |
| `fontsize` | Base font size | `10pt`, `11pt`, `12pt` |
| `oneside`/`twoside` | Page layout | Single or double-sided |
| `DIV` | Type area calculation | Integer (12-16 recommended) |
| `onecolumn`/`twocolumn` | Column layout | Single or double column |

## 🎨 Customization

### Modifying the Title Page

Edit `Settings/General.tex` to customize title page fields:
```latex
\AddTitlePageDataLine{Field Name}{Field Content}
\AddTitlePageDataSpace{5pt}  % Add vertical space
```

### Adding Custom Packages

Add custom packages to `Preamble.tex`:
```latex
\usepackage{yourpackage}
\yourpackagesetup{options}
```

### Changing Fonts

The template uses custom fonts defined in `HSRTReport/Config/Fonts.tex`. Modify this file to change fonts template-wide.

### Creating Custom Commands

Add custom commands to `Preamble.tex`:
```latex
\newcommand{\mycommand}[1]{#1}
```

## 📚 Chapter Management

### Automatic Chapter Management (Recommended)

The template includes scripts for efficient chapter management:

#### Create a New Chapter
```bash
./scripts/create_chapter.sh 02 methodology
```
This creates `Content/Chapters/02_methodology.tex` with a template structure and automatically adds it to the document.

#### List All Chapters
```bash
./scripts/list_chapters.sh
```
Shows all chapters and their inclusion status in the document.

#### View Chapter Content
```bash
./scripts/show_chapter.sh 02_methodology --info
./scripts/show_chapter.sh 02_methodology --structure
```

#### Delete a Chapter
```bash
./scripts/delete_chapter.sh 02_methodology
```
Removes the chapter and creates a backup in `.chapter_backups/`.

### Manual Chapter Management

1. Create a file in `Content/Chapters/`
2. Add `\input{Content/Chapters/your_chapter}` to the marked section in `Content/01_content.tex`

## 🔨 Building the Document

### 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
# Show Docker configuration and which compose variant is used
make docker-info

# Default build using Docker
make

# 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 directly

```bash
latexmk -xelatex -shell-escape -bibtex Main.tex
```

## 🚀 CI/CD Pipeline

### Continuous Integration

The project includes GitHub Actions workflows for automated building and testing:

#### Release Workflow (`release.yml`)
- **Triggers on:** Version tags (e.g., `v1.0.0`, `release-2024-10`)
- **Actions:**
  - Creates a GitHub release
  - Attaches the PDF with version number
  - Generates release notes automatically
  - Archives artifacts for 90 days

### Creating a Release

To create a new release with the PDF:

```bash
# Tag the current commit
git tag -a v1.X.X -m "Release version 1.X.X"

# Push the tag to trigger the release workflow
git push origin v1.X.X
```

The workflow will automatically:
1. Build the document
2. Create a GitHub release
3. Attach the PDF to the release
4. Generate release notes from commit history

### Accessing Build Artifacts

1. Go to the **Actions** tab in your GitHub repository
2. Select a workflow run
3. Scroll down to **Artifacts**
4. Download `Main.pdf`

## 🐛 Troubleshooting

### Common Issues

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).

- **Original Author**: Martin Oswald (Zürich University of Applied Sciences)
- **Modified by**: Frederik Beimgraben (University of Applied Sciences Reutlingen)

See [LICENSE](LICENSE) for details.

## 📧 Support

For questions, issues, or suggestions:
- Open an issue on GitHub
- Contact the maintainer at [frederik@beimgraben.net](mailto:frederik@beimgraben.net)

## 🙏 Acknowledgments

- Martin Oswald for the original ZHAWReport class
- KOMA-Script team for the excellent document classes
- University of Applied Sciences Reutlingen – [Reutlingen University](https://reutlingen-university.de)

---

## 🆕 Recent Updates

### Version 1.0 (October 2025)
- Added Docker support for containerized compilation

### Key Configuration Changes
- **Paragraph Spacing**: 6pt
- **Section Minimum Content**: 12 baseline skips (~2 paragraphs)
- **Citation Style**: APA format via BibLaTeX

---

*Documentation Last updated: 30th of October 2025*