From eb666cb1f1f5b9ea5ad9691c7e84135adb58b31e Mon Sep 17 00:00:00 2001 From: Michael Williamson Date: Sat, 30 Apr 2016 17:16:20 +0100 Subject: Add README.md for .NET --- dotnet/README.md | 394 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 394 insertions(+) create mode 100644 dotnet/README.md diff --git a/dotnet/README.md b/dotnet/README.md new file mode 100644 index 0000000..82aebb5 --- /dev/null +++ b/dotnet/README.md @@ -0,0 +1,394 @@ +# Mammoth .docx to HTML converter for .NET + +Mammoth is designed to convert .docx documents, +such as those created by Microsoft Word, +and convert them to HTML. +Mammoth aims to produce simple and clean HTML by using semantic information in the document, +and ignoring other details. +For instance, +Mammoth converts any paragraph with the style `Heading 1` to `h1` elements, +rather than attempting to exactly copy the styling (font, text size, colour, etc.) of the heading. + +There's a large mismatch between the structure used by .docx and the structure of HTML, +meaning that the conversion is unlikely to be perfect for more complicated documents. +Mammoth works best if you only use styles to semantically mark up your document. + +The following features are currently supported: + +* Headings. + +* Lists. + +* Customisable mapping from your own docx styles to HTML. + For instance, you could convert `WarningHeading` to `h1.warning` by providing an appropriate style mapping. + +* Tables. + The formatting of the table itself, such as borders, is currently ignored, + but the formatting of the text is treated the same as in the rest of the document. + +* Footnotes and endnotes. + +* Images. + +* Bold, italics, underlines, strikethrough, superscript and subscript. + +* Links. + +* Line breaks. + +* Text boxes. The contents of the text box are treated as a separate paragraph + that appears after the paragraph containing the text box. + +## Installation + +Available on [NuGet](https://www.nuget.org/packages/Mammoth/). + +``` +Install-Package Mammoth +``` + +## Other supported platforms + +* [JavaScript](https://github.com/mwilliamson/mammoth.js), both the browser and node.js. + Available [on npm](https://www.npmjs.com/package/mammoth). + +* [Python](https://github.com/mwilliamson/python-mammoth). + Available [on PyPI](https://pypi.python.org/pypi/mammoth). + +* [WordPress](https://wordpress.org/plugins/mammoth-docx-converter/). + +* [Java](https://github.com/mwilliamson/java-mammoth). + Available on Maven Central. + +## Usage + +### Library + +#### Basic conversion + +To convert an existing .docx file to HTML, +create an instance of `DocumentConverter` and +pass the path of the file to `ConvertToHtml`. +For instance: + +```csharp +using Mammoth; + +var converter = new DocumentConverter(); +var result = converter.ConvertToHtml("document.docx"); +var html = result.Value; // The generated HTML +var warnings = result.Warnings; // Any warnings during conversion +``` + +You can also extract the raw text of the document by using `ExtractRawText`. +This will ignore all formatting in the document. +Each paragraph is followed by two newlines. + +```csharp +var converter = new DocumentConverter(); +var result = converter.ExtractRawText("document.docx"); +var html = result.Value; // The raw text +var warnings = result.Warnings; // Any warnings during conversion +``` + +#### Custom style map + +By default, +Mammoth maps some common .docx styles to HTML elements. +For instance, +a paragraph with the style name `Heading 1` is converted to a `h1` element. +You can add custom style maps by calling `AddStyleMap(string)`. +A description of the syntax for style maps can be found in the section "Writing style maps". +For instance, if paragraphs with the style name `Section Title` should be converted to `h1` elements, +and paragraphs with the style name `Subsection Title` should be converted to `h2` elements: + +```csharp +var converter = new DocumentConverter() + .AddStyleMap("p[style-name='Section Title'] => h1:fresh") + .AddStyleMap("p[style-name='Subsection Title'] => h2:fresh"); +``` + +You can also pass in the entire style map as a single string, +which can be useful if style maps are stored in text files: + +```csharp +var styleMap = + "p[style-name='Section Title'] => h1:fresh\n" + + "p[style-name='Subsection Title'] => h2:fresh"; +var converter = new DocumentConverter() + .AddStyleMap(styleMap); +``` + +The most recently-added styles have the greatest precedence. +User-defined style mappings are used in preference to the default style mappings. +To stop using the default style mappings altogether, +call `DisableDefaultStyleMap`: + +```csharp +var converter = new DocumentConverter() + .DisableDefaultStyleMap(); +``` + +#### Bold + +By default, bold text is wrapped in `` tags. +This behaviour can be changed by adding a style mapping for `b`. +For instance, to wrap bold text in `` tags: + +```csharp +var converter = new DocumentConverter() + .AddStyleMap("b => em"); +``` + +#### Italic + +By default, italic text is wrapped in `` tags. +This behaviour can be changed by adding a style mapping for `i`. +For instance, to wrap italic text in `` tags: + +```csharp +var converter = new DocumentConverter() + .AddStyleMap("i => strong"); +``` + +#### Underline + +By default, the underlining of any text is ignored since underlining can be confused with links in HTML documents. +This behaviour can be changed by adding a style mapping for `u`. +For instance, suppose that a source document uses underlining for emphasis. +The following will wrap any explicitly underlined source text in `` tags: + +```csharp +var converter = new DocumentConverter() + .AddStyleMap("u => em"); +``` + +#### Strikethrough + +By default, strikethrough text is wrapped in `` tags. +This behaviour can be changed by adding a style mapping for `strike`. +For instance, to wrap strikethrough text in `` tags: + +```csharp +var converter = new DocumentConverter() + .AddStyleMap("strike => del"); +``` +### API + +#### `DocumentConverter` + +Methods: + +* `IResult ConvertToHtml(string path)`: converts the file at `path` into an HTML string. + +* `IResult ConvertToHtml(Stream stream)`: converts `stream` into an HTML string. + Note that using this method instead of `convertToHtml(File file)` means that relative paths + to other files, such as images, cannot be resolved. + +* `IResult ExtractRawText(string path)`: + Extract the raw text of the document. + This will ignore all formatting in the document. + Each paragraph is followed by two newlines. + +* `IResult ExtractRawText(Stream stream)`: + Extract the raw text of the document. + This will ignore all formatting in the document. + Each paragraph is followed by two newlines. + +* `DocumentConverter AddStyleMap(string styleMap)`: + add a style map to specify the mapping of Word styles to HTML. + The most recently added style map has the greatest precedence. + See the section "Writing style maps" for a description of the syntax. + +* `DocumentConverter DisableDefaultStyleMap()`: by default, + any added style maps are combined with the default style map. + Call this to stop using the default style map altogether. + +* `DocumentConverter PreserveEmptyParagraphs()`: by default, empty paragraphs are ignored. + Call this to preserve empty paragraphs in the output. + +* `DocumentConverter IdPrefix(string idPrefix)`: + a string to prepend to any generated IDs, + such as those used by bookmarks, footnotes and endnotes. + Defaults to the empty string. + +#### `IResult` + +Represents the result of a conversion. Properties: + +* `T Value`: the generated text. + +* `ISet Warnings`: any warnings generated during the conversion. + +## Writing style maps + +A style map is made up of a number of style mappings separated by new lines. +Blank lines and lines starting with `#` are ignored. + +A style mapping has two parts: + +* On the left, before the arrow, is the document element matcher. +* On the right, after the arrow, is the HTML path. + +When converting each paragraph, +Mammoth finds the first style mapping where the document element matcher matches the current paragraph. +Mammoth then ensures the HTML path is satisfied. + +### Freshness + +When writing style mappings, it's helpful to understand Mammoth's notion of freshness. +When generating, Mammoth will only close an HTML element when necessary. +Otherwise, elements are reused. + +For instance, suppose one of the specified style mappings is `p[style-name='Heading 1'] => h1`. +If Mammoth encounters a .docx paragraph with the style name `Heading 1`, +the .docx paragraph is converted to a `h1` element with the same text. +If the next .docx paragraph also has the style name `Heading 1`, +then the text of that paragraph will be appended to the *existing* `h1` element, +rather than creating a new `h1` element. + +In most cases, you'll probably want to generate a new `h1` element instead. +You can specify this by using the `:fresh` modifier: + +`p[style-name='Heading 1'] => h1:fresh` + +The two consective `Heading 1` .docx paragraphs will then be converted to two separate `h1` elements. + +Reusing elements is useful in generating more complicated HTML structures. +For instance, suppose your .docx contains asides. +Each aside might have a heading and some body text, +which should be contained within a single `div.aside` element. +In this case, style mappings similar to `p[style-name='Aside Heading'] => div.aside > h2:fresh` and +`p[style-name='Aside Text'] => div.aside > p:fresh` might be helpful. + +### Document element matchers + +#### Paragraphs and runs + +Match any paragraph: + +``` +p +``` + +Match any run: + +``` +r +``` + +To match a paragraph or run with a specific style, +you can reference the style by name. +This is the style name that is displayed in Microsoft Word or LibreOffice. +For instance, to match a paragraph with the style name `Heading 1`: + +``` +p[style-name='Heading 1'] +``` + +Styles can also be referenced by style ID. +This is the ID used internally in the .docx file. +To match a paragraph or run with a specific style ID, +append a dot followed by the style ID. +For instance, to match a paragraph with the style ID `Heading1`: + +``` +p.Heading1 +``` + +#### Bold + +Match explicitly bold text: + +``` +b +``` + +Note that this matches text that has had bold explicitly applied to it. +It will not match any text that is bold because of its paragraph or run style. + +#### Italic + +Match explicitly italic text: + +``` +i +``` + +Note that this matches text that has had italic explicitly applied to it. +It will not match any text that is italic because of its paragraph or run style. + +#### Underline + +Match explicitly underlined text: + +``` +u +``` + +Note that this matches text that has had underline explicitly applied to it. +It will not match any text that is underlined because of its paragraph or run style. + +#### Strikethough + +Match explicitly struckthrough text: + +``` +strike +``` + +Note that this matches text that has had strikethrough explicitly applied to it. +It will not match any text that is struckthrough because of its paragraph or run style. + +### HTML paths + +#### Single elements + +The simplest HTML path is to specify a single element. +For instance, to specify an `h1` element: + +``` +h1 +``` + +To give an element a CSS class, +append a dot followed by the name of the class: + +``` +h1.section-title +``` + +To require that an element is fresh, use `:fresh`: + +``` +h1:fresh +``` + +Modifiers must be used in the correct order: + +``` +h1.section-title:fresh +``` + +#### Nested elements + +Use `>` to specify nested elements. +For instance, to specify `h2` within `div.aside`: + +``` +div.aside > h2 +``` + +You can nest elements to any depth. + +## Missing features + +Compared to the JavaScript and Python implementations, the following features +are currently missing: + +* Custom image handlers +* CLI +* Embedded style map support +* Markdown support +* Document transforms + -- cgit v1.2.3