LaTeX Handouts

What this skill does

# LaTeX Handouts

LaTeX provides professional typesetting for presentation handouts that combine slide images, presenter notes, and supplementary research into comprehensive reference documents.

## Dependency Checking

Before generating handouts, check dependencies using:
```bash
${CLAUDE_PLUGIN_ROOT}/scripts/check-handout-deps.sh
```

**Exit codes:**
- 0: All dependencies available (full handout with images and rich formatting)
- 1: pdflatex missing (BLOCKER - cannot generate handout)
- 2: LaTeX packages missing (use basic formatting)
- 3: Playwright missing (text-only handout)

## Graceful Degradation Strategies

**When LaTeX packages unavailable (exit code 2):**
- Skip `\usepackage{tcolorbox}` and `\usepackage{enumitem}` in preamble
- Use standard LaTeX boxes instead of tcolorbox
- Use default enumerate/itemize instead of enumitem
- Result: Basic but functional handout

**When Playwright unavailable (exit code 3):**
- Skip slide PNG export entirely
- Omit `\begin{figure}...\end{figure}` blocks for slide images
- Still include all prose paragraphs (Overview, Key Considerations, Technical Details)
- Still include all Further Reading links
- Result: Text-only reference document (still valuable)

**When pdflatex unavailable (exit code 1):**
- Cannot generate PDF handout
- Offer to create .tex file for user to compile later
- Provide installation instructions

## Handout Writing Principles

**Critical:** Handouts should be **comprehensive standalone documents**, not just copies of slides.

### Content Requirements

✅ **DO:**
- Write in **complete prose paragraphs** (2-4 sentences minimum)
- **Expand on slide content** - explain concepts in detail
- **Add context** - WHY things matter, HOW they work
- **Include researched URLs** - 3-5 quality resources per section
- **Provide examples** - real-world applications and use cases
- **Explain trade-offs** - discuss implications and alternatives
- Make it **standalone** - reader understands without attending presentation

❌ **DON'T:**
- Copy bullet points from slides verbatim
- Write generic descriptions
- Use slide content as handout content
- Skip research for further reading
- Assume reader attended presentation

### Writing Style

**For each slide, write:**

1. **Overview paragraph** (2-4 sentences)
   - Transform slide bullets into flowing narrative
   - Explain the concept in complete detail
   - Provide context and connections

2. **Key Considerations paragraph** (2-4 sentences)
   - Discuss implications and trade-offs
   - Explain WHY it matters
   - Provide real-world examples

3. **Technical Details paragraph** (if applicable)
   - Explain HOW things work (not just WHAT)
   - Code explanations in prose
   - Architecture decisions and reasoning

4. **Further Reading list** (3-5 URLs)
   - Official documentation
   - Authoritative articles
   - Tutorials and guides
   - Each with specific description of value

## Document Structure

### Basic Handout Template

```latex
\documentclass[11pt,a4paper]{article}

% Essential packages
\usepackage[utf8]{inputenc}
\usepackage[margin=1in]{geometry}
\usepackage{graphicx}
\usepackage{hyperref}
\usepackage{fancyhdr}

% Document metadata
\title{Presentation Title}
\author{Author Name}
\date{\today}

% Header/footer setup
\pagestyle{fancy}
\fancyhead[L]{Presentation Title}
\fancyhead[R]{\thepage}
\fancyfoot[C]{}

\begin{document}

\maketitle
\tableofcontents
\newpage

% Content sections
\section{Introduction}
Content here...

\end{document}
```

### Document Classes

**article** - Standard documents
- Best for: Short handouts (1-20 pages)
- Features: Simple structure, no chapters
- Use when: Single presentation handout

**report** - Longer documents
- Best for: Extended handouts (20+ pages)
- Features: Chapters supported, more structure
- Use when: Multi-session course materials

