TSYSDevStack/documentation/USAGE.md

# USAGE.md

## TSYSDevStack - Toolboxes - DocsAndDiagrams

Detailed Usage Instructions for the Document Production Workhorse Container

---

## 📖 Overview

The TSYSDevStack Toolboxes Docs container is designed for document production workflows, offering a comprehensive suite of tools for converting, generating, and processing documents in various formats with a focus on beautiful PDF output.

This guide details how to effectively use the tools available in the container for various document production tasks.

## 🏗️ Container Setup

### Running the Container

The container can be used in both interactive and non-interactive modes:

**Interactive Mode:**
```bash
docker run -it --rm \
  -v "$(pwd)/output:/home/tsysdevstack/TSYSDevStack/Toolbox/docs/output" \
  -v "$(pwd):/data" \
  tsysdevstack/toolboxes-docs
```

**Non-Interactive Mode:**
```bash
docker run --rm \
  -v "$(pwd)/output:/home/tsysdevstack/TSYSDevStack/Toolbox/docs/output" \
  -v "$(pwd):/data" \
  tsysdevstack/toolboxes-docs \
  bash -c "pandoc /data/input.md -o /home/tsysdevstack/TSYSDevStack/Toolbox/docs/output/output.pdf --pdf-engine=xelatex"
```

### Volume Mounting Explained

- **Output Directory**: Mount your local directory to `/home/tsysdevstack/TSYSDevStack/Toolbox/docs/output` to access generated documents
- **Input Directory**: Mount your documents directory to `/data` for processing
- **Configuration**: Store custom configurations in mounted volumes for reuse

## 📝 Pandoc Usage

### Basic Conversion

Pandoc is the universal document converter, supporting over 50 input and output formats:

```bash
# Markdown to PDF (with beautiful styling)
pandoc input.md -o output.pdf --pdf-engine=xelatex

# Markdown to DOCX
pandoc input.md -o output.docx

# HTML to Markdown
pandoc input.html -o output.md -f html -t markdown
```

### Advanced Pandoc Options

```bash
# Convert with custom template and styling
pandoc input.md \
  --output=output.pdf \
  --pdf-engine=xelatex \
  --template=eisvogel \
  --highlight-style=tango \
  --css=styles.css \
  --variable=geometry:a4paper \
  --variable=margin=1in

# Resume generation optimized for ATS systems
pandoc resume.md \
  --output=resume.pdf \
  --pdf-engine=xelatex \
  --template=plain \
  --variable=margin=1in \
  --variable=fontsize=11pt \
  --variable=fontfamily=noto
```

### Joplin Notes to PDF

```bash
# Convert Joplin note to PDF preserving formatting
pandoc joplin_note.md \
  --output=output.pdf \
  --pdf-engine=xelatex \
  --metadata=title:"Note Title" \
  --variable=classoption=landscape \
  --highlight-style=espresso
```

## 📘 mdBook Usage

### Creating a Book

```bash
# Initialize a new book
mdbook init mybook

# Build the book
mdbook build mybook -d /home/tsysdevstack/TSYSDevStack/Toolbox/docs/output
```

### Serving Books

```bash
# Serve the book locally (useful during development)
mdbook serve /data/mybook --hostname 0.0.0.0 --port 3000

# Then access via http://localhost:3000
```

### Custom Configuration

Create a `book.toml` file in your book directory:

```toml
[book]
authors = ["Your Name"]
language = "en"
multilingual = false
src = "."
title = "My Book Title"

[output.html]
mathjax-support = true
default-theme = "coal"
preferred-dark-theme = "navy"
```

## ✍️ Typst Usage

### Basic Document Creation

Create a `.typ` file with Typst syntax:

```typst
#set page(width: 15cm, height: 20cm, margin: 2cm)

= Introduction
This is a basic Typst document.

#figure(
  image("diagram.png"),
  caption: [Figure 1: A diagram]
)
```

### Compiling Typst Documents

```bash
# Compile to PDF
typst compile document.typ /home/tsysdevstack/TSYSDevStack/Toolbox/docs/output/document.pdf

# Compile to PNG
typst compile document.typ /home/tsysdevstack/TSYSDevStack/Toolbox/docs/output/document.png

# Watch for changes
typst watch document.typ /home/tsysdevstack/TSYSDevStack/Toolbox/docs/output/document.pdf
```

