[conspire] pandoc rules ok

[Nick Moffitt]

Link-heavy mail here, so odds are I got one wrong.  Touch wood, scratch a stay, spin widdershins...

On 16Jul2023 11:33pm (-0700), Rick Moen wrote:
> Quoting Steve Litt (slitt at troubleshooters.com):
> > I'm learning more and more about Plain TeX, and hope someday to specify
> > a Markdown superset that converts easily to either Plain TeX or HTML,
> > thereby making a true "write once deploy all formats" authoring format.
> 
> Yes, I'd love to love TeX and its various Implements of Construction
> (LaTeX, LyX, etc.), but just haven't.  I'm obviously Bad and Wrong in
> this.

It's probably more entertaining to try and write your own groff macros.  The most recent project to do this was the "mom" macros, which are now distributed along with groff.

I have had a lot of fun using LaTeX for more advanced book layout, in particular using the "Tufte LaTeX project" styles:

	https://zork.net/amsterdam/handbook.tex along with https://zork.net/amsterdam/tufte-common.def generates:
	https://zork.net/amsterdam/handbook.pdf (17MB A5 PDF full of images, best viewed 2-up).

> I do like Markdown a lot.  And I like JSON when I'm paid to.  ;->

For "write once, deploy everywhere" plain-text, I prefer to do everything in pandoc markdown.  

	https://pandoc.org/

I've found ways to make it work with the "Tufte CSS" styles, via a "sidenote" plugin, although it generates pretty generic LaTeX output.  I should really get back to hacking up something that keeps the same layout for both.

Here's the first couple chapters of a book I was writing over the holidays, trying to capture the spirit of 1980s "learn to program a game on your Home Computer" books for young people:

	https://zork.net/punybook/beginner.md generates:
	https://zork.net/punybook/beginner.html (check out dark mode vs light!)

And here's a rough exegesis on a 1970s source code repository for the PDP-8, which I was doing mainly to learn PAL assembler for my friend's PDP-12:

	https://zork.net/pdp8-cookbook/cookbook.md generates:
	https://zork.net/pdp8-cookbook/cookbook.html (check out dark mode vs light!)

The nice thing about pandoc markdown is that you can get vim (or better, neovim) styles to highlight the markup and be more confident that you got it right before running Make.  And even if you view it in a normal markdown converter, it can get you most of the layout.  Here's what gitea's built-in converter does to the above documents:

	https://zork.net/git/SpaceHobo/punybook/src/branch/main/beginner.md
	https://zork.net/git/SpaceHobo/pdp8-cookbook/src/branch/main/cookbook.md

I can also use it to spit out groff -man or -ms documents (so it's a handy way to write manual pages), or to generate slide decks (which I used for meeting agendas over jitsi during lockdown).  

The "man page" version loses a *lot* of formatting, including all the footnotes:

	https://zork.net/pdp8-cookbook/cookbook.7 (93k, and more's the pity)

Unfortunately getting embedded images via groff is a bit of a pain (and raster images are pretty much entirely unsupported), so you get placeholder text instead:

	https://zork.net/pdp8-cookbook/cookbook-ms.pdf (192k, due to lack of images)

Still, I like that the ms version rendered the syntax highlighting from my custom PAL assembler definition a little more clearly than the LaTeX version:

	https://zork.net/pdp8-cookbook/cookbook.pdf (1.4MB)

But as you can see, the LaTeX one is the most complete document, even if it inlines all my margin notes (while keeping footnotes).  This is the place where I hope to find time to improve things, and make it look more like the Amsterdam ride manual at the top of this mail.

> My not-so-secret shame:  I maintain an almost-ASCII file of 
> the status of all the streaming programmes I follow -- in _RTF_.  Why?
> Because despite MSFT messing with the format occasionally, it's a
> least-hassle way, using many tools, to incorporate styling features like
> bolding.

Pandoc can do RTF as well, but it doesn't seem to scale images, and it entirely ignored my syntax highlighting for some reason:

	https://zork.net/pdp8-cookbook/cookbook.rtf (2.5MB, presumably due to the un-scaled images in an inefficient format)