3 files changed, 60 insertions, 18 deletions
diff --git a/docs/src/getting_started.rst b/docs/src/getting_started.rst
index c5a724f..4696015 100644
--- a/docs/src/getting_started.rst
+++ b/docs/src/getting_started.rst
@@ -1,5 +1,5 @@
-Getting started
-===============
+Getting started with colors
+===========================
 
 To highlight using colors:
 
@@ -24,25 +24,11 @@ If I want to be able to pass a color as an argument I can also use the
 
 .. literalinclude:: ../snippets/getting_started_2.py
 
+.. figure:: ../snippets/getting_started_2.png
+
 
 I can also apply color on a portion of a string:
 
 .. literalinclude:: ../snippets/getting_started_3.py
 
 .. figure:: ../snippets/getting_started_3.png
-
-
-Sometimes I may have a string that contains markup and I'll want to do something
-with it that concerns only the text, so I can strip the markup:
-
-.. code:: python
-
-    >>> from ansicolor import red
-    >>> from ansicolor import strip_escapes
-    >>> from ansicolor import yellow
-
-    >>> message = "My favorite colors are %s and %s" % (yellow("yellow"), red("red"))
-    >>> print("The length of this string is not: %d" % len(message))
-    The length of this string is not: 67
-    >>> print("The length of this string is: %d" % len(strip_escapes(message)))
-    The length of this string is: 37
diff --git a/docs/src/marked_up_strings.rst b/docs/src/marked_up_strings.rst
new file mode 100644
index 0000000..dc36521
--- /dev/null
+++ b/docs/src/marked_up_strings.rst
@@ -0,0 +1,33 @@
+Working with marked-up strings
+==============================
+
+
+Stripping markup
+----------------
+
+Sometimes I may have a string that contains markup and I'll want to do something
+with it that concerns only the text, so I can strip the markup:
+
+.. code:: python
+
+    >>> from ansicolor import red
+    >>> from ansicolor import strip_escapes
+    >>> from ansicolor import yellow
+
+    >>> message = "My favorite colors are %s and %s" % (yellow("yellow"), red("red"))
+    >>> print("The length of this text is not: %d" % len(message))
+    The length of this text is not: 67
+    >>> print("The length of this text is: %d" % len(strip_escapes(message)))
+    The length of this text is: 37
+
+
+Producing output
+----------------
+
+Printing marked-up strings directly is not appropriate for all use cases. When
+writing to a file it's generally not desirable to print ansi escapes meant
+for a terminal. The two functions :data:`ansicolor.write_out` and
+:data:`ansicolor.write_err` omit ansi escapes if the file being written to is
+not a tty.
+
+.. literalinclude:: ../snippets/marked_up_strings_1.py
diff --git a/docs/src/using_highlights.rst b/docs/src/using_highlights.rst
new file mode 100644
index 0000000..0fbd4bb
--- /dev/null
+++ b/docs/src/using_highlights.rst
@@ -0,0 +1,23 @@
+Using highlights
+================
+
+Quite often colors are used not to format all of the text in color, but to
+highlight certain parts of it.
+The function :data:`ansicolor.highlight_string` takes this a
+bit further by allowing you to pass in a list of pairs that represent
+the start and end offsets in the string that you want highlighted.
+
+.. literalinclude:: ../snippets/using_highlights_1.py
+
+.. figure:: ../snippets/using_highlights_1.png
+
+Every list of pairs that is passed in is considered a highlighting layer
+and gets a new color. Where layers overlap this is indicated by applying:
+
+- bold (two layers overlap),
+- reverse (three layers overlap),
+- bold and reverse (four layers overlap).
+
+Four layers is the maximum, because after that there is no further
+distinction possible. See :data:`ansicolor.demos.demo_highlight` for an
+exhaustive example.