## 🎞️ Marp Usage

### Creating Presentations

Create a Markdown file with Marp-specific syntax:

```markdown
---
marp: true
theme: gaia
_class: lead
paginate: true
backgroundColor: #fff
backgroundImage: url('https://cdn.jsdelivr.net/gh/marp-team/marp@master/assets/hero-background.svg')
---

# Slide 1

---

# Slide 2
- Point 1
- Point 2
```

### Generating Presentations

```bash
# Convert to PDF
marp presentation.md --pdf --output /home/tsysdevstack/TSYSDevStack/Toolbox/docs/output/presentation.pdf

# Convert to PPTX
marp presentation.md --pptx --output /home/tsysdevstack/TSYSDevStack/Toolbox/docs/output/presentation.pptx

# Serve locally
marp --server --port 8080
```

## 📊 Quarto Usage

### Basic Document Rendering

```bash
# Render Quarto document to PDF
quarto render document.qmd --to pdf

# Render to HTML with interactive features
quarto render document.qmd --to html --embed-resources

# Render to DOCX
quarto render document.qmd --to docx
```

### Advanced Quarto Features

```bash
# Create a parameterized report
quarto render document.qmd --execute-params "dataset=dataset1;output_format=full" --output /home/tsysdevstack/TSYSDevStack/Toolbox/docs/output/report.pdf

# Create a presentation
quarto render presentation.qmd --to revealjs --output /home/tsysdevstack/TSYSDevStack/Toolbox/docs/output/slides.html
```

### Creating Projects

```bash
# Create a new book project
quarto create-project mybook --type book

# Create an article project
quarto create-project article --type default
```

## 🚦 Kroki Usage

### Generating Diagrams

```bash
# Create a PlantUML diagram
kroki --file diagram.puml --output /home/tsysdevstack/TSYSDevStack/Toolbox/docs/output/diagram.svg

# Generate block diagram in PNG format
echo '@startuml\nAlice -> Bob: Hello\n@enduml' > simple.puml
kroki --file simple.puml --type plantuml --output /home/tsysdevstack/TSYSDevStack/Toolbox/docs/output/simple.png
```

## 📜 Vale Usage

### Linting Documents

```bash
# Check a single document
vale /data/document.md

# Check with specific configuration
vale --config=/data/.vale.ini /data/document.md

# Generate report in JSON format
vale --output-style=JSON /data/document.md
```

## 🔧 Working with TeXLive

### Custom LaTeX Documents

```bash
# Compile LaTeX with XeTeX (for better font support)
xelatex -output-directory=/home/tsysdevstack/TSYSDevStack/Toolbox/docs/output document.tex

# Compile with pdflatex
pdflatex -output-directory=/home/tsysdevstack/TSYSDevStack/Toolbox/docs/output document.tex
```

## 📁 Best Practices

### Organizing Work

1. **Use the `/data` directory** for input files
2. **Use the output directory** for generated documents
3. **Create a local `config` directory** for custom configurations
4. **Use volume mounts** for persistent work

### Performance Tips

1. **Use Docker volumes** instead of bind mounts for better performance when possible
2. **Process multiple files** in a single container run to avoid startup overhead
3. **Use appropriate memory allocation** for large document processing
4. **Use specific tool versions** with mise for reproducibility

### Security Considerations

1. **The container runs as non-root user** (`tsysdevstack`)
2. **No root access is available at runtime** to prevent security issues
3. **Language runtimes are managed by mise** for consistent and secure tooling

## 🔍 Troubleshooting

### Common Issues

- **Font Issues**: The container includes Noto fonts; for additional fonts, extend the container or mount font directories
- **Memory Issues**: Increase Docker's memory allocation for processing large documents
- **Permission Issues**: Ensure mounted volumes have appropriate permissions for UID 1000

### Getting Help

If you encounter issues:

1. Check the [TROUBLESHOOTING.md](TROUBLESHOOTING.md) guide
2. Use the diagnostic commands from the troubleshooting guide
3. Examine container logs: `docker logs <container-name>`
4. Verify volume mappings and file accessibility