Render the documentation as HTML

[masak]

As a later step, we can also publish it as GitHub pages.

I find the Postgres documentation to have a pleasant-to-read stylesheet. Maybe start from something that looks similar and then tweak it to suit the Bel documentation?

[masak]

This issue seems to be the closest issue where I can drop this suggestion:

Visual Basic 3.0 Language Reference manual (1993)

Every entry in the Language Reference manual is formatted in a clear structured form. It still stands as an excellent template for any programming language reference:

Property name

• Applies to
• Description
• Usage
• Remarks
• Data type
• See also
• Example

I have this book at home. I should take a closer look at it and confirm.

[masak]

Checked out the (linked-above) PDF:

• It is nice.
• Not all the entries in the list are used in each chapter. Only the ones that add value.
• There are also other entries, such as "Syntax", "Syntax 1", "Syntax 2", "Setting", "Toolbox Icon", "Example 1", "Example 2". The point is that these categories are mostly fixed, but they flex enough to provide value too.
• There are also little "Caution" boxes, demarcated by double lines. That's nice and charming. Also "Note", "Distribution Note", and "Tip". But these all have single lines.
• The manual is not afraid to use tables, when presenting information that way makes sense. This seems to be preferable even to bullet lists.
• There's also a kind of "definition list" tables, with two columns. (E.g. the "part"/"description" table explaining the different bits of syntax in the "Circle" chapter.) Also found a similar but three-column table.
• The fact that the "Usage" entry uses a kind of simplified BNF, including making good use of italics and bold, helps a lot. I think we could pull something like that off. The trick is to "intuitively" communicate that (e.g.) italics means that it's an arbitrary thing of the named type, and square brackets mean that the thing is optional. The {a|b|c} syntax is used for alternation, and bold for fixed/literal syntax. Bold is also consistently used outside of the "Usage" section, whenever referring to something that's a chapter in the reference.
• Screenshots, where it makes sense.
• Sometimes, the text says 'See "Activate, Deactivate Events"' (in the chapter "Deactivate Event"). In a hyperlinked version, this might be the one thing where we just link directly, instead of forcing the user to click an extra time.