GitHub's markdown doesn't understand commented out examples in tutorial

[brson]

See: https://github.com/mozilla/rust/blob/master/doc/tutorial/syntax.md

There are code examples prefixed with # that don't appear in the website version. We should probably try to make our markdown displays correctly on github.

[marijnh]

These are not commented out examples, but extra code used to make the examples runnable (which is important for keeping the tutorial in sync with the language). There is no markdown mechanism I know of that would allow us to do this in a portable manner. I'm not too concerned about the tutorial looking good on github, personally.

[brson]

That's pretty cool. Is there a mechanism set up to run these as part of the build? If not, what would it entail?

[brson]

I wonder if any of the extensions graydon's been playing with (pandoc, etc) has a way to deal with comments.

[marijnh]

They are not run as part of the build (and there are in fact two errors currently due to float::consts::pi not working). You do

cd doc/tutorial
RUSTC=/path/to/rustc bash test.sh

to get a list of failing fragments.

[nikomatsakis]

Neat.

[bstrie]

I was the one who brought up this issue, because I couldn't understand the purpose of the leading hashes in the following code fragment:

# fn the_stars_align() -> bool { false }
# fn something_else() -> bool { true }
let x = if the_stars_align() { 4 }
        else if something_else() { 3 }
        else { 0 };

"Are those syntax extensions? Attributes? Some sort of alternative commenting style?" Not being aware that the tutorial even existed on rust-lang.org, GitHub seemed the place to turn for the "official" tutorial. I don't know if I'll be the last person to make that assumption.

Would it be possible for the sources to contain a comment line at the top of each, something like:

# For the canonical version of the tutorial, see: http://www.rust-lang.org/doc/tutorial/

It's not really a big deal, but the syntax highlighting is very nice to have. :)

[graydon]

Think I'm going to close this; adding special comment-support to the format just so that someone viewing the .md source gets redirected to the canonical home of the built docs seems like overkill. Reopen if you disagree vehemently.