4 ms·

I spent some time working with the Sphinx source code (the main user of rst), and found that reStructuredText is very poorly suited for porting to any other pla

by irskep 5y ago

I spent some time working with the Sphinx source code (the main user of rst), and found that reStructuredText is very poorly suited for porting to any other platform because a lot of the "spec" is just whatever the Python implementation is doing. IIRC it's also not context-free, so it's more laborious to write a parser. "Technically superior" it is not. I also think a lot of the syntax is obtuse. That said, I really dislike that Markdown does not have any affordance for adding custom markup. Because of that, it's poorly suited to technical documentation; there's no official way to say "insert the autogenerated docs for function X here." Every doc system that uses Markdown invents its own special thing. So, I think there's still space for markup languages that find a balance between prettiness and extensibility. I did my own experiment that let you define custom HTML tags but didn't have a reason to really finish the project.

tannhaeuser 5y ago
Markdown lets you drop into inline or block-level HTML doesn't it? And if that isn't enough and you want your own markup vocabulary, render-to-HTML pipeline or markup decorator/macro expander, there's always SGML which can be customized to parse Markdown to HTML, or your own extension or custom syntax.
- irskep 5y ago
  OK, yes, but at that point you're writing your own parser for a custom language that is not Markdown anymore. Markdown _does not_ support SGML. Look at the source for any CommonMark parser—there's a whitelist for the HTML tags. Compare to rst and Sphinx. It's very obvious how you're supposed to add new inline and block elements. There is a standard syntax for adding parameters to directives. Markdown has nothing, so there are a dozen incompatible variations that are only available in some parsers. On the other hand, reStructuredText also defines a whole system for transforming the document tree, which as far as I know, no other markup language does.
  - tannhaeuser 5y ago
    > reStructuredText also defines a whole system for transforming the document tree, which as far as I know, no other markup language does I guess we're not agreeing what a "markup language" is then, since the things you mention, plus defining your formal vocabulary etc., is very much the entire point of SGML/XML/HTML. I'm aware the term "markup" is used inflationary to mean all things text to all people ever since YAML came up with its original, flawed meaning of that acronym, but "markup" in the original sense really is just any layout instruction and proofreading comment written in a shorthand notation on a preprint copy, and has a very specific meaning developed from there in digital text, quite different from "any convention to encode text formatting using ASCII" (I know since my boss, a typesetter by profession, way back used that notation for reviewing/dissing my prints, and ruining my weekend ;) Markdown indeed is only a set of Wiki syntax conventions for HTML specifically, and as such only allows HTML rather than arbitrary inline/block elements. But it's quite natural to implement Markdown (or rST) as a SHORTREF syntax within the greater SGML framework to give you site building, validation, transformations, text macros, etc. etc.
- Fire-Dragon-DoL 5y ago
  It does, but you can't use markdown within an html tag. That is, once you go down to html, you can't mix abd match, which would have been incredibly helpful (think html tables)

by irskep 5y ago

tannhaeuser 5y ago

Markdown lets you drop into inline or block-level HTML doesn't it? And if that isn't enough and you want your own markup vocabulary, render-to-HTML pipeline or markup decorator/macro expander, there's always SGML which can be customized to parse Markdown to HTML, or your own extension or custom syntax.

irskep 5y ago
OK, yes, but at that point you're writing your own parser for a custom language that is not Markdown anymore. Markdown _does not_ support SGML. Look at the source for any CommonMark parser—there's a whitelist for the HTML tags. Compare to rst and Sphinx. It's very obvious how you're supposed to add new inline and block elements. There is a standard syntax for adding parameters to directives. Markdown has nothing, so there are a dozen incompatible variations that are only available in some parsers. On the other hand, reStructuredText also defines a whole system for transforming the document tree, which as far as I know, no other markup language does.
- tannhaeuser 5y ago
  > reStructuredText also defines a whole system for transforming the document tree, which as far as I know, no other markup language does I guess we're not agreeing what a "markup language" is then, since the things you mention, plus defining your formal vocabulary etc., is very much the entire point of SGML/XML/HTML. I'm aware the term "markup" is used inflationary to mean all things text to all people ever since YAML came up with its original, flawed meaning of that acronym, but "markup" in the original sense really is just any layout instruction and proofreading comment written in a shorthand notation on a preprint copy, and has a very specific meaning developed from there in digital text, quite different from "any convention to encode text formatting using ASCII" (I know since my boss, a typesetter by profession, way back used that notation for reviewing/dissing my prints, and ruining my weekend ;) Markdown indeed is only a set of Wiki syntax conventions for HTML specifically, and as such only allows HTML rather than arbitrary inline/block elements. But it's quite natural to implement Markdown (or rST) as a SHORTREF syntax within the greater SGML framework to give you site building, validation, transformations, text macros, etc. etc.
Fire-Dragon-DoL 5y ago
It does, but you can't use markdown within an html tag. That is, once you go down to html, you can't mix abd match, which would have been incredibly helpful (think html tables)