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?

[robertknight]

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.

LaTeX would give you the combination of these features plus Git-diff friendliness and easy export to PDF or HTML. Unfortunately I appreciate that would require some effort to convert the spec and might be unfamiliar inside Microsoft. pandoc can help with this.

This is a quick attempt at automatic conversion of the existing Word spec to Markdown using pandoc and doctoc : https://gist.github.com/robertknight/c866f6ff71d4e3cedddd .

This was produced as follows:

pandoc --toc --standalone zip/TypeScript\ Language\ Specification.docx -t 'markdown_github+auto_identifiers' -o typescript.md
doctoc typescript.md

The main omission is that code blocks are not formatted as such. I think that could be addressed outside of pandoc by post-processing the output to auto-detect and format code blocks (ie. auto-indent any blocks whose contents are sufficiently TypeScript/JavaScript-like), or possibly in a pandoc extension.

[robertknight]

Looks like pandoc does support generating code blocks in the output when processing docx input files. The style used for the relevant blocks in Word just needs to be named "SourceCode". For code fragments in a paragraph, the style needs to be named "VerbatimChar". In the current spec .docx it is named "Code".

See https://github.com/jgm/pandoc/blob/master/src/Text/Pandoc/Readers/Docx.hs for details.

[danquirk]

Good start. I was playing with pandoc myself. Using the commands you used above I get similar results.

Issues I see:

• Some characters aren't converted correctly. Did you manually fix this? I see smart quotes and some whitespace being turned into gibberish. Fairly simple to find/replace away the mistakes but annoying nonetheless.
• Grammar fragments in sections are not styled correctly. Unsure of an immediate solution here.
• Code segments are not colorized for TypeScript. I did a bulk replace of the Code style in Word with SourceCode which works for getting the code into Code Block style in GitHub Flavored Markdown. I was hoping it would emit ``` to format the Fenced Code Blocks so it'd be a simple find/replace to add the correct language formatter.
• Some tables are poorly formatted (ex 3.7.2.1 Type Parameters)
• Lost the header numbering (not sure whether this is pandoc or doctoc's fault)