Document underline support in style maps

2 files changed, 30 insertions, 2 deletions

diff --git a/NEWS b/NEWS
index 3c305e7..3d0d733 100644
--- a/NEWS
+++ b/NEWS
@@ -1,3 +1,7 @@
+# 0.3.22
+
+* Add support for underlines in style map.
+
 # 0.3.21
 
 * Add basic support for text boxes. The contents of the text box are treated as
diff --git a/README.md b/README.md
index bc6761f..a49656c 100644
--- a/README.md
+++ b/README.md
@@ -209,12 +209,25 @@ var options = {
 #### 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 setting the `convertUnderline` option to `mammoth.underline.element(name)`.
-
+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 underlined source text in `<em>` tags:
 
 ```javascript
+var mammoth = require("mammoth");
+
+var options = {
+    styleMap: [
+        "u => em"
+    ]
+};
+mammoth.convertToHtml({path: "path/to/document.docx"}, options);
+```
+
+The `convertUnderline` option is deprecated, and will be removed in Mammoth.js 1.0.
+The following behaves as the example above:
+
+```javascript
 var options = {
     convertUnderline: mammoth.underline.element("em")
 };
@@ -462,6 +475,17 @@ For instance, to match a paragraph with the style ID `Heading1`:
 p.Heading1
 ```
 
+#### 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.
+
 ### HTML paths
 
 #### Single elements