Language Specification in Markdown format

[ahejlsberg]

Fixes #213.

This pull request adds the language specification in Markdown format.

The pull request also includes a tool (word2md) that can convert Word documents to Markdown format. The tool uses the Word Automation APIs to start an instance of Word and access the contents of the document being converted. The tool must be run using the cscript.exe script host and requires Word to be installed on the target machine. The tool recognizes the specific Word styles used in the TypeScript Language Specification but could easily be adapted to other uses.

Note that the specification is tagged such that you can reference sections by their section number in hyperlinks. For example:

https://github.com/Microsoft/TypeScript/blob/master/doc/spec.md#3.6.1

[RyanCavanaugh]

Need to get rid of the Windows Script Host startup header (x2) in the .md output

[ahejlsberg]

Yup, just noticed that. It's gone now.

[RyanCavanaugh]

(Not sure why I can't leave a comment in the .md file)
Some emsp entities appearing in the export grammar:

 *ExportAssignment:*    export = *Identifier* ;

[mhegazy]

do not think we need this file checked in. we just need a Jake target, say "Jake spec" that would build this script and run it on the latest word doc to generate the .md file.

[ahejlsberg]

Agreed, we probably don't need the .js file. I wasn't sure how to modify the jakefile, but once I figure it out I can make it an automated step.

[mhegazy]

task generate-diagnostics should be a lot like this work. you will need to first compile scripts\word2md.ts, then run.

here is a sample.. I did not try to run it though :)

var docDirectory = "doc/";

var word2MDJS = path.join(scriptsDirectory, "word2md.js");
var word2MDTS = path.join(scriptsDirectory, "word2md.ts");
var specWord = path.join(docDirectory, "TypeScript Language Specification.docx");
var specMD = path.join(docDirectory, "spec.ms");

file(processDiagnosticMessagesTs)

// processDiagnosticMessages script
compileFile(word2MDJS,
            [word2MDTS],
            [word2MDJS],
            [],
            false);

// The generated diagnostics map; built for the compiler and for the 'generate-diagnostics' task
file(specMD, [word2MDJS, specWord], function () {
    var cmd = "node " + word2MDJS + " "  + specWord;
    console.log(cmd);
    var ex = jake.createExec([cmd]);
    // Add listeners for output and error
    ex.addListener("stdout", function(output) {
        process.stdout.write(output);
    });
    ex.addListener("stderr", function(error) {
        process.stderr.write(error);
    });
    ex.addListener("cmdEnd", function() {
        complete();
    });
    ex.run();    
}, {async: true})


desc("Generates a markdown version of the language specificiation");
task("generate-spec", [specMD])

[ahejlsberg]

The word2md tool has to run with cscript.exe and requires Word to be installed on the target machine (it uses the Word Automation APIs). Are we ok with those requirements in the jakefile?

[mhegazy]

I think so. it is not needed as part of the normal build targets (jake local, jake runtests).

[mhegazy]

I would change "spec.md" to "TypeScript Language Specification.md"

[ahejlsberg]

@mhegazy I went with "spec.md" because it makes hyperlinking easier (it is shorter and doesn't have blanks in it). I'm fine either way.

[mhegazy]

@ahejlsberg I do not feel strongly about it. it just seemed inconsistent.

[danquirk]

Something weird here with * at the end of 8.6.2:

[danquirk]

4.17

Colorization is obviously weird but we've also translated Operator= to ??==

[ahejlsberg]

@danquirk Formatting issue is caused by a paragraph mark that had italic formatting. Markdown doesn't do well with formatting that attempts to span lines. Something to be aware of when editing the spec.

Regarding ??=, I changed it from Operator= because Markdown doesn't allow italics in code blocks. The red highlighting is caused by GitHub's Markdown formatter, presumably because the code isn't properly formatted TypeScript (which the code block claims to be). Fix would involve the tool giving you control over what type of code block to emit based on different styles, e.g. "Code" vs. "TypeScript Code". I may do that at some later time.

[CyrusNajmabadi]

you cal find.execute with the same first set of 9 args. Can you extract out a helper to do this?

[CyrusNajmabadi]

👍

[ahejlsberg]

I'm going to merge this pull request and start a separate one for automating the Word-to-Markdown conversion.