From 1bf77e4592ea63f1a7a2e156611232be9d66b90c Mon Sep 17 00:00:00 2001
From: Michael Williamson <mike@zwobble.org>
Date: Tue, 7 Jan 2014 23:05:44 +0000
Subject: Clarify style vs style map

---
 README.md | 26 ++++++++++++++++----------
 1 file changed, 16 insertions(+), 10 deletions(-)

diff --git a/README.md b/README.md
index 4f4f418..a3cc7f5 100644
--- a/README.md
+++ b/README.md
@@ -49,7 +49,9 @@ Where `custom-style-map` looks something like:
     p.AsideHeading => div.aside > h2:fresh
     p.AsideText => div.aside > p:fresh
 
-### API
+### Library
+
+#### Basic conversion
 
 To convert an existing .docx file to HTML,
 pass a file-like object to `mammoth.convert_to_html`.
@@ -65,12 +67,14 @@ with open("document.docx", "rb") as docx_file:
     messages = result.messages # Any messages, such as warnings during conversion
 ```
 
+### Custom style map
+
 By default,
 Mammoth maps some common .docx styles to HTML elements.
 For instance,
 a paragraph with the style `Heading1` is converted to a `h1` element.
-You can pass in custom styles using the `style_map` argument.
-A description of the syntax for styles can be found in the section "Writing styles".
+You can pass in a custom style map using the `style_map` argument.
+A description of the syntax for style maps can be found in the section "Writing style maps".
 For instance, if paragraphs with the style `SectionTitle` should be converted to `h1` elements,
 and paragraphs with the style `SubSectionTitle` should be converted to `h2` elements:
 
@@ -88,25 +92,27 @@ with open("document.docx", "rb") as docx_file:
 
 User-defined style mappings are used in preference to the default style mappings.
 
-## Writing styles
+## Writing style maps
+
+A style map is made up of a number of style mappings.
 
-A style has two parts:
+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 where the document element matcher matches the current 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 styles, it's helpful to understand Mammoth's notion of 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 styles is `p.Heading1 => h1`.
-If Mammoth encounters a .docx paragraphs with the style `Heading1`,
+For instance, suppose one of the specified style mappings is `p.Heading1 => h1`.
+If Mammoth encounters a .docx paragraph with the style `Heading1`,
 the .docx paragraph is converted to a `h1` element with the same text.
 If the next .docx paragraph also has the style `Heading1`,
 then the text of that paragraph will be appended to the *existing* `h1` element,
@@ -123,7 +129,7 @@ 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, styles similar to `p.AsideHeading => div.aside > h2:fresh` and
+In this case, style mappings similar to `p.AsideHeading => div.aside > h2:fresh` and
 `p.AsideText => div.aside > p:fresh` might be helpful.
 
 ### Document element matchers
-- 
cgit v1.2.3