Markup Language

[OrangeToucan]

I wonder about the choice of markup language. I understand that this was inherited from Mark Trapp's original decision to use it but that doesn't mean it has to continue. The reason I wonder if something else might be better is to better preserve the formatting of the original book, which uses things like underline in both parts of paragraphs as well as some section numbers, indenting sections of code from the left margin, and etc. which are not supported in GitHub's version of Markdown.

[OrangeToucan]

And other books (I assume the goal is to work on preserving them all?) have things such as footnotes, which are also not directly supported in GitHub's version of Markdown.

[taradinoc]

Markdown has been convenient for quick transcription and rendering, and it's also nice that it can be searched for keywords with grep.

I wouldn't mind using another format if those advantages can be preserved - maybe finishing the transcription in Markdown and then converting it with a script. Besides the formatting, that would also let us rebuild the index, since the printed index is useless without page numbers.

[OrangeToucan]

Page numbers are really only useful with a printed book though. They're not so useful for an online copy which can just link to sections from a table of contents. So I suppose part of this question then becomes what sort of output is desired in the end? Is there a desire to print an actual book then?

[taradinoc]

I don't think there's a need to make it printable. My main goals are to make it easy to search, and accessible to blind users.

A secondary goal is to make it adaptable for use as part of ZILF's documentation somehow, e.g. with some kind of optional annotations or links explaining the differences.

[OrangeToucan]

Finishing the transcription in GitHub's version of Markdown and then returning to the language question means that some formatting & style decisions will have already been made (like the table in chapter 18.)

[taradinoc]

What alternatives should we be looking at?

reStructuredText + Sphinx, maybe? Looks like it supports footnotes, references, TOC/index, some extensibility, and can be hosted for viewing at GitHub or other sites.

[OrangeToucan]

Maybe Pandoc's version of markdown would work? http://pandoc.org/MANUAL.html#pandocs-markdown

It seems very similar to GitHub's version of Markdown. I imagine it would require little to no changes to the current stuff, while adding support for footnotes, a table of contents, etc.

With a couple of changes to add title, author, and year metadata I was able to use pandoc to make this PDF.

The MDL Programming Language.pdf

HTML output is possible too.

[taradinoc]

That looks promising, and not having to reformat much of the existing content is a plus. A Markdown format might also be the best option for the specific formatting problem from #21 (emphasizing part of a code block); it requires embedding HTML, but in RST I guess the workaround is even uglier.

The main drawback is the lack of indexing features, I think. Sphinx can generate lists like http://www.sphinx-doc.org/en/stable/genindex.html.

[OrangeToucan]

With Sphinx you can do http://blockdiag.com/en/ which sort of touches on issue #19 for the diagrams.
The downside is that moving to Sphinx would mean re-writing everything?

[OrangeToucan]

If HTML can be included in Markdown as you mention then that perhaps solves both problems, from pull request #21 and from issue #19. Diagrams can be made with a vector graphics program (or from blogdiag & then exported as a vector) and then included via HTML?

[taradinoc]

I've been playing around with Sphinx lately, porting what little I've written of the ZILF Language Guide. I think that might be a good way to go with this.

• Converting the text looks straightforward with pandoc.
• I'm writing a Pygments highlighter for ZIL/MDL, and may end up writing some markup extensions too, so those could be reused here.
• The builtin markup is useful for the parts we haven't reproduced: emphasis in section titles, some emphasis in some code samples (e.g. italicizing the lowercase parts in <BLOCK look-up:list-of-oblists>), indexing, section cross-references, bibliography.
• There's a graphviz extension, which ought to work for the diagrams: http://codrspace.com/toddkfisher/advanced-dot/

[OrangeToucan]

This sound interesting, yes.

[jmdyck]

Do you have any timeline for porting mdl-docs to Sphinx?

[taradinoc]

Not anytime soon, I think other priorities will come first for the next couple months at least. But if someone else wants to pick it up, take a look at the sphinx branch here.