Pandoc-scdoc: write schelp files with pandoc

Resources
1

I just tagged the first release of pandoc-scdoc.

The goal is what it sounds like, write SuperCollider help files in Markdown, org-mode, or rst and convert them directly into valid .schelp files.

The long-term goal is to make this suitable for upstream inclusion in pandoc. For now, it remains a standalone tool while the mapping is tested against real-world usage.

Repo: https://github.com/smoge/pandoc-scdoc

0.1.0.0 is still experimental, but already covers the main pieces:

  • markdown, rst, and org-mode
  • SCDoc metadata
  • Standard help sections: Description, ClassMethods, InstanceMethods, Examples
  • methods and arguments inferred from document structure, or tagged with pandoc attributes
  • tables, notes, warnings, links, anchors, code etc
  • raw scdoc passthrough

Examples: pandoc-scdoc/examples at main · smoge/pandoc-scdoc · GitHub

I’d appreciate feedback from people who write or maintain sc help files. Where the mapping feels natural, where it gets in the way, and what would be better fit.

If you have a file that would make a good test case, I’d be glad to include in the test. I’m genuinely curious to hear what breaks.

2

I’ve released pandoc-scdoc 0.2.0.0

A writer is good, a reader changes things a bit. With both directions implemented, pandoc-scdoc can now verify itself against the real SuperCollider HelpSource corpus by reading, writing, reading again, and comparing the resulting ASTs.

Now the project has something better than confidence: a corpus that checks the work. We can pull the receipts now.

Text.Pandoc.Readers.SCDoc now exists, offering readSCDoc and readSCDocPure

The parser follows SCDoc grammar, including some edge cases that only became visible when tested against the HelpSource corpus. No hand-waving: just files, grammar, and the small humiliation loops by which things become honest.

Round-trip coverage against SuperCollider’s HelpSource corpus:

  • 1137 files parsed — every one, no apologies
  • 1136 files round-trip cleanly (read → write → read)
  • One failure: Overviews/JITLib.schelp, undone by a leading-whitespace peculiarity - a flaw so minor it is almost charming, documented rather than buried, which is more than most do with their blemishes

Several things have been corrected to better reflect upstream SCDoc semantics, which, upon close inspection, turned out to have opinions of their own:

  • returns:: and note:: now use body-bearing forms, as they always should have
  • Body-level keyword:: lines are lifted into Meta
  • Link canonicalization is shared between reader and writer one authoritative version, as there ought to be of most things

Writer:

The round-trip work revealed what one had quietly assumed was working, which is to say, rather less than one had assumed. Half the writer fixes came from letting the reader call the writer out all the way through.

One behavioral change: headings titled warning that carry an explicit structural class, method, subsection, and so forth. Pandoc attribution syntax is still available as before 0.1.x. If this touches your workflow, that heading behavior is where I looked first. The new behavior is closer to what SCDoc does, and why walk it back now?

CorpusAuditSpec walks your local HelpSource and writes a drift report to /tmp/scdoc-audit.md:

SCDOC_HELPSOURCE=/path/to/HelpSource SCDOC_AUDIT=1 stack test

The round-trip was quite useful, and I feel the project is in good shape now.

1 Like