[Docs] Reworked intro and cleanup.

docs/core/faq-and-tips.md

@@ -5,7 +5,9 @@
 
 This is a collection of tips, from how to avoid pitfalls to best practices.
 
-Suggestions for new entries may be submitted by [creating a new issue](https://github.com/tmedwards/tweego/issues) at Tweego's [source code repository](https://github.com/tmedwards/tweego).  **NOTE:** Acceptance of submissions ***is not*** guaranteed.
+<p role="note"><b>Note:</b>
+Suggestions for new entries may be submitted by <a href="https://github.com/tmedwards/tweego/issues">creating a new issue</a> at Tweego's <a href="https://github.com/tmedwards/tweego">source code repository</a>—though acceptance of submissions <strong><em>is not</em></strong> guaranteed.
+</p>
 
 
 <!-- ***************************************************************************

docs/core/usage.md

@@ -20,7 +20,7 @@ Basic command line usage is as follows:
 tweego [options] sources…
 ```
 
-Where <code>[options]</code> are mostly optional configuration flags—see [Options](#usage-options)—and <code>sources</code> are the input sources which may consist of supported files and/or directories to recursively search for such files.  Many types of files are supported as input sources—see [File &amp; Directory Handling](#usage-file-and-directory-handling) for more information.
+Where <code>[options]</code> are mostly optional configuration flags—see [Options](#usage-options)—and <code>sources</code> are the input sources which may consist of supported files and/or directories to recursively search for such files.  Many types of files are supported as input sources—see [Supported Files](#usage-supported-files) for more information.
 
 
 <!-- ***************************************************************************
@@ -73,54 +73,14 @@ Where <code>[options]</code> are mostly optional configuration flags—see [Opti
 
 
 <!-- ***************************************************************************
-	Basic Examples
+	Supported Files
 **************************************************************************** -->
-<span id="usage-basic-examples"></span>
+<span id="usage-supported-files"></span>
-## Basic Examples
+## Supported Files
 
-Compile <kbd>example_1.twee</kbd> as <kbd>example_1.html</kbd> with the default story format:
+Tweego supports various types of files for use in projects.  File types are recognized by filename extension, so all files ***must*** have an extension.
 
-```
+The following extensions are supported:
-tweego -o example_1.html example_1.twee
-```
-
-Compile all files in <kbd>example_directory_2</kbd> as <kbd>example_2.html</kbd> with the default story format:
-
-```
-tweego -o example_2.html example_directory_2
-```
-
-Compile <kbd>example_3.twee</kbd> as <kbd>example_3.html</kbd> with the story format <kbd>snowman</kbd>:
-
-```
-tweego -f snowman -o example_3.html example_3.twee
-```
-
-Compile all files in <kbd>example_directory_4</kbd> as <kbd>example_4.html</kbd> with the default story format while also bundling all files in <kbd>modules_directory_4</kbd> into the &lt;head&gt; element of the compiled HTML:
-
-```
-tweego -o example_4.html -m modules_directory_4 example_directory_4
-```
-
-Decompile <kbd>example_5.html</kbd> as <kbd>example_5.twee</kbd>:
-
-```
-tweego -d -o example5.twee example5.html
-```
-
-
-<!-- ***************************************************************************
-	File & Directory Handling
-**************************************************************************** -->
-<span id="usage-file-and-directory-handling"></span>
-## File &amp; Directory Handling
-
-Tweego allows you to specify an arbitrary number of files and directories on the command line for processing.  In addition to those manually specified, it will recursively search all directories encountered looking for additional files and directories to process.  Generally, this means that you only have to specify the base source directory of your project and Tweego will find all of its files automatically.
-
-<span id="usage-file-and-directory-handling-supported-extensions"></span>
-### Supported File Extensions
-
-Tweego only processes files with the following extensions:
 
 <dl>
 <dt><code>.tw</code>, <code>.twee</code></dt>
@@ -167,3 +127,49 @@ Tweego only processes files with the following extensions:
 	</p>
 </dd>
 </dl>
+
+
+<!-- ***************************************************************************
+	File & Directory Handling
+**************************************************************************** -->
+<span id="usage-file-and-directory-handling"></span>
+## File &amp; Directory Handling
+
+Tweego allows you to specify an arbitrary number of files and directories on the command line for processing.  In addition to those manually specified, it will recursively search all directories encountered looking for additional files and directories to process.  Generally, this means that you only have to specify the base source directory of your project and Tweego will find all of its files automatically.
+
+
+<!-- ***************************************************************************
+	Basic Examples
+**************************************************************************** -->
+<span id="usage-basic-examples"></span>
+## Basic Examples
+
+Compile <kbd>example_1.twee</kbd> as <kbd>example_1.html</kbd> with the default story format:
+
+```
+tweego -o example_1.html example_1.twee
+```
+
+Compile all files in <kbd>example_directory_2</kbd> as <kbd>example_2.html</kbd> with the default story format:
+
+```
+tweego -o example_2.html example_directory_2
+```
+
+Compile <kbd>example_3.twee</kbd> as <kbd>example_3.html</kbd> with the story format <kbd>snowman</kbd>:
+
+```
+tweego -f snowman -o example_3.html example_3.twee
+```
+
+Compile all files in <kbd>example_directory_4</kbd> as <kbd>example_4.html</kbd> with the default story format while also bundling all files in <kbd>modules_directory_4</kbd> into the &lt;head&gt; element of the compiled HTML:
+
+```
+tweego -o example_4.html -m modules_directory_4 example_directory_4
+```
+
+Decompile <kbd>example_5.html</kbd> as <kbd>example_5.twee</kbd>:
+
+```
+tweego -d -o example5.twee example5.html
+```

docs/introduction.md

@@ -3,9 +3,9 @@
 ************************************************************************************************ -->
 <h1 id="introduction">Introduction</h1>
 
-This documentation is a reference for [Tweego](http://www.motoslave.net/tweego/), a free (gratis and libre) command line compiler for [Twine/Twee](http://twinery.org/) story formats, written in [Go](http://golang.org/).
+This documentation is a reference for [Tweego](http://www.motoslave.net/tweego/), a free (gratis and libre) [command line interface](https://en.wikipedia.org/wiki/Command-line_interface) compiler for [Twine](http://twinery.org/) projects, written in [Go](http://golang.org/).
 
-Tweego is a [command line program](https://en.wikipedia.org/wiki/Command-line_interface) that compiles a Twine game from loose, usually text, files.  Passages are defined within Twee files—see: [Twee Notation](#twee-notation) and [Twine Cookbook: *What is Twee?*](http://twinery.org/cookbook/terms/terms_twee.html)—though Tweego [supports many types of files](#usage-file-and-directory-handling-supported-extensions).  This allows you to write your game using your favorite text editor, rather than the Twine IDE, and compile it into an `.html` file with Tweego.
+Why use Tweego?  Tweego lets you write Twine projects using your favorite text editor, rather than the [Twine software](http://twinery.org/).  You write passages in plain text files using the [Twee notation](#twee-notation) across as few or as many files as you choose, which can make working, and collaborating, on Twine projects faster and easier.  When you're ready to publish or test, you simply compile all your project files into an `.html` file with Tweego.
 
 <p role="note"><b>Note:</b>
 If you believe that you've found a bug in Tweego, or simply wish to make a suggestion, you may do so by <a href="https://github.com/tmedwards/tweego/issues">creating a new issue</a> at its <a href="https://github.com/tmedwards/tweego">source code repository</a>.

docs/table-of-contents.md

@@ -20,8 +20,9 @@
 
 * [Overview](#usage-overview)
 * [Options](#usage-options)
-* [Basic Examples](#usage-basic-examples)
+* [Supported Files](#usage-supported-files)
 * [File & Directory Handling](#usage-file-and-directory-handling)
+* [Basic Examples](#usage-basic-examples)
 
 ## [Twee Notation](#twee-notation)