Added importstr to the tutorial.

Author: Alex Helfet

doc/docs/tutorial.html

@@ -167,24 +167,56 @@ <h2 id="modularity">Modularity and Encapsulation</h2>
 
 <p>As the amount of JSON grows, its size makes it harder to manage.  Jsonnet has various constructs
 to help.  A file can be broken into parts, as one Jsonnet file can import other Jsonnet files (and
-therefore other JSON files).  Values can be held in local variables and fields, which are only
-visible within their scopes.  Functions can be defined to factor out common descriptions, and error
-statements can be used to validate inputs.  Jsonnet provides a standard library that is implicitly
-imported and contains useful functions for data manipulation, among other things.</p>
+therefore other JSON files), or a whole text file can be imported as a string value.  Values can be
+held in local variables and fields, which are only visible within their scopes.  Functions can be
+defined to factor out common descriptions, and error statements can be used to validate inputs.
+Jsonnet provides a standard library that is implicitly imported and contains useful functions for
+data manipulation, among other things.</p>
 
 <h3 id="imports">Imports</h3>
 
 <p>The first example below factors out some cocktails into a separate file.  This may be useful to
-allow concurrent modifications by different mixologists.  The <code>import</code> construct yields
-the content of the <tt>martinis.libsonnet</tt> file.  The <code>+</code> operator is object
-concatenation, which combines two objects to form a single object.  Note that the Cosmopolitan field
-is defined in both files, so the one on the right hand side is used.  This means that
-<tt>bar_menu.jsonnet</tt> has overridden the recipe from <tt>martinis.libsonnet</tt> with a different
-recipe (one that uses Cointreau instead of Triple Sec, among other changes).</p>
+allow concurrent modifications by different mixologists.</p>
 
+<p>The <code>import</code> construct yields the content of the <tt>martinis.libsonnet</tt> file
+evaluated as a Jsonnet object. The <code>+</code> operator is object concatenation, which combines
+two objects to form a single object.  Note that the Cosmopolitan field is defined in both files, so
+the one on the right hand side is used.  This means that <tt>bar_menu.jsonnet</tt> has overridden
+the recipe from <tt>martinis.libsonnet</tt> with a different recipe (one that uses Cointreau instead
+of Triple Sec, among other changes).</p>
+
+<p>The <code>importstr</code> construct yields a string with the content of
+the <tt>bar_menu.6.manhattan_garnish.txt</tt> file without any processing beyond UTF-8 decoding.</p>
+
+<table>
+<tr> <td><span class="TableHeader">Input (Jsonnet)</span></td> </tr>
+
+<tr>
+<td>
 <pre><code>{% include examples/martinis.libsonnet %}</code></pre>
+</td>
+</tr>
 
+<tr>
+<td>
+<pre><code>// bar_menu.6.manhattan_garnish.txt
+{% include examples/bar_menu.6.manhattan_garnish.txt %}</code></pre>
+</td>
+</tr>
+
+<tr>
+<td>
 <pre><code>{% include examples/bar_menu.6.jsonnet %}</code></pre>
+</td>
+</tr>
+
+<tr><td><span class="TableHeader">Output (JSON)</span></td></tr>
+<tr>
+<td>
+<pre><code>{% include examples/bar_menu.6.jsonnet.golden %}</code></pre>
+</td>
+</tr>
+</table>
 
 <p>By convention, Jsonnet code that is intended only for importing has a <tt>.libsonnet</tt>
 extension.  This is not enforced, it simply allows you to distinguish between the two kinds of files

examples/BUILD

@@ -14,6 +14,8 @@ jsonnet_docs_srcs_zip(
         "bar_menu.5.jsonnet",
         "bar_menu.5.jsonnet.golden",
         "bar_menu.6.jsonnet",
+        "bar_menu.6.manhattan_garnish.txt",
+        "bar_menu.6.jsonnet.golden",
         "bar_menu_utils.libsonnet",
         "bar_menu.7.jsonnet",
         "bar_menu.7.jsonnet.golden",

examples/bar_menu.6.jsonnet

@@ -23,7 +23,7 @@ limitations under the License.
                 { kind: "Sweet Red Vermouth", qty: 1 },
                 { kind: "Angostura", qty: "dash" },
             ],
-            garnish: "Maraschino Cherry",
+            garnish: importstr "bar_menu.6.manhattan_garnish.txt",
             served: "Straight Up",
         },
         Cosmopolitan: {

examples/bar_menu.6.manhattan_garnish.txt

@@ -0,0 +1 @@
+Maraschino Cherry