Update pluck docs to clarify label use. Update example grammar to mat…

…ch docs. Fixes peggyjs#405.

docs/documentation.html

@@ -1052,9 +1052,11 @@ <h3 id="grammar-syntax-and-semantics-parsing-expression-types">Parsing Expressio
 
   <dd>
     <p>Match the expression and if the label exists, remember its match result
-    under given label. The label must be a Peggy
-    <a href="#identifiers">identifier</a>, and must be valid as a function parameter
-      in the language that is being generated (by default, JavaScript).</p>
+      under given label. The label must be a Peggy
+      <a href="#identifiers">identifier</a>, and must be valid as a function
+      parameter in the language that is being generated (by default,
+      JavaScript).  Labels are only useful for later reference in a semantic
+      predicate at this time.</p>
 
     <p>Return the value of this expression from the rule, or "pluck" it. You
       may not have an action for this rule. The expression must not be a
@@ -1070,7 +1072,7 @@ <h3 id="grammar-syntax-and-semantics-parsing-expression-types">Parsing Expressio
     <div class="example">
       <div>
         <div><em>Example:</em> <code>pluck_1 = @$"a"+ " "+ @$"b"+</code></div>
-        <div><em>Matches:</em> <code>"aaa "</code>, <code>"a  "</code></div>
+        <div><em>Matches:</em> <code>"aaa bb"</code>, <code>"a  "</code></div>
         <div><em>Does not match:</em> <code>"b"</code>, <code>" "</code></div>
       </div>
       <div class="try">
@@ -1082,13 +1084,13 @@ <h3 id="grammar-syntax-and-semantics-parsing-expression-types">Parsing Expressio
 
     <div class="example">
       <div>
-        <div><em>Example:</em> <code>pluck_2 = @$"a"+ " "+ @two:$"b"+</code></div>
-        <div><em>Matches:</em> <code>"aaa b"</code>, <code>"a  bbb"</code></div>
-        <div><em>Does not match:</em> <code>"b"</code>, <code>" "</code></div>
+        <div><em>Example:</em> <code>pluck_2 = @$"a"+ " "+ @two:$"b"+ &{ return two.length < 3 } </code></div>
+        <div><em>Matches:</em> <code>"aaa b"</code>, <code>"a  bb"</code></div>
+        <div><em>Does not match:</em> <code>"a bbbb"</code>, <code>"b"</code>, <code>" "</code></div>
       </div>
       <div class="try">
         <em>Try it:</em>
-        <input type="text" value="aaa   bbb" class="exampleInput" name="pluck_2">
+        <input type="text" value="aaa   bb" class="exampleInput" name="pluck_2">
         <div class="result"></div>
       </div>
     </div>
@@ -1423,7 +1425,7 @@ <h2 id="locations">Locations</h2>
 
 <p><code>source</code> is the a string or object that was supplied in the
   <a href="#grammar-source"><code>grammarSource</code></a> parser option.</p>
-  
+
 <p>For certain special cases, you can use an instance of the
   <code>GrammarLocation</code> class as the <code>grammarSource</code>.
   <code>GrammarLocation</code> allows you to specify the offset of the grammar

docs/js/examples.peggy

@@ -32,9 +32,9 @@ dollar = match:$"a"+ rest:rest { return {match, rest}; }
 
 label = match:(foo:"bar"i { return {foo}; }) rest:rest { return {match, rest}; }
 
-pluck_1 = match:(@$"a"+ " "+) rest:rest { return {match, rest}; }
+pluck_1 = match:(@$"a"+ " "+ @$"b"+) rest:rest { return {match, rest}; }
 
-pluck_2 = match:(@$"a"+ " "+ @two:$"b"+) rest:rest { return {match, rest}; }
+pluck_2 = match:(@$"a"+ " "+ @two:$"b"+ &{ return two.length < 3 }) rest:rest { return {match, rest}; }
 
 sequence = match:("a" "b" "c") rest:rest { return {match, rest}; }