clarify exactly what "tagging" is

Author: alexweissman

docs/_includes/examples/tags.html

@@ -2,50 +2,46 @@
   <h1 id="tags">Tagging support</h1>
 
   <p>
-    Select2 can be used to quickly set up fields used for tagging. 
-  </p>
-
-  <p>
-    Note that when tagging is enabled the user can select from pre-existing
-    options or create a new tag by picking the first choice, which is what
-    the user has typed into the search box so far.
+    In addition to the dropdown menu of options, Select2 can also allow free-text responses.  This feature is called "tagging".  To enable free-text responses, set the <code>tags</code> option to <code>true</code>:
   </p>
 
   <div class="s2-example">
     <p>
-      <select class="js-example-tags-multiple form-control" multiple="multiple">
+      <select class="js-example-tags form-control">
         <option selected="selected">orange</option>
         <option>white</option>
-        <option selected="selected">purple</option>
+        <option>purple</option>
       </select>
     </p>
   </div>
 
 {% highlight js linenos %}
-$(".js-example-tags-multiple").select2({
+$(".js-example-tags").select2({
   tags: true
 })
 {% endhighlight %}
-  
+
+  <p>
+    Note that when tagging is enabled the user can select from the pre-existing options or create a new option by picking the first choice, which is what the user has typed into the search box so far.
+  </p>
+
+  <h2>Tagging with multi-value select boxes</h2>
+
   <p>
-    Tagging can also be used on a single select element. Simply remove the
-    <code>multiple="multiple"</code> attribute from your HTML markup.
+    Tagging can also be used in multi-value select boxes. In the example below, we set the <code>multiple="multiple"</code> attribute on a Select2 control that also has <code>tags: true</code> enabled:
   </p>
 
   <div class="s2-example">
     <p>
-      <select class="js-example-tags form-control">
+      <select class="js-example-tags form-control" multiple="multiple">
         <option selected="selected">orange</option>
         <option>white</option>
-        <option>purple</option>
+        <option selected="selected">purple</option>
       </select>
     </p>
   </div>
 
-{% highlight js linenos %}
-$(".js-example-tags").select2({
-  tags: true
-})
-{% endhighlight %}
-  
+  <p>
+    Try entering a value that isn't listed in the dropdown - you'll be able to add it as a new option!
+  </p>
 </section>

docs/_includes/nav/examples.html

@@ -51,7 +51,7 @@
       </ul>
     </li>
     <li>
-      <a href="#tags">Tagging support</a>
+      <a href="#tags">Tagging (free-text) support</a>
     </li>
     <li>
       <a href="#tokenizer">Automatic tokenization</a>