Tock: TRD1: Should we use CommonMark for TRDs instead pointing to Gruber's spec?

[ppannuto]

The world is starting to create an actual markdown standard: http://commonmark.org/

Or we could go all the way to GitHub's formal spec given that's where things are rendered (mostly): https://github.com/blog/2333-a-formal-spec-for-github-flavored-markdown - but I think there was (reasonable) aversion to tying too tightly to github

But in any case, I think tying ourselves to the old Daring Fireball spec isn't the right choice

[szechy]

GitHub's explanation of GitHub Flavored Markdown (GFM) from the document you listed frames GFM as a superset of Common Mark to support special GitHub features:

We've updated the original CommonMark spec with formal definitions for the custom Markdown features that are commonly used in GitHub, such as tables, task lists, and autolinking.

I think it makes sense to move forward with CommonMark to maintain full compatibility with non-GitHub systems (that will presumably standardize around CommonMark).

[alevy]

I actually think we want GFM specifically. CommonMark is missing pretty important features like tables and strikethrough, and Pandoc markdown matched GFM nearly identically (so there is a reasonable way to pretty reliably export the same markdown to non-HTML formats).

[phil-levis]

Given the totally ridiculous state of Markdown, my complete lack of interest in using a website-specific variant, and its poor features, I’m all for dropping this piece of steaming crap in favor of Restructured Text (or some other format that it’s a steaming piece of crap).

Phil

On Mar 21, 2017, at 7:54 AM, Amit Levy [e-mail] wrote:

I actually think we want GFM specifically. CommonMark is missing pretty important features like tables and strikethrough, and Pandoc markdown matched GFM nearly identically (so there is a reasonable way to pretty reliably export the same markdown to non-HTML formats).

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub, or mute the thread.

[ppannuto]

Heh. I know you have some (justified) issues with Markdown, but I still think it's the right choice:

• Markdown is in vogue: This is trite on the surface, but the reality is, if I see a project that uses rST, my instinct is that the project is crufty and out-of-date. It's akin to seeing something hosted on sourceforge in 2017. It's an immediate negative impression*
• Markdown syntax is more accessible: This is a pro and a con in practice. It's why you see Markdown used pretty universally in applications where interfacing with non-technical folks is important. It's also why it's hard to do anything remotely advanced in Markdown. The extensibility of rST is a big win, especially for technical documentation, which is what the language is/was designed for
• Rust uses markdown for documentation: We're pretty tied into Rust with this project, so it feels like there's a big consistency win here - related to this @alevy what flavor of CommonMark does Rust use? Stock or GFM?

Given that TRDs are somewhat of a separate documentation path, it wouldn't be inappropriate to use a different formatting engine for them. But, if we're going to go that route, I'd advocate for something like Latex. In my mind rST sits in this awkward middle ground where it tried to be a text-like language, but then added too many features, and is now a mess of ::, _, and other arcane symbols that need to have learned meanings. It loses on being a readable text-like language and it's less powerful than a proper typesetting language. Jack of all trades, master of none.

*hah: Brad points out to me that the restructured text project is hosted on sourceforge, kind of doubling this point

[phil-levis]

Vogue doesn't matter. We are engineering, not fashion. We could also put our docs in Pokémon Go.

Accessible is subjective and personal. I know people who think Prolog is accessible.

The only good reason you give is that Rust uses it. If the argument is that we should use the Markdown that Rust uses, I could maybe agree with that.

Phil [sent from a phone]

On Mar 21, 2017, at 10:37 AM, Pat Pannuto [e-mail] wrote:

Heh. I know you have some (justified) issues with Markdown, but I still think it's the right choice:

