Convert the non-CLI docs from man pages to Markdown

[ISSOtm]

(Editing the top comment to be the current consensus on this issue.)

For the reasons discussed below, we've settled on Markdown as the best option for rewriting the docs.

What we'd have to do:

• [ ] Actually do the man-to-md rewrites.
• [ ] Carefully review the rendered Markdown for any regressions.
• [ ] Update rgbds-www to handle integrating the new Markdown docs into rgbds.gbdev.io!
• [ ] Update the README with the new repo directory tree. (And maybe with explanations/recommendations of how to view the rendered Markdown, since "man man/rgbasm.5" and firefox docs/rgbasm.html won't work?)
• [ ] Anything else?

====================

(Original comment follows.)

If the website is the primary UX, I think we should have a serious discussion about not messing with these 1970s-era macros any more and just providing simple man pages that refer to HTML docs (ideally checked into rgbds, not only rgbds-www) for detailed spec info like this.

(Originally posted by @Rangi42 in https://github.com/gbdev/rgbds/pull/1455#discussion_r1706975122.)

Good idea!

I think the most important aspect is that there's a strong split here: the CLI references are better suited as man pages (as supported by @aaaaaa123456789); but the language references, not so much:

• The descriptions are more detailed, leading to rendering gripes like in the OP quoted above.
• It's hard to go to a specific anchor, / in less is annoying, and there's no ToC.
• There's a lot more content in there, and it's harder to navigate in a terminal than in a browser. (And, again, there's no ToC.)

So, I agree that it is a good idea to port some of the documentation away from Mandoc. (Bikeshed point: what language and tooling to use?)

One technical issue I see is how to make the pages stand-alone (for distribution, so people can keep their documentation offline) yet also transclude-able (for rgbds-www).

[Rangi42]

I agree about keeping CLI docs as man pages. But the assembly language, CPU instructions, linkerscript format, object file format, and development history would be modernized.

Pros of Markdown (Cons of HTML):

• A much simpler language; no bikeshedding about which tags to use, how to format them, anything about CSS, etc.
• Easier to read and write in "raw" form.
• Familiar from the README, and other existing doc files.

Pros of HTML (Cons of Markdown):

• More capable (though I do not know if our current docs use any man-page capabilities that Markdown can't handle).
• Easy to read in every user's web browser. (Who has a Markdown renderer?)
• No competing "flavors" with support for different syntax extensions.

[ISSOtm]

Another pro of MarkDown: mandown, which might be usable to back-shim the documentation for people who cling to the terminal regardless. (Probably used as

To explore also:

• [ ] AsciiDoc
• [ ] reStructured Text
• [ ] scdoc (but that's only for man pages...)

[Rangi42]

We already moved away from reStructuredText to Markdown for in-repo files, on the grounds that Markdown is more familiar and has more than sufficient syntax for our typesetting. I see all of those as "the same as Markdown, but with less familiarity/support" unless one of them has a fancy typesetting option that we'd like and Markdown lacks. (Which I highly doubt because, come on, our docs already manage to work within the confines of man pages.)

The motivation I see to change file formats is "ease of writing and reading them", not "enabling even fancier formatting".

[ISSOtm]

Then if that's the axis we're prioritising, MarkDown is by far the way to go. It massively helps with keeping rendering consistent, is far les verbose and “ceremonious” than HTML (its main claim to fame!).

Plus we could use some inline HTML if absolutely necessary.

[Rangi42]

Good point! I'd forgotten about HTML-in-Markdown for edge cases.

[aaaaaa123456789]

The choice of which format to use to write a webpage has no user visibility, so I have no horse in this race, but I honestly don't think you need any fancier formatting at all — it's documentation, not a sales page :P

[ISSOtm]

Good point! I'd forgotten about HTML-in-Markdown for edge cases.

I insist on the “if absolutely necessary” part, because HTML tags exclude exporting to other formats (PDF and/or man page, in our case). Though, as mentioned, we are currently managing quite well without, anyway.

[...] I honestly don't think you need any fancier formatting at all — it's documentation, not a sales page :P

Hey, the best April Fools jokes take a lot of pre-planning! :3

[ISSOtm]

This seems to be decided, but I'd like this to not happen in 0.9.0, since it's going to require a lot of effort, including coordinated across two repos and a pile of scripts.

(Hell, I'd suggest putting this off to the Rust rewrite, since it's going to be changing the way the documentation is managed, anyway.)

[Rangi42]

One example that I expect will be frequently necessary, and which I've used a lot before: allowing formatting inside inline code.

This doesn't work:

`HIGH(*n* + 2)`

But this does:

<code>HIGH(<em>n</em> + 2)</code>

[pinobatch]

I mentioned some things to consider about Ubuntu and dependency bloat in https://github.com/gbdev/rgbds/pull/1455#discussion_r1707225538. Quoting for convenience:

One practical problem with an HTML manual is that when a program is installed for one user, its HTML manual ends up inside $HOME/.local/share. Like other hidden folders, $HOME/.local is off-limits to web browsers in a Snap package. The default web browser under major Ubuntu flavors is Firefox in a Snap package. This limit of Snap has already caused people to be unable to view Rust documentation.

Another is that a lot of these static site generators used for building an HTML manual from source code rely on Node.js. This would significantly increase the total dependency download size and total dependency install footprint of RGBDS on all GNU/Linux distributions that . We would need to carefully consider make Node.js and NPM into dependencies for building and installing RGBDS.

[Rangi42]

rgbds-www uses Docusaurus already, which uses Node.js.

Presumably it would not be a dependency of building RGBDS, just a tool people could use to render docs/rgbasm.md into HTML, if they wanted to.

[pinobatch]

Once the docs come to rely more on HTML-in-Markdown, I fail to envision cases in which "if they wanted to" would be false.

[Rangi42]

HTML syntax (<code>, <em>, etc) is part of Markdown. Your preferred .md viewer/editor should support it already. The idea is not to start using <style> and <script>.

[pinobatch]

Then I appear to have some deep-seated misconceptions about how terminal users usually read Markdown files, and I'd appreciate correction.

[Rangi42]

"Terminal users"? I expect your browser is a GUI, not Lynx; so a command like md2html rgbasm.md - | firefox would work. (Or md2html rgbasm.md - | lynx, for that matter.) But, it looks like glow, Vim + Pandoc, markdown2html-converter, and probably others are some popular choices.