On Mon, Mar 11, 2019 at 12:40 PM elf <xxxxxx@ephemeral.net> wrote:
> Aren't we down a rat hole atm about what elements, tags, features, etc, and the best way to go about handling existing and future docs? :)

I (technically) agree with you, but at the same time I also
(practically) agree with Arthur.

For example for my own Scheme implementation I've used a S-expression
based syntax I came-up with, which is rendered as bellow:

  (the S-expression source)
  https://github.com/volution/vonuvoli-scheme/blob/development/documentation/libraries-r7rs.ss

  (as multiple HTML documents)
  https://vonuvoli.volution.ro/documentation/libraries-html/_libraries.html

  (as a single HTML document -- quite large!)
  https://vonuvoli.volution.ro/documentation/libraries.html

  (as multiple CommonMark documents)
  https://vonuvoli.volution.ro/documentation/libraries.md

> I would imagine that a very simple and clear semi-markup language would actually make it easier to submit, edit, and review srfis - html is a lot of extra writing for low value IF the goal is something machine parsable and semantic. If the goal is, as it has been, human review and understanding, then perhaps it would make sense if it was easier on the authors and readers, otherwise it should be relegated to a personal project and not a group discussion.

If (and this is just hypothetical) we would choose another markup
language then I would strongly suggest CommonMark, perhaps with a few
extensions.  (In fact the documentation above is built like this
S-expressions -> CommonMark -> HTML.)

We could also take into account something like reStructuredText,
however for that there is only one implementation, meanwhile for
CommonMark there are countless implementations in many programming
languages.

Ciprian.