Writeup Generation

Target: $ARGUMENTS

Generates structured academic/technical writeups with pandoc citation support. IEEE [1] style by default.

Workflow

1. •Parse arguments - Extract topic and optional citation style
2. •Create directory - docs/write-up/<topic>/
3. •Generate sections - Use template.md for structure and formats
4. •Setup bibliography - Create references.bib (see template for BibTeX format)
5. •Add YAML frontmatter - See template for required fields
6. •Run markdownlint - make lint_md INPUT_FILES="docs/write-up/<topic>/*.md"
7. •Generate PDF - make pandoc_run with BIBLIOGRAPHY variable

Additional Resources

• •For document structure, frontmatter, and BibTeX format, see template.md

Citation Styles

Additional CSL files are available from the Zotero Style Repository.

Pandoc Command

Generate PDF with citations:

dir=docs/write-up/<topic> && \
make pandoc_run \
  INPUT_FILES="$$(printf '%s\036' $$dir/*.md)" \
  OUTPUT_FILE="$$dir/output.pdf" \
  BIBLIOGRAPHY="$$dir/references.bib"

With custom citation style:

dir=docs/write-up/<topic> && \
make pandoc_run \
  INPUT_FILES="$$(printf '%s\036' $$dir/*.md)" \
  OUTPUT_FILE="$$dir/output.pdf" \
  BIBLIOGRAPHY="$$dir/references.bib" \
  CSL="scripts/writeup/citation-styles/apa.csl"

Section Numbering (MANDATORY)

NEVER add manual section numbers to headings. Pandoc --number-sections handles all numbering automatically.

• •Wrong: # 2. Projektvorstellung, ## 2.1 Motivation, ### 2.1.1 Details
• •Correct: # Projektvorstellung, ## Motivation, ### Details

The NUMBER_SECTIONS parameter in the Makefile writeup recipe controls this. Manual numbers in markdown headings conflict with pandoc auto-numbering and produce duplicated numbers in the PDF output.

Quality Checks

Before completing:

1. •No manual section numbers - Headings must not contain N., N.N, N.N.N prefixes
2. •Markdownlint - make lint_md INPUT_FILES="docs/write-up/<topic>/*.md"
3. •Citation validation - Verify all [@key] references exist in .bib file
4. •PDF generation - Run pandoc command above and confirm output