**scrartcl/scrreprt** - KOMA-Script alternatives
- Best for: Modern, customizable layouts
- Features: Better typography, more options
- Use when: Advanced formatting needed

## Essential Packages

### Graphics and Images

```latex
\usepackage{graphicx}  % Include images
\usepackage{float}     % Better float positioning

% Usage
\begin{figure}[H]
  \centering
  \includegraphics[width=0.8\textwidth]{slide-01.pdf}
  \caption{Introduction Slide}
  \label{fig:intro}
\end{figure}
```

### Layout and Formatting

```latex
\usepackage[margin=1in]{geometry}  % Page margins
\usepackage{multicol}              % Multiple columns
\usepackage{parskip}               % Paragraph spacing
\usepackage{setspace}              % Line spacing

% Multi-column sections
\begin{multicols}{2}
  Content in two columns
\end{multicols}
```

### Hyperlinks and References

```latex
\usepackage{hyperref}

% Configuration
\hypersetup{
    colorlinks=true,
    linkcolor=blue,
    filecolor=magenta,
    urlcolor=cyan,
    citecolor=green
}

% Usage
\href{https://example.com}{Link text}
\url{https://example.com}
```

### Code Listings

```latex
\usepackage{listings}
\usepackage{xcolor}

% Configuration
\lstset{
    basicstyle=\ttfamily\small,
    keywordstyle=\color{blue},
    commentstyle=\color{green},
    stringstyle=\color{red},
    frame=single,
    breaklines=true
}

% Usage
\begin{lstlisting}[language=Python]
def hello():
    print("Hello, World!")
\end{lstlisting}
```

### Bibliography

```latex
\usepackage[backend=biber,style=apa]{biblatex}
\addbibresource{references.bib}

% In document
\cite{key}

% At end
\printbibliography
```

## Heading Hierarchy

**Use semantic heading levels rigorously and consistently:**

- `\section{}` - Major document divisions (Introduction, Presentation Content, Summary, Additional Resources)
- `\subsection{}` - Topic sections within presentation (matches slide deck sections/chapters)
- `\subsubsection{}` - Individual slide titles (each slide gets its own subsubsection heading)
- `\paragraph{}` - Content subdivisions within slides (Overview, Key Considerations, Technical Details, Further Reading)

**Rules:**
- Never skip heading levels (don't go from `\section{}` to `\subsubsection{}`)
- Use headings for semantic structure, not just visual formatting
- Keep heading text descriptive and assertion-based
- Each slide must have its own `\subsubsection{}` heading

## Handout Patterns

### Comprehensive Slide Documentation (RECOMMENDED)

Modern handout format with PNG slides and prose explanations:

```latex
\section{Topic Name}

\subsubsection{Specific Slide Title (Assertion Form)}

\begin{figure}[H]
  \centering
  \fbox{\includegraphics[width=0.72\textwidth]{exports/slide-005.png}}
  \caption{Specific Slide Title}
\end{figure}

\paragraph{Overview:}
This section introduces the core concept of container orchestration in distributed systems.
Kubernetes provides declarative configuration management, allowing operators to specify desired
state rather than imperative commands. The reconciliation loop continuously monitors actual
state and makes adjustments to match the declared configuration, providing self-healing
capabilities automatically.

\paragraph{Key Considerations:}
The declarative approach fundamentally changes operational practices compared to traditional
imperative automation. When configuration drift occurs, the system automatically corrects it
without human intervention. This is particularly valuable in large-scale deployments where
manual intervention becomes impractical. However, it requires careful design of resource
specifications and understanding of reconciliation behavior during failures.

\paragraph{Technical Details:}
The control loop pattern uses three key components: controllers watch the API server for
changes, compare current state to desired state, and issue commands to reconcile differences.
Each controller operates independently, managing specific resource types. This distributed
control model provides scalability and fault tolerance, as controller failures don't cascade
across the system.

\paragraph{Further Reading:}
\begin{itemize}
  \item \href{https://kubernetes