Markdown is in vogue: This is trite on the surface, but the reality is, if I see a project that uses rST, my instinct is that the project is crufty and out-of-date. It's akin to seeing something hosted on sourceforge in 2017. It's an immediate negative impression*
Markdown syntax is more accessible: This is a pro and a con in practice. It's why you see Markdown used pretty universally in applications where interfacing with non-technical folks is important. It's also why it's hard to do anything remotely advanced in Markdown. The extensibility of rST is a big win, especially for technical documentation, which is what the language is/was designed for
Rust uses markdown for documentation: We're pretty tied into Rust with this project, so it feels like there's a big consistency win here - related to this @alevy what flavor of CommonMark does Rust use? Stock or GFM?
Given that TRDs are somewhat of a separate documentation path, it wouldn't be inappropriate to use a different formatting engine for them. But, if we're going to go that route, I'd advocate for something like Latex. In my mind rST sits in this awkward middle ground where it tried to be a text-like language, but then added too many features, and is now a mess of ::, _, and other arcane symbols that need to have learned meanings. It loses on being a readable text-like language and it's less powerful than a proper typesetting language. Jack of all trades, master of none.

*hah: Brad points out to me that the restructured text project is hosted on sourceforge, kind of doubling this point

—
You are receiving this because you commented.
Reply to this email directly, view it on GitHub, or mute the thread.

[alevy]

The only good reason you give is that Rust uses it. If the argument is that we should use the Markdown that Rust uses, I could maybe agree with that.

Can there be more than one argument, and that can be one of them?

But to this point specifically, Rust inline documentation is markdown, so using something else generally doesn't make a ton of sense.

[phil-levis]

Sure there can be multiple reasons. But to get back to the point, we need to pick which variant of Markdown we're going to use, and stick with it. I'm strongly against using a GitHub specific version, but if there's some more general variant which GitHub is a superset of, that's fine.

My point is that I want to use the best tool for the job; I'm worried about longevity, portability, and ease of use, not whether the cool kids use it. I think it's amazingly short-sighted to care more about where a package is hosted than whether the generated documentation is easier to read.

[alevy]

The GitHub variant of markdown _is_ officially a superset of CommonMark, which is basically the version of markdown used in practice (by pandoc, reddit, stackoverflow, GitHub, GitLab, jekyll, etc).

Also, GitHub _extends_ CommonMark in fairly standard ways (tables are the same as pandoc and jekyll, for example) or with GitHub specific nice-to-haves-but-not-breaking like automatically linking to commits if you put write it's hash (which just renders as regular text otherwise).

My vote is to stick with Markdown (mostly because Rust docs are also Markdown, and realistically a _lot_ of TRD stuff should really end up in some form or another in inline docs). Assuming we stick with markdown we should specify CommonMark. Using GitHub-style tables are fine, as long as they are formatted such they are readable as text (which is good practice anyway).

[ppannuto]

care more about where a package is hosted

Okay.. I don't want to belabor this, but I do think it's important to recognize that paying _some_ mind to non-code factors is important. If I see a project hosted on sourceforge, my initial expectation is 50/50 that it'll work, and if searching for a library, I'll skip the ones there unless they're the only option. I wouldn't even try downloading a project hosted with CVS today (would you use something hosted with RCS?).

These things _do_ impact the discoverability and impression of a project. They are _less_ important than working code and quality documentation, but they should not be completely ignored.

---

To the actual point: using raw CommonMark almost certainly is not the right choice. In the way that you could use strict, pedantic, ansi C89, but people jumped on board gcc's C flavors pretty quickly and they worked their way back into the C spec, CommonMark is the minimal base. GitHub Markdown is formally specified, GitHub is one of 6 on the CommonMark board, and the expressly stated intent is to move Github-specific variations into CommonMark over time.

We spent a little while reading around why the Rust community went markdown ( https://internals.rust-lang.org/t/rustdoc-restructuredtext-vs-markdown/356 , https://github.com/rust-lang/rust/issues/29474 , and links from those ). I walked away from those pretty unconvinced in both directions. My personal bend is to favor usability and accessibility, so I end up on the Markdown side of the fence, but could be swayed. The most compelling to me remains matching Rust, especially given the value and intent of rustdoc. I haven't heard a compelling argument for having two documentation systems in the project, and one of them is immutable.

I just saw Amit's comment come in which I think echoes much of this.