Add Markdown/DOCX → NIME PDF pipeline via pandoc

.gitignore

@@ -310,3 +310,7 @@ TSWLatexianTemp*
 # option is specified. Footnotes are the stored in a file with suffix Notes.bib.
 # Uncomment the next line to have this generated file ignored.
 #*Notes.bib
+
+# Outputs generated by the pandoc Markdown/DOCX -> NIME PDF pipeline
+/example.tex
+/example.pdf

Makefile

@@ -24,11 +24,59 @@ $(ALT_NIME_TEMPLATE).pdf: $(ALT_NIME_TEMPLATE).tex
 
 all: $(MUSIC_TEMPLATE).pdf $(PAPER_TEMPLATE).pdf $(ALT_NIME_TEMPLATE).pdf
 
+# ===========================================================================
+# Markdown / DOCX -> NIME PDF pipeline (pandoc + pdflatex)
+#
+#   make md-pdf                          # builds pandoc/example.md
+#   make md-pdf   SRC=mypaper.md
+#   make docx-pdf SRC=mypaper.docx META=mypaper-meta.yaml
+#   make docx-md  SRC=mypaper.docx       # extract .docx -> editable Markdown
+#
+# Output <name>.tex and <name>.pdf are written to the repository root so that
+# image and .bib paths in the metadata resolve relative to the repo.
+# See pandoc/README.md for the metadata format.
+# ===========================================================================
+PANDOC          ?= pandoc
+PANDOC_DEFAULTS  = pandoc/nime-defaults.yaml
+MD_READER        = markdown+yaml_metadata_block+tex_math_dollars+raw_tex
+DOCX_READER      = docx+citations
+
+SRC  ?= pandoc/example.md
+META ?=
+OUT   = $(notdir $(basename $(SRC)))
+
+# pdflatex + bibtex cycle for a pandoc-generated $(OUT).tex
+define pandoc_latex
+	pdflatex -interaction=nonstopmode $(OUT).tex
+	-bibtex $(OUT)
+	pdflatex -interaction=nonstopmode $(OUT).tex
+	pdflatex -interaction=nonstopmode $(OUT).tex
+endef
+
+# Markdown (with YAML front matter) -> NIME PDF
+md-pdf:
+	$(PANDOC) --defaults $(PANDOC_DEFAULTS) -f $(MD_READER) -o $(OUT).tex $(SRC)
+	$(pandoc_latex)
+
+# Word .docx (+ metadata sidecar via META=...) -> NIME PDF
+docx-pdf:
+	$(PANDOC) --defaults $(PANDOC_DEFAULTS) -f $(DOCX_READER) \
+		$(if $(META),--metadata-file $(META),) -o $(OUT).tex $(SRC)
+	$(pandoc_latex)
+
+# Extract a .docx to a Markdown starting point (then add front matter + md-pdf)
+docx-md:
+	$(PANDOC) -f $(DOCX_READER) -t markdown --wrap=preserve \
+		--extract-media=images/$(OUT)-media -o $(OUT).md $(SRC)
+	@echo "Wrote $(OUT).md. Add YAML front matter (see pandoc/example.md), then:"
+	@echo "    make md-pdf SRC=$(OUT).md"
+
 # Clean generated files
 clean:
 	rm -f $(PAPER_TEMPLATE).pdf $(MUSIC_TEMPLATE).pdf $(ALT_NIME_TEMPLATE).pdf
+	rm -f example.pdf example.tex
 	rm -f *.aux *.log *.out \
 		*.bbl *.blg *.fls *.fdb_latexmk \
 		*.synctex.gz
 
-.PHONY: all clean
+.PHONY: all clean md-pdf docx-pdf docx-md

README.md

@@ -10,6 +10,21 @@ The templates have example text demonstrating many interesting and useful featur
 
 The `word` folder also contains .docx MS Word templates for all tracks. 
 
