Repository navigation
Suggestion: Language Spec as markdown #213
Description
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 ?
{{ message }}
Activity
Bartvds commentedon Jul 23, 2014
+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 commentedon Jul 23, 2014
👍
Diullei commentedon Jul 23, 2014
👍 , please!
teppeis commentedon Jul 23, 2014
👍 nice!
Yes, I made it. Official version is much better!
Bartvds commentedon Jul 23, 2014
Teppei Sato (@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 commentedon Jul 23, 2014
I agree with Bart van der Schoor (@Bartvds), a PDF or Word document is not practical in this case.
joewood commentedon Jul 23, 2014
👍
johnnyreilly commentedon Jul 23, 2014
👍 fantastic idea!
omidkrad commentedon Jul 23, 2014
Adopt everything "GitHub"
RyanCavanaugh commentedon Jul 28, 2014
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 commentedon Sep 19, 2014
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 commentedon Sep 20, 2014
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:
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 commentedon Sep 20, 2014
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 commentedon Sep 22, 2014
Good start. I was playing with pandoc myself. Using the commands you used above I get similar results.
Issues I see: