diff --git a/doc/TypeScript Language Specification.docx b/doc/TypeScript Language Specification.docx index 4eb94908b57..370e5e25d89 100644 Binary files a/doc/TypeScript Language Specification.docx and b/doc/TypeScript Language Specification.docx differ diff --git a/doc/images/image1.png b/doc/images/image1.png new file mode 100644 index 00000000000..e1db88fa4f8 Binary files /dev/null and b/doc/images/image1.png differ diff --git a/doc/images/image2.png b/doc/images/image2.png new file mode 100644 index 00000000000..c0321038057 Binary files /dev/null and b/doc/images/image2.png differ diff --git a/doc/images/image3.png b/doc/images/image3.png new file mode 100644 index 00000000000..5fe2ecb8f3e Binary files /dev/null and b/doc/images/image3.png differ diff --git a/doc/images/image4.png b/doc/images/image4.png new file mode 100644 index 00000000000..13a6d8fcfb6 Binary files /dev/null and b/doc/images/image4.png differ diff --git a/doc/spec.md b/doc/spec.md index a7947b19926..df3f4d90b0a 100644 --- a/doc/spec.md +++ b/doc/spec.md @@ -262,7 +262,7 @@ function f() { To benefit from this inference, a programmer can use the TypeScript language service. For example, a code editor can incorporate the TypeScript language service and use the service to find the members of a string object as in the following screen shot. -/ +  ![](images/image1.png) In this example, the programmer benefits from type inference without providing type annotations. Some beneficial tools, however, do require the programmer to provide type annotations. In TypeScript, we can express a parameter requirement as in the following code fragment. @@ -410,7 +410,7 @@ This signature denotes that a function may be passed as the parameter of the '$' A typical client would not need to add any additional typing but could just use a community-supplied typing to discover (through statement completion with documentation tips) and verify (through static checking) correct use of the library, as in the following screen shot. -/ +  ![](images/image2.png) Section [3.3](#3.3) provides additional information about object types. @@ -627,7 +627,7 @@ An important goal of TypeScript is to provide accurate and straightforward types JavaScript programming interfaces often include functions whose behavior is discriminated by a string constant passed to the function. The Document Object Model makes heavy use of this pattern. For example, the following screen shot shows that the 'createElement' method of the 'document' object has multiple signatures, some of which identify the types returned when specific strings are passed into the method. -/ +  ![](images/image3.png) The following code fragment uses this feature. Because the 'span' variable is inferred to have the type 'HTMLSpanElement', the code can reference without static error the 'isMultiline' property of 'span'. @@ -638,7 +638,7 @@ span.isMultiLine = false; // OK: HTMLSpanElement has isMultiline property In the following screen shot, a programming tool combines information from overloading on string parameters with contextual typing to infer that the type of the variable 'e' is 'MouseEvent' and that therefore 'e' has a 'clientX' property. -/ +  ![](images/image4.png) Section [3.9.2.4](#3.9.2.4) provides details on how to use string literals in function signatures. diff --git a/scripts/word2md.js b/scripts/word2md.js deleted file mode 100644 index e80275d5b2d..00000000000 --- a/scripts/word2md.js +++ /dev/null @@ -1,235 +0,0 @@ -// word2md - Word to Markdown conversion tool -// -// word2md converts a Microsoft Word document to Markdown formatted text. 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 name of the document to convert must be specified -// as a command line argument and the resulting Markdown is written to standard output. The -// tool recognizes the specific Word styles used in the TypeScript Language Specification. -var sys = (function () { - var fileStream = new ActiveXObject("ADODB.Stream"); - fileStream.Type = 2 /*text*/; - var binaryStream = new ActiveXObject("ADODB.Stream"); - binaryStream.Type = 1 /*binary*/; - var args = []; - for (var i = 0; i < WScript.Arguments.length; i++) { - args[i] = WScript.Arguments.Item(i); - } - return { - args: args, - createObject: function (typeName) { return new ActiveXObject(typeName); }, - write: function (s) { - WScript.StdOut.Write(s); - }, - writeFile: function (fileName, data) { - fileStream.Open(); - binaryStream.Open(); - try { - // Write characters in UTF-8 encoding - fileStream.Charset = "utf-8"; - fileStream.WriteText(data); - // We don't want the BOM, skip it by setting the starting location to 3 (size of BOM). - fileStream.Position = 3; - fileStream.CopyTo(binaryStream); - binaryStream.SaveToFile(fileName, 2 /*overwrite*/); - } - finally { - binaryStream.Close(); - fileStream.Close(); - } - } - }; -})(); -function convertDocumentToMarkdown(doc) { - var result = ""; - var lastStyle; - var lastInTable; - var tableColumnCount; - var tableCellIndex; - var columnAlignment = []; - function setProperties(target, properties) { - for (var name in properties) { - if (properties.hasOwnProperty(name)) { - var value = properties[name]; - if (typeof value === "object") { - setProperties(target[name], value); - } - else { - target[name] = value; - } - } - } - } - function findReplace(findText, findOptions, replaceText, replaceOptions) { - var find = doc.range().find; - find.clearFormatting(); - setProperties(find, findOptions); - var replace = find.replacement; - replace.clearFormatting(); - setProperties(replace, replaceOptions); - find.execute(findText, false, false, false, false, false, true, 0, true, replaceText, 2); - } - function fixHyperlinks() { - var count = doc.hyperlinks.count; - for (var i = 0; i < count; i++) { - var hyperlink = doc.hyperlinks.item(i + 1); - var address = hyperlink.address; - if (address && address.length > 0) { - var textToDisplay = hyperlink.textToDisplay; - hyperlink.textToDisplay = "[" + textToDisplay + "](" + address + ")"; - } - } - } - function write(s) { - result += s; - } - function writeTableHeader() { - for (var i = 0; i < tableColumnCount - 1; i++) { - switch (columnAlignment[i]) { - case 1: - write("|:---:"); - break; - case 2: - write("|---:"); - break; - default: - write("|---"); - } - } - write("|\n"); - } - function trimEndFormattingMarks(text) { - var i = text.length; - while (i > 0 && text.charCodeAt(i - 1) < 0x20) - i--; - return text.substr(0, i); - } - function writeBlockEnd() { - switch (lastStyle) { - case "Code": - write("```\n\n"); - break; - case "List Paragraph": - case "Table": - case "TOC": - write("\n"); - break; - } - } - function writeParagraph(p) { - var text = p.range.text; - var style = p.style.nameLocal; - var inTable = p.range.tables.count > 0; - var level = 1; - var sectionBreak = text.indexOf("\x0C") >= 0; - text = trimEndFormattingMarks(text); - if (inTable) { - style = "Table"; - } - else if (style.match(/\s\d$/)) { - level = +style.substr(style.length - 1); - style = style.substr(0, style.length - 2); - } - if (lastStyle && style !== lastStyle) { - writeBlockEnd(); - } - switch (style) { - case "Heading": - case "Appendix": - var section = p.range.listFormat.listString; - write("####".substr(0, level) + ' ' + section + " " + text + "\n\n"); - break; - case "Normal": - if (text.length) { - write(text + "\n\n"); - } - break; - case "List Paragraph": - write(" ".substr(0, p.range.listFormat.listLevelNumber * 2 - 2) + "* " + text + "\n"); - break; - case "Grammar": - write("  " + text.replace(/\s\s\s/g, " ").replace(/\x0B/g, " \n   ") + "\n\n"); - break; - case "Code": - if (lastStyle !== "Code") { - write("```TypeScript\n"); - } - else { - write("\n"); - } - write(text.replace(/\x0B/g, " \n") + "\n"); - break; - case "Table": - if (!lastInTable) { - tableColumnCount = p.range.tables.item(1).columns.count + 1; - tableCellIndex = 0; - } - if (tableCellIndex < tableColumnCount) { - columnAlignment[tableCellIndex] = p.alignment; - } - write("|" + text); - tableCellIndex++; - if (tableCellIndex % tableColumnCount === 0) { - write("\n"); - if (tableCellIndex === tableColumnCount) { - writeTableHeader(); - } - } - break; - case "TOC Heading": - write("## " + text + "\n\n"); - break; - case "TOC": - var strings = text.split("\t"); - write(" ".substr(0, level * 2 - 2) + "* [" + strings[0] + " " + strings[1] + "](#" + strings[0] + ")\n"); - break; - } - if (sectionBreak) { - write("
\n\n"); - } - lastStyle = style; - lastInTable = inTable; - } - function writeDocument() { - var title = doc.builtInDocumentProperties.item(1) + ""; - if (title.length) { - write("# " + title + "\n\n"); - } - for (var p = doc.paragraphs.first; p; p = p.next()) { - writeParagraph(p); - } - writeBlockEnd(); - } - findReplace("<", {}, "<", {}); - findReplace("<", { style: "Code" }, "<", {}); - findReplace("<", { style: "Code Fragment" }, "<", {}); - findReplace("<", { style: "Terminal" }, "<", {}); - findReplace("", { font: { subscript: true } }, "^&", { font: { subscript: false } }); - findReplace("", { style: "Code Fragment" }, "`^&`", { style: -66 /* default font */ }); - findReplace("", { style: "Production" }, "*^&*", { style: -66 /* default font */ }); - findReplace("", { style: "Terminal" }, "`^&`", { style: -66 /* default font */ }); - findReplace("", { font: { bold: true, italic: true } }, "***^&***", { font: { bold: false, italic: false } }); - findReplace("", { font: { italic: true } }, "*^&*", { font: { italic: false } }); - doc.fields.toggleShowCodes(); - findReplace("^19 REF", {}, "[^&](#^&)", {}); - doc.fields.toggleShowCodes(); - fixHyperlinks(); - writeDocument(); - result = result.replace(/\x85/g, "\u2026"); - result = result.replace(/\x96/g, "\u2013"); - result = result.replace(/\x97/g, "\u2014"); - return result; -} -function main(args) { - if (args.length !== 2) { - sys.write("Syntax: word2md \n"); - return; - } - var app = sys.createObject("Word.Application"); - var doc = app.documents.open(args[0]); - sys.writeFile(args[1], convertDocumentToMarkdown(doc)); - doc.close(false); - app.quit(); -} -main(sys.args); -//# sourceMappingURL=file:///c:/ts/scripts/word2md.js.map \ No newline at end of file diff --git a/scripts/word2md.ts b/scripts/word2md.ts index ec9ed634b3c..f602c700ff9 100644 --- a/scripts/word2md.ts +++ b/scripts/word2md.ts @@ -72,6 +72,9 @@ module Word { listFormat: ListFormat; tables: Tables; text: string; + textRetrievalMode: { + includeHiddenText: boolean; + } words: Ranges; } @@ -258,13 +261,27 @@ function convertDocumentToMarkdown(doc: Word.Document): string { function writeParagraph(p: Word.Paragraph) { - var text = p.range.text; + var range = p.range; + var text = range.text; var style = p.style.nameLocal; - var inTable = p.range.tables.count > 0; + var inTable = range.tables.count > 0; var level = 1; var sectionBreak = text.indexOf("\x0C") >= 0; text = trimEndFormattingMarks(text); + if (text === "/") { + // An inline image shows up in the text as a "/". When we see a paragraph + // consisting of nothing but "/", we check to see if the paragraph contains + // hidden text and, if so, emit that instead. The hidden text is assumed to + // contain an appropriate markdown image link. + range.textRetrievalMode.includeHiddenText = true; + var fullText = range.text; + range.textRetrievalMode.includeHiddenText = false; + if (text !== fullText) { + text = "  " + fullText.substr(1); + } + } + if (inTable) { style = "Table"; } @@ -280,7 +297,7 @@ function convertDocumentToMarkdown(doc: Word.Document): string { case "Heading": case "Appendix": - var section = p.range.listFormat.listString; + var section = range.listFormat.listString; write("####".substr(0, level) + ' ' + section + " " + text + "\n\n"); break; @@ -291,7 +308,7 @@ function convertDocumentToMarkdown(doc: Word.Document): string { break; case "List Paragraph": - write(" ".substr(0, p.range.listFormat.listLevelNumber * 2 - 2) + "* " + text + "\n"); + write(" ".substr(0, range.listFormat.listLevelNumber * 2 - 2) + "* " + text + "\n"); break; case "Grammar": @@ -310,7 +327,7 @@ function convertDocumentToMarkdown(doc: Word.Document): string { case "Table": if (!lastInTable) { - tableColumnCount = p.range.tables.item(1).columns.count + 1; + tableColumnCount = range.tables.item(1).columns.count + 1; tableCellIndex = 0; } if (tableCellIndex < tableColumnCount) {