Export from java-mammoth 5f538798b147f0e76

1 files changed, 381 insertions, 13 deletions

diff --git a/README.md b/README.md
index c9b4a05..82aebb5 100644
--- a/README.md
+++ b/README.md
@@ -1,26 +1,394 @@
-# dotnet-mammoth: .docx to HTML converter
+# Mammoth .docx to HTML converter for .NET
 
-This project uses [Edge.js](http://tjanczuk.github.io/edge/) to allow [mammoth.js](https://github.com/mwilliamson/mammoth.js) to be used from .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.
 
-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.
 
-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
 
-Install the package `Mammoth` from NuGet.
+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
 
-Only the bare minimum case is currently supported:
+### 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
-var documentConverter = new Mammoth.DocumentConverter();
-var result = documentConverter.ConvertToHtml(@"path/to/document.docx");
-// result.Value contains the HTML output
-// result.Messages contains any messages produced during the conversion,
-// such as warnings about unrecognised paragraph styles.
+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");
 ```
 
-However, adding support for features that already exist in mammoth.js should be fairly straightforward,
-so feel free to file a bug or pull request for any such feature (or any other feature, for that matter).
+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 `<strong>` tags.
+This behaviour can be changed by adding a style mapping for `b`.
+For instance, to wrap bold text in `<em>` tags:
+
+```csharp
+var converter = new DocumentConverter()
+    .AddStyleMap("b => em");
+```
+
+#### Italic
+
+By default, italic text is wrapped in `<em>` tags.
+This behaviour can be changed by adding a style mapping for `i`.
+For instance, to wrap italic text in `<strong>` 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 `<em>` tags:
+
+```csharp
+var converter = new DocumentConverter()
+    .AddStyleMap("u => em");
+```
+
+#### Strikethrough
+
+By default, strikethrough text is wrapped in `<s>` tags.
+This behaviour can be changed by adding a style mapping for `strike`.
+For instance, to wrap strikethrough text in `<del>` tags:
+
+```csharp
+var converter = new DocumentConverter()
+    .AddStyleMap("strike => del");
+```
+### API
+
+#### `DocumentConverter`
+
+Methods:
+
+* `IResult<string> ConvertToHtml(string path)`: converts the file at `path` into an HTML string.
+
+* `IResult<string> 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<string> 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<string> 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<T>`
+
+Represents the result of a conversion. Properties:
+
+* `T Value`: the generated text.
+
+* `ISet<string> 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
+