Add doc example of unexpected combining sequence parsers.

Example is based on #215.

Author: tzlaine

doc/parser.qbk

@@ -110,6 +110,7 @@
 
 
 [def _std_str_             `std::string`]
+[def _std_strs_            `std::string`s]
 [def _std_vec_char_        `std::vector<char>`]
 [def _std_vec_char32_      `std::vector<char32_t>`]
 
@@ -242,6 +243,7 @@
 [def _more_about_rules_    [link boost_parser.tutorial.more_about_rules More About Rules]]
 [def _unicode_             [link boost_parser.tutorial.unicode_support Unicode Support]]
 [def _concepts_            [link boost_parser.concepts Concepts]]
+[def _seq_parser_example_  [link boost_parser.tutorial.attribute_generation.a_sequence_parser_attribute_example A sequence parser attribute example]]
 [def _ex_json_             [link boost_parser.extended_examples.parsing_json Parsing JSON]]
 [def _ex_cb_json_          [link boost_parser.extended_examples.parsing_json_with_callbacks Parsing JSON With Callbacks]]
 [def _rationale_           [link boost_parser.rationale Rationale]]

doc/tutorial.qbk

@@ -1616,6 +1616,71 @@ attribute becomes `T`.
     [container_concept]
 ]
 
+[heading A sequence parser attribute example]
+
+Note that the application of `OP` is done in the style of a left-fold, and
+is therefore greedy.  This can lead to some non-obvious results.  For example,
+consider this program.  Thanks to Duncan Paterson for this very nice example!
+
+    #include <boost/parser/parser.hpp>
+    #include <print>
+
+    namespace bp = boost::parser;
+    int main() {
+      const auto id_set_action = [](auto &ctx) {
+        const auto& [left, right] = _attr(ctx);
+        std::println("{} = {}", left, right);
+      };
+
+      const auto id_parser = bp::char_('a', 'z') > *bp::char_('a', 'z');
+
+      const auto id_set = (id_parser >> '=' >> id_parser)[id_set_action];
+      bp::parse("left=right", id_set);
+      return 0;
+    }
+
+Perhaps surprisingly, this program prints `leftr = ight`!  Why is this?  This
+happens because `id_parser` seems to impose structure, but does not.  `id_set`
+is exactly equivalent to this (comments added to clarify which parts are which
+below).
+
+    const auto id_set = (
+      /*A*/ bp::char_('a', 'z') > /*B*/ *bp::char_('a', 'z') >>
+      /*C*/ '=' >>
+      /*D*/ bp::char_('a', 'z') > /*E*/ *bp::char_('a', 'z')
+    )[id_set_action];
+
+As _Parser_ applies `OP` to this sequence parser, the individual steps are:
+`A` and `B` get merged into a single _std_str_; `C` is ignored, since it
+produces no attribute; and `D` gets merged into the _std_str_ formed earlier
+by `A` and `B`; finally, we have `E`. `E` does not combine with `D`, as `D`
+was already consumed.  `E` also does not combine with the _std_str_ we formed
+from `A`, `B`, and `D`, since we don't combine adjacent containers.  In the
+end, we have a 2-tuple of _std_strs_, in which the first element contains all
+the characters parsed by `A`, `B`, and `D`, and in which the second element
+contains all the characters parsed by `E`.
+
+That's clearly not what we wanted here, though.  How do we get a top-level
+parser that would print `left = right`?  We use a _r_.  The parser used inside
+a _r_ can never combine with any parser(s) outside the _r_.  Instances of a
+rule are inherently separate from all parsers with which they are used,
+whether those parsers are _rs_ or non-_r_ parsers.  So, consider a _r_
+equivalent to the previous `id_parser` above.
+
+    namespace bp = boost::parser;
+    bp::rule<struct id_parser_tag, std::string> id_parser = "identifier";
+    auto const id_parser_def = bp::char_('a', 'z') > *bp::char_('a', 'z');
+    BOOST_PARSER_DEFINE_RULES(id_parser);
+
+Later, we can use it just as we used the previous non-rule version.
+
+    const auto id_set = (id_parser >> '=' >> id_parser)[id_set_action];
+
+This produces the results you might expect, since only the `bp::char_('a',
+'z') > *bp::char_('a', 'z')` parser inside the `id_parser` _r_ is ever
+eligible for combining via `OP`.
+
+
 [heading Alternative parser attribute rules]
 
 The rules for alternative parsers are much simpler.  For an alternative parer
@@ -2237,6 +2302,8 @@ common use cases for _rs_.  Use a _r_ if you want to:
 * fix the attribute type produced by a parser to something other than the
   default;
 
+* control the attributes generated by adjacent sequence parsers;
+
 * create a parser that produces useful diagnostic text;
 
 * create a recursive rule (more on this below);
@@ -2377,6 +2444,10 @@ action if:
 
 The notion of "compatible" is defined in _p_api_.
 
+[heading Controlling the attributes generated]
+
+See the _seq_parser_example_ in the _attr_gen_ section for details.
+
 [heading Creating a parser for better diagnostics]
 
 Each _r_ has associated diagnostic text that _Parser_ can use for failures of