.

Toolbox/docs/documentation/USAGE.md

@@ -0,0 +1,206 @@
+# Usage Guide
+
+This guide explains how to use the documentation toolchain container for various document creation workflows.
+
+## 🚀 Quick Start
+
+### Run the Container
+```bash
+# Interactive mode (recommended for development)
+docker run --rm -it -v $(pwd):/home/tsysdevstack/docs tsysdevstack-toolboxes-docs
+
+# Or use with docker-compose
+docker-compose -f output/docker-compose.yml up
+```
+
+### Available Tools
+Once inside the container, you have access to all the tools in the toolchain:
+
+- `pandoc` - Universal document converter
+- `mdbook` - Book generator from markdown
+- `typst` - Modern typesetting system
+- `marp` - Markdown presentation tool
+- `quarto` - Scientific publishing system
+- `vale` - Prose linter
+- And many more...
+
+## 📄 Document Workflows
+
+### 1. Resume Generation
+
+Creating a professional PDF resume from Markdown:
+
+```bash
+# Convert markdown to PDF using pandoc
+pandoc examples/resume-sample.md -o output/resume.pdf --template=examples/resume-style.tex --pdf-engine=xelatex
+
+# Or with custom styling
+pandoc examples/resume-sample.md -o output/resume.pdf -H examples/resume-style.tex --pdf-engine=xelatex
+```
+
+### 2. Project Documentation
+
+Generating comprehensive project documentation:
+
+```bash
+# Create HTML documentation from markdown
+pandoc examples/project-plan.md -o output/project-plan.html --standalone
+
+# Create PDF documentation
+pandoc examples/project-plan.md -o output/project-plan.pdf --pdf-engine=xelatex
+
+# Generate a full documentation site with mdbook
+cd examples/mdbook-sample
+mdbook build -d ../../output/mdbook-output
+```
+
+### 3. Academic Writing
+
+Using Typst for academic documents:
+
+```bash
+# Compile a typst document
+typst compile examples/sample-typst.typ output/thesis.pdf
+
+# Watch for changes and recompile
+typst watch examples/sample-typst.typ output/thesis.pdf
+```
+
+### 4. Presentations
+
+Creating presentations from markdown:
+
+```bash
+# Using marp to create a presentation
+npx --package @marp-team/marp-cli marp examples/sample-presentation.md -o output/presentation.pdf
+
+# Serve presentation for live editing
+npx --package @marp-team/marp-cli marp examples/sample-presentation.md --server
+```
+
+### 5. Joplin Notes Conversion
+
+Converting Joplin notes to various formats:
+
+```bash
+# Convert Joplin markdown to PDF
+pandoc examples/joplin-note-sample.md -o output/joplin-note.pdf --pdf-engine=xelatex
+
+# Convert to HTML with custom styling
+pandoc examples/joplin-note-sample.md -o output/joplin-note.html --standalone --css styles/notes-style.css
+```
+
+### 6. Data-Driven Reports
+
+Using Quarto for data-driven reports:
+
+```bash
+# Render a quarto document
+quarto render examples/sample-report.qmd -o output/report.html
+
+# Convert to PDF
+quarto render examples/sample-report.qmd -o output/report.pdf
+```
+
+## 🔧 Advanced Usage
+
+### Environment Variables
+
+Set these environment variables to customize behavior:
+
+- `PANDOC_DATA_DIR` - Directory for custom pandoc templates and filters
+- `MARP_USER` - User settings for marp
+- `QUARTO_PROJECT_DIR` - Project directory for quarto
+
+### File Mounting
+
+Mount volumes to share files between your host and the container:
+
+```bash
+# Share your documents directory
+docker run --rm -it \
+  -v $(pwd)/docs:/home/tsysdevstack/docs \
+  -v $(pwd)/templates:/home/tsysdevstack/templates \
+  tsysdevstack-toolboxes-docs
+```
+
+### Custom Templates
+
+Place custom pandoc templates in `/home/tsysdevstack/.pandoc/templates/`:
+
+```bash
+# Use a custom template
+pandoc input.md -o output.pdf --template custom-template
+
+# Or specify template path directly
+pandoc input.md -o output.pdf --template=/path/to/my-template.tex
+```
+
+## 🛠️ Tool-Specific Examples
+
+### Pandoc
+
+Convert between various formats:
+
+```bash
+# Markdown to LaTeX
+pandoc input.md -o output.tex
+
+# Markdown to Docx
+pandoc input.md -o output.docx
+
+# HTML to markdown
+pandoc input.html -o output.md
+
+# Custom styling with CSS
+pandoc input.md -o output.html --css styles/custom.css --standalone
+```
+
+### Vale
+
+Lint your documentation for style issues:
+
+```bash
+# Check a document
+vale examples/project-plan.md
+
+# Check with specific configuration
+vale --config /path/to/.vale.ini examples/
+```
+
+### BibTeX Management
+
+Use bibtool to manage bibliography files:
+
+```bash
+# Format and clean a bibliography
+bibtool -s -d examples/sample-bibliography.bib > output/cleaned-bibliography.bib
+
+# Extract entries from a larger bibliography
+bibtool -x "author='Smith'" examples/large-bibliography.bib > output/smith-entries.bib
+```
+
+## 🧪 Testing Your Setup
+
+Verify that all tools are working correctly:
+
+```bash
+# Test pandoc
+pandoc --version
+
+# Test mdbook
+mdbook --version
+
+# Test typst
+typst --version
+
+# Test quarto
+quarto --version
+
+# Test that all required tools are accessible
+ls -la /home/tsysdevstack/.local/bin/
+```
+
+## 🚨 Troubleshooting
+
+If you encounter issues, see our [Troubleshooting Guide](TROUBLESHOOTING.md) for solutions to common problems.