From d6bc96d7dea06a602316673d72b328ddfdcea1b4 Mon Sep 17 00:00:00 2001
From: Kevin Brown <kevin@kevin-brown.com>
Date: Thu, 14 Jan 2016 18:40:37 -0500
Subject: [PATCH] Expand upon the core section of the docs

This adds more code examples where they might be useful, and adds some
more description where it was needed. This clarifies a couple of the
questions that have come up about the AMD support and links to the bug
that Select2 was involved with that some people reported when 4.0.0 was
released.
---
 docs/_includes/options/core/amd-support.html  | 14 ++++++++---
 .../options/core/data-attributes.html         |  6 ++++-
 docs/_includes/options/core/options.html      | 24 ++++++++++++++++++-
 3 files changed, 39 insertions(+), 5 deletions(-)

diff --git a/docs/_includes/options/core/amd-support.html b/docs/_includes/options/core/amd-support.html
index 9dfd2759..faa23246 100644
--- a/docs/_includes/options/core/amd-support.html
+++ b/docs/_includes/options/core/amd-support.html
@@ -4,7 +4,7 @@
   </h2>
 
   <p>
-    Yes, Select2 should work with most AMD or CommonJS loaders without any issues.
+    Select2 should work with most AMD- or CommonJS-compliant module loaders, including <a href="http://requirejs.org/">RequireJS</a> and <a href="https://github.com/jrburke/almond">almond</a>. Select2 ships with a modified version of the <a href="https://github.com/umdjs/umd/blob/f208d385768ed30cd0025d5415997075345cd1c0/templates/jqueryPlugin.js">UMD jQuery template</a> that supports both CommonJS and AMD environments.
   </p>
 
   <h3>
@@ -29,10 +29,18 @@ $.fn.select2.defaults.set('amdLanguageBase', 'select2/i18n/');
   </h3>
 
   <p>
-    Due to a bug in older versions of the r.js build tool, Select2 was sometimes placed before jQuery in then compiled build file. Because of this, Select2 will trigger an error because it won't be able to find or load jQuery.
+    Due to <a href="https://github.com/jrburke/requirejs/issues/1342">a bug in older versions</a> of the r.js build tool, Select2 was sometimes placed before jQuery in then compiled build file. Because of this, Select2 will trigger an error because it won't be able to find or load jQuery.
   </p>
 
   <p>
-    You can fix this issue by upgrading to a newer version of the r.js build tool.
+    By upgrading to version 2.1.18 or higher of the r.js build tool, you will be able to fix the issue.
+  </p>
+
+  <h3>
+    Should I point to the files in <code>dist</code> or <code>src</code>?
+  </h3>
+
+  <p>
+    Select2 internally uses AMD and the r.js build tool to build the files located in the <code>dist</code> folder. These are built using the files in the <code>src</code> folder, so <em>you can</em> just point your modules to the Select2 source and load in <code>jquery.select2</code> or <code>select2/core</code> when you want to use Select2. The files located in the <code>dist</code> folder are also AMD-compatible, so you can point to that file if you want to load in all of the default Select2 modules.
   </p>
 </section>
\ No newline at end of file
diff --git a/docs/_includes/options/core/data-attributes.html b/docs/_includes/options/core/data-attributes.html
index 9a95e105..357bfaa9 100644
--- a/docs/_includes/options/core/data-attributes.html
+++ b/docs/_includes/options/core/data-attributes.html
@@ -14,6 +14,10 @@
     How should <code>camelCase</code> options be written?
   </h3>
 
+  <p>
+    HTML data attributes are case-insensitive, so any options which contain capital letters will be parsed as if they were all lowercase. Because Select2 has many options which are camelCase, where words are separated by uppercase letters, you must write these options out with dashes instead. So an option that would normally be called <code>allowClear</code> should instead be defined as <code>allow-clear</code>.
+  </p>
+
   <p>
     This means that if you declare your <code>&lt;select&gt;</code> tag as...
   </p>
@@ -59,7 +63,7 @@ $("select").select2({
 $("select").select2({
   ajax: {
     url: "http://example.org/api/test",
-    cache: "true"
+    cache: true
   }
 });
 </pre>
diff --git a/docs/_includes/options/core/options.html b/docs/_includes/options/core/options.html
index 2b7cb1f4..8f712626 100644
--- a/docs/_includes/options/core/options.html
+++ b/docs/_includes/options/core/options.html
@@ -3,6 +3,24 @@
     How should Select2 be initialized?
   </h2>
 
+  <p>
+    Select2 will register itself as a jQuery function if you use any of the distribution builds, so you can call <code>.select2()</code> on any jQuery element where you would like to initialize Select2.
+  </p>
+
+<pre class="prettyprint">
+$('select').select2();
+</pre>
+
+  <p>
+    You can optionally pass an object containing all of the options that you would like to initialize Select2 with.
+  </p>
+
+<pre class="prettyprint">
+$('select').select2({
+  placeholder: 'Select an option'
+});
+</pre>
+
   <h3 id="setting-default-options">
     Can default options be set for all dropdowns?
   </h3>
@@ -44,12 +62,16 @@ $.fn.select2.defaults.set("theme", "classic");
     string.
   </p>
 
+<pre class="prettyprint">
+$.fn.select2.defaults.set("ajax--cache", false);
+</pre>
+
   <h3>
     How can I reset all of the global default options?
   </h3>
 
   <p>
-    You can reset the default options by calling
+    You can reset the default options to their initial values by calling
   </p>
 
 <pre class="prettyprint">