+## Markdown / Word → NIME PDF
+
+If you would rather write in **Markdown** (or convert from a **Word `.docx`**)
+than edit LaTeX directly, the `pandoc` folder contains a pipeline that renders
+those sources to a NIME-formatted PDF using the same `nimeart` class:
+
+```sh
+make md-pdf                              # builds the example pandoc/example.md
+make md-pdf   SRC=mypaper.md
+make docx-pdf SRC=mypaper.docx META=mypaper-meta.yaml
+```
+
+This requires [pandoc](https://pandoc.org) in addition to the LaTeX toolchain.
+See [`pandoc/README.md`](pandoc/README.md) for the metadata format and details.
+
 In addition to the alt.nime template, you can also find the folder `alt-nime_pictorial-templates`, which contains Word .docx, PowerPoint .pptx, and InDesign templates for pictorial-oriented work should you wish to use this format for your alt.nime submission. These templates are modeled on the ACM SIGCHI Pictorial template used a the ACM TEI and DIS conferences and provide a visual focus for your research. 
 
 ## `nimeart.cls`

pandoc/README.md

@@ -0,0 +1,127 @@
+# Markdown / DOCX → NIME PDF pipeline
+
+Write your NIME paper in **Markdown** (or a **Word `.docx`**) and render it to a
+NIME-formatted PDF using [pandoc](https://pandoc.org) and the `nimeart` LaTeX
+class. This is an alternative authoring route to writing LaTeX directly — the
+output uses the same class, fonts, and reference style as the `.tex` templates.
+
+## Requirements
+
+- [pandoc](https://pandoc.org) 3.x
+- A TeX distribution with `pdflatex` and `bibtex` (TeX Live / MacTeX) — the same
+  toolchain the LaTeX templates need, including the `nimeart.cls` in this repo.
+
+## Quick start
+
+From the repository root:
+
+```sh
+make md-pdf                 # builds the example: pandoc/example.md -> example.pdf
+make md-pdf SRC=mypaper.md  # build your own Markdown file
+```
+
+Outputs `<name>.tex` and `<name>.pdf` are written to the repository **root** so
+that image paths (e.g. `images/...`) and the `.bib` file resolve relative to the
+repo, exactly as in the LaTeX templates.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `nime.latex`          | Pandoc LaTeX template; maps YAML metadata onto the `nimeart` front-matter commands. |
+| `nime-defaults.yaml`  | Pandoc options (template, citation method, table filter, variables). |
+| `nime-tables.lua`     | Renders Markdown tables as `table`+`tabular` floats (pandoc's default `longtable` fails in two-column mode). |
+| `example.md`          | A complete example paper with all supported metadata fields. |
+| `example-meta.yaml`   | A metadata sidecar for the DOCX path. |
+
+## Markdown front matter
+
+All NIME front-matter lives in a YAML block at the top of the Markdown file.
+See `example.md` for a full, commented example. The supported fields:
+
+```yaml
+---
+title: "Your Paper Title"
+shorttitle: "Short Title"          # optional, for page headers
+subtitle: "Optional Subtitle"      # optional
+classoption: sigconf               # or [sigconf, anonymous, review] for blind review
+
+author:
+  - name: First Author
+    email: first@example.org
+    institution: Their University
+    department: Optional Department # optional
+    city: City
+    state: ST                       # optional
+    country: Country
+    orcid: 0000-0000-0000-0000      # optional
+    note: Shared-contribution note. # optional (\authornote)
+  - name: Second Author
+    email: second@example.org
+    institution: Another University
+    city: City
+    country: Country
+    notemark: 1                     # optional, references an earlier note
+
+shortauthors: "First and Second"    # optional, for page headers
+abstract: |
+  Your abstract here.
+keywords: [one, two, three]
+
+teaser:                             # optional page-spanning teaser figure
+  image: images/sampleteaser.png
+  caption: "Caption."
+  description: "Accessibility description."
+  label: "fig:teaser"
+
+bibliography: sample-references.bib  # BibTeX, rendered with ACM-Reference-Format
+acknowledgments: |                   # optional, emitted as acmart \begin{acks}
+  Thanks to ...
+---
+```
+
+The document body is plain Markdown: `#`/`##`/`###` headings become numbered
+`\section`/`\subsection`/`\subsubsection`, images become `figure`s (alt text →
+accessibility `\Description`), pipe tables become booktabs tables, `$...$` /
+`$$...$$` are maths, and citations use pandoc's `@key` syntax (`[@a; @b]`),
+rendered through BibTeX. You can also drop in raw LaTeX where you need it.
+
+## Word (`.docx`)
+
+A Word document carries prose but not the structured NIME front matter, so
+supply that in a metadata sidecar (same fields as above):
+
+```sh
+make docx-pdf SRC=mypaper.docx META=pandoc/example-meta.yaml
+```
+
+Or convert the `.docx` into a Markdown starting point, add the front matter, and
+use the Markdown path (recommended if you want full citation support):
+
+```sh
+make docx-md SRC=mypaper.docx   # -> mypaper.md (media extracted to images/)
+# add YAML front matter to mypaper.md, then:
+make md-pdf SRC=mypaper.md
+```
+
+### Citation caveat for `.docx`
+
+Pandoc only parses `[@key]` citation syntax from Markdown-family input. Citations
+typed as `[@key]` text inside a Word document are **not** converted and will
+appear literally. For cited work, prefer the Markdown path (or the `docx-md`
+→ `md-pdf` route above), or manage references with a Word/Zotero citation plugin
+whose native fields pandoc can read.
+
+## How it works
+
+```
+Markdown ─┐
+          ├─ pandoc (--template nime.latex, --natbib, table filter) ─► .tex ─► pdflatex + bibtex ─► .pdf
+.docx  ───┘  (+ metadata sidecar)
+```
+
+acmart/nimeart provides its own fonts (Libertine/newtxmath), `hyperref`, and
+page geometry, so the template deliberately omits pandoc's font and geometry
+partials to avoid clashes (notably the `\Bbbk` redefinition from reloading
+`amssymb`). Paragraphs are forced to `indent` mode so pandoc does not load
+`parskip`, which would override acmart's paragraph formatting.

pandoc/example-meta.yaml

@@ -0,0 +1,35 @@
+# Metadata sidecar for the DOCX → NIME PDF path.
+#
+# A Word document carries the prose, but not the structured NIME front matter
+# (authors, affiliations, keywords, ...). Supply that here and combine the two:
+#
+#   make docx-pdf SRC=mypaper.docx META=pandoc/example-meta.yaml
+#
+# The fields are identical to the YAML front matter in pandoc/example.md.
+---
+title: "Writing NIME Papers in Word"
+shorttitle: "NIME Papers in Word"
+classoption: sigconf
+
+author:
+  - name: Ada Lovelace
+    email: ada@example.org
+    institution: Analytical Engine Lab
+    city: London
+    country: United Kingdom
+  - name: Alan Turing
+    email: alan@example.org
+    institution: Bletchley University
+    city: Milton Keynes
+    country: United Kingdom
+
+shortauthors: "Lovelace and Turing"
+
+abstract: |
+  This abstract comes from the metadata sidecar rather than the Word document,
+  demonstrating the DOCX → NIME PDF path.
+
+keywords: [word, docx, pandoc, NIME, authoring]
+
+bibliography: sample-references.bib
+---

pandoc/example.md

@@ -0,0 +1,105 @@
+---
+# ===========================================================================
+# NIME paper metadata. Everything in this YAML block maps onto the nimeart
+# (acmart) front-matter commands via pandoc/nime.latex.
+# ===========================================================================
+
+title: "Writing NIME Papers in Markdown"
+shorttitle: "NIME Papers in Markdown"   # used in page headers; omit if title is short
+# subtitle: "An Optional Subtitle"
+
+# For double-anonymous submission, set:
+#   classoption: [sigconf, anonymous, review]
+classoption: sigconf
+
+author:
+  - name: Ada Lovelace
+    email: ada@example.org
+    institution: Analytical Engine Lab
+    city: London
+    country: United Kingdom
+    orcid: 0000-0000-0000-0000
+    note: Both authors contributed equally to this research.
+  - name: Alan Turing
+    email: alan@example.org
+    institution: Bletchley University
+    department: Department of Computing
+    city: Milton Keynes
+    country: United Kingdom
+    notemark: 1          # references the note above (shared-contribution mark)
+
+shortauthors: "Lovelace and Turing"
+
+abstract: |
+  This document demonstrates how to author a NIME paper in Markdown and render
+  it to a NIME-formatted PDF with pandoc and the `nimeart` LaTeX class. It
+  shows headings, citations, figures, tables, and maths so you can see how a
+  Markdown source maps onto the conference template.
+
+keywords: [markdown, pandoc, NIME, authoring, music]
+
+# Optional teaser image spanning the page width (place above \maketitle).
+teaser:
+  image: images/sampleteaser.png
+  caption: "A teaser image rendered from Markdown."
+  description: "Tangled banana patch cables."
+  label: "fig:teaser"
+
+# Bibliography (BibTeX). bibtex + ACM-Reference-Format are run by the Makefile.
+bibliography: sample-references.bib
+
+# Acknowledgments are emitted inside acmart's \begin{acks} ... \end{acks}.
+acknowledgments: |
+  To the maintainers of pandoc and the NIME template, for making this possible.
+---
+
+# Introduction
+
+You can write your NIME paper in **Markdown** and still get a properly
+formatted PDF. Inline formatting such as *emphasis*, **bold**, and `code`
+all work, as do footnotes.[^1] Citations use pandoc's `@key` syntax and are
+rendered through BibTeX with the ACM reference format, e.g. a classic
+reference [@Lamport:LaTeX] or several at once [@Abril07; @Cohen07].
+
+[^1]: Footnotes render as endnotes/footnotes per the class.
+
+# Sectioning
+
+Markdown headings map onto LaTeX sectioning commands.
+
+## A Subsection
+
+Text under a subsection.
+
+### A Subsubsection
+
+Text under a subsubsection.
+
+# Figures
+
+Reference a figure with standard Markdown image syntax; the caption becomes
+the `\caption` and the alt text becomes the accessibility `\Description`.
+
+![A Bela board in action at a workshop.](images/sample-image.jpg){#fig:bela width=80%}
+
+# Tables
+
+| Symbol      | Frequency      | Comments          |
+|-------------|----------------|-------------------|
+| Ø           | 1 in 1,000     | For Swedish names |
+| $\pi$       | 1 in 5         | Common in math    |
+| \$          | 4 in 5         | Used in business  |
+
+: Frequency of special characters. {#tbl:freq}
+
+# Maths
+
+Inline maths such as $\lim_{n\to\infty} x = 0$ works, as do display equations:
+
+$$\sum_{i=0}^{\infty} x_i = \int_0^{\pi+2} f \, .$$
+
+# Ethical Standards
+
+The Ethical Standards section is mandatory for all NIME submissions. State
+sources of funding, conflicts of interest, and informed-consent information
+here.

pandoc/nime-defaults.yaml

@@ -0,0 +1,33 @@
+# Pandoc defaults for building NIME PDFs from Markdown or DOCX.
+#
+#   pandoc --defaults pandoc/nime-defaults.yaml -o out.tex pandoc/example.md
+#
+# Invoked via the Makefile targets `md-pdf` / `docx-pdf`, which run pdflatex +
+# bibtex afterwards so the NIME (nimeart) class and ACM-Reference-Format style
+# are applied. Paths are relative to the repository root.
+
+# The input reader (`-f`/`--from`) is set per Makefile target, since Markdown
+# and DOCX need different readers.
+to: latex
+template: pandoc/nime.latex
+
+# Emit \citep/\citet + \bibliography{} so bibtex + ACM-Reference-Format runs,
+# matching the LaTeX templates (rather than pandoc's own citeproc renderer).
+cite-method: natbib
+standalone: true
+
+filters:
+  # Render tables as `table`+`tabular` floats (pandoc's default longtable
+  # output fails in two-column sigconf mode).
+  - pandoc/nime-tables.lua
+
+variables:
+  # Use the ACM reference style for the bibliography (matches the LaTeX
+  # templates). This drives the single \bibliographystyle emitted by pandoc.
+  biblio-style: ACM-Reference-Format
+  # Force indented paragraphs: stops pandoc's `common` partial from loading
+  # parskip, which would override acmart's strict paragraph formatting.
+  indent: true
+  # Default document-class option. Override per-file with `classoption:` in the
+  # YAML front matter, e.g. [sigconf, anonymous, review] for blind submission.
+  classoption: sigconf