Better docs for the bind method

Author: spookylukey

docs/overview.rst

@@ -32,7 +32,8 @@ Parsy differentiates itself from other solutions with the following:
   English:
 
   * we can easily handle cases where later parsing depends on the value of
-    something parsed earlier e.g. Hollerith constants.
+    something parsed earlier e.g. `Hollerith constants
+    <https://en.wikipedia.org/wiki/Hollerith_constant>`_.
   * it's easy to build up complex result objects, rather than returning lists of
     lists etc. which then need to be further processed.
 

docs/ref/generating.rst

@@ -80,10 +80,11 @@ Using values already parsed
 ---------------------------
 
 The third example shows how we can use an earlier parsed value to influence the
-subsequent parsing. This example parses Hollerith constants. Hollerith constants
-are a way of specifying an arbitrary set of characters by first writing the
-integer that specifies the length, followed by the character H, followed by the
-set of characters. For example, ``pancakes`` would be written ``8Hpancakes``.
+subsequent parsing. This example parses `Hollerith constants
+<https://en.wikipedia.org/wiki/Hollerith_constant>`_. These are a
+way of specifying an arbitrary set of characters by first writing the integer
+that specifies the length, followed by the character H, followed by the set of
+characters. For example, ``pancakes`` would be written ``8Hpancakes``.
 
 .. code:: python
 
@@ -95,6 +96,9 @@ set of characters. For example, ``pancakes`` would be written ``8Hpancakes``.
        yield string('H')
        return any_char.times(num).concat()
 
+We could also write the same thing, more tersely, using the :meth:`Parser.bind`
+method.
+
 (You may want to compare this with an `implementation of Hollerith constants
 <https://gist.github.com/spookylukey/591aa8a6a9af7cf0f1e22129b29288d6>`_ that
 uses `pyparsing <http://pyparsing.wikispaces.com/>`_, originally by John

docs/ref/methods_and_combinators.rst

@@ -366,10 +366,34 @@ can be used and manipulated as below.
 
       Returns a parser which, if the initial parser is successful, passes the
       result to ``fn``, and continues with the parser returned from ``fn``. This
-      is the monadic binding operation. However, since we don't have Haskell's
-      ``do`` notation in Python, using this is very awkward. Instead, you should
-      look at :doc:`/ref/generating/` which provides a much nicer syntax for that
-      cases where you would have needed ``do`` notation in Parsec.
+      is the monadic binding operation.
+
+      Here is an example that implements `Hollerith constants
+      <https://en.wikipedia.org/wiki/Hollerith_constant>`_:
+
+      .. code-block:: python
+
+
+         from parsy import regex, string, any_char
+
+         hollerith = (regex(r'[0-9]+').map(int) << string('H')).bind(
+             lambda num: any_char.times(num).concat()
+         )
+
+      The first parser ``(regex(r'[0-9]+').map(int) << string('H'))`` will
+      consume something like ``"8H"`` and produce the integer ``8``. Via
+      ``bind``, we then pass that value as ``num`` into the lambda, which can
+      use it to consume more input.
+
+      However, since we don't have Haskell's ``do`` notation in Python, for
+      longer examples this is quite awkward. Instead, you should look at
+      :doc:`/ref/generating/` which provides a much nicer syntax for that cases
+      where you would have needed ``do`` notation in Parsec.
+
+      Also, the methods :meth:`~Parser.map`, :meth:`~Parser.combine` and
+      :meth:`~Parser.combine_dict`, which all use ``bind`` internally, are often
+      more convenient ways to chain output where you are doing transformations
+      but not further consuming of input.
 
    .. method:: sep_by(sep, min=0, max=inf)