Suggestion: Language Spec as markdown

[fdecampredon]

Instead of doc and pdf if language spec was written with markdown (or asciidoc) it could help to follow changes, and perhaps even for pull-request in the future ?

[Bartvds]

+1

There are many people who want this (I had a codeplex ticket for this once).

This guy had enough and made a start on a markdown conversion: https://github.com/teppeis/typescript-spec-md

Also it should be partitioned in chapters instead of one massive blob with a unusable scrollbar, and be online viewable with proper deeplinking.

[vvakame]

👍

[Diullei]

👍 , please!

[teppeis]

👍 nice!

This guy had enough and made a start on a markdown conversion: https://github.com/teppeis/typescript-spec-md

Yes, I made it. Official version is much better!

[Bartvds]

@teppeis But it was a good idea! We need something like that as official version that gets updated (and versioned in git).

PDF and Docx are so old world.

[Diullei]

I agree with @Bartvds, a PDF or Word document is not practical in this case.

[joewood]

👍

[johnnyreilly]

👍 fantastic idea!

[omidkrad]

Adopt everything "GitHub"

[RyanCavanaugh]

This was well-received in the design meeting. We're looking into what we would need to do to make it readable/navigable, since a giant webpage would be perhaps unwieldy and probably we don't want to break it into multiple pages (since you often need to search across the whole document).

[RyanCavanaugh]

Discussed in design meeting. We'd prefer to keep the Word document as the authoritative source as it's easier to do cross-referencing, section renumbering, global find, and navigation than in Markdown.

We'd definitely like to have a Word -> Markdown conversion tool to produce a web-readable and GitHub-diffable version of the spec, even if that tool only works specifically for the spec. Any recommendations?