Derive a Docbook version from the Markdown version?

[stakx]

Markdown cannot capture all of the semantics in the original PDF document. Examples of that are:

• Difference between grammar productions and metadata table names; they're both formatted italic.
• Meta-comments that are in Comic Sans in the original document.
• ILAsm keywords and directives are formatted either using monospace (in grammar tables) or in bold (when appearing in a regular text paragraph).
• Some symbols can be either CLS types or ILAsm keywords—depending on what they are, they should be formatted differently, say native int (CLS type) vs. native int (ILAsm type keywords). Even the original PDF document doesn't appear to be certain what formatting to apply in such cases.

Using a markup format more powerful than Markdown may offer clean solutions to some of these issues; Docbook comes to mind, though I don't have any prioor experience with it.

We'd lose the specific formatting, which would have to be restored by means of a specialized stylesheet (CSS or XSL-FO, if I understand Docbook correctly).

Doing the Markdown → Docbook conversion manually would be a gargantuan task, it might be worth writing a Markdown parser script that does most of the work.

[darthwalsh]

@stakx If the content changes to docbook, should there be a published version of the site? I can browse the existing docs in github markdown preview, but docbook XML doesn't have that benefit.

If publishing a version of the content to the web is out of scope for now, keeping the content to something GitHub can preview seems better? I think this is the list of language formats GitHub will preview.

[stakx]

@darthwalsh, there's no concrete plan to actually do this (plenty of other work at the moment :-), but I agree that noone would want to browse raw Docbook XML. The idea here was to have a "master" format from which others could be derived programmatically. I assumed that it ought to be reasonably easy to render it as HTML, for example. I don't think it's strictly required that the files be previewable here at the GitHub repo's web UI. Instead, a HTML version could be published automatically (via GitHub Actions) to GitHub Pages, for example... perhaps even with a nice sidebar for the TOC.

[darthwalsh]

I was thinking more about what a HTML version of the site could look like.

On a branch I tried invoking Pandoc against the docs/ folder to build a big HTML file. (It was sort of working, but I was trying to get the sections sorted correctly instead of alphabetically...)

---

I was thinking about this because I added auto-links to a different project, so clicking some line of source code with text // see II.23.1.4 for details could go to some configured URL template that I fill in with II.23.1.4.

The easiest pattern I could come up with is https://github.com/stakx/ecma-335/search?q=II.23.1.4 which kind of works? I might try adding some JS to the generated pandoc site. The idea would be that nagitating to index.html?q=II.23.1.4 would run some JS to scroll to the heading that matches best

[darthwalsh]

@stakx ok i got a PoC working of github actions publishing a single-page HTML! It's hosted at github pages https://darthwalsh.github.io/ecma-335 (That redirects to my custom domain, but if you like this and merge it, github would host it at https://stakx.github.io/ecma-335 )

You can see the build and deploy phases of the github action: https://github.com/darthwalsh/ecma-335/actions/runs/4863547181

I'll work on the custom JS next, so that https://darthwalsh.github.io/ecma-335?section=II.23.1.4 scrolls to the right spot

[stakx]

@darthwalsh, once again, my apologies for the slow reply.

Your HTML PoC is really cool! Yes, I think I'd merge this if you submitted a PR for it. (Though I must admit I've only looked at the resulting page so far, I haven't looked at the actual GitHub Actions.)

I'll still be slow to respond for another few weeks, but starting in autumn I should have some more time for GitHub.