README.template.md in markdown_helper-0.2.3

- old
+ new

@@ -10,10 +10,23 @@
 
 Next feature:
 
 * "Slide deck": to chain markdown pages into a series with next/prev navigation links.
 
+## How It Works
+
+The markdown helper reads a markdown document (template) and writes another markdown document.
+
+The template can contain certain instructions that call for file inclusions and image resolutions.
+
+By default, the output markdown has added comments that show:
+
+* The path to the template file.
+* The path to each included file.
+* The image description (original) for each resolved image file path.
+
+You can suppress those comments using the <code>pristine</code> option.
 ## File Inclusion 
 
 ![include_icon](images/include.png | width=50)
 
 This markdown helper enables file inclusion in GitHub markdown.
@@ -32,10 +45,14 @@
 
 @[:code_block](include.rb)
 
 [Note:  In the gem documentation, RubyDoc.info chooses to highlight this code block regardless.  Go figure.]
 
+#### Comment
+
+Comment text is written into the output between the comment delimiters <code>\<!--</code> and <code>--></code>
+
 #### Verbatim
 
 Verbatim text is included unadorned.  Most often, verbatim text is markdown to be rendered as part of the markdown page.
 
 ### Usage
@@ -48,11 +65,11 @@
 
 @[ruby](include_usage.rb)
 
 #### Include Descriptions
 
-Specify each file inclusion via an *include description*, which has the form:
+Specify each file inclusion at the beginning of a line via an *include description*, which has the form:
 
 <code>@[</code>*format*<code>]\(</code>*relative_file_path*<code>)</code>
 
 where:
 
@@ -80,19 +97,19 @@
 
 ### Usage
 
 #### CLI
 
-@[:code_block](../bin/usage/resolve_image_urls.txt)
+@[:code_block](../bin/usage/resolve.txt)
 
 #### API
 
-@[ruby](resolve_image_urls_usage.rb)
+@[ruby](resolve_usage.rb)
 
 #### Image Descriptions
 
-Specify each image via an *image description*, which has the form:
+Specify each image  at the beginning of a line via an *image description*, which has the form:
 
 <code>![*alt_text*]\(</code>*relative_file_path* <code>|</code> *attributes*<code>)</code>
 
 where:
 
@@ -100,11 +117,11 @@
 * *relative_file_path* points to the file to be included.
 * *attributes* specify image attributes.  See [Image Attributes](#image-attributes) below.
 
 ##### Example Image Descriptions
 
-@[code_block](resolve_image_urls.md)
+@[code_block](resolve.md)
 
 ## Image Attributes
 
 ![html_icon](images/html.png | width=50)
 
@@ -116,19 +133,19 @@
 
 ### Usage
 
 #### CLI
 
-@[:code_block](../bin/usage/resolve_image_urls.txt)
+@[:code_block](../bin/usage/resolve.txt)
 
 #### API
 
-@[ruby](resolve_image_urls_usage.rb)
+@[ruby](resolve_usage.rb)
 
 #### Image Descriptions
 
-Specify each image via an *image description*, which has the form:
+Specify each image at the beginning of a line  via an *image description*, which has the form:
 
 <code>![*alt_text*]\(</code>*relative_file_path* <code>|</code> *attributes*<code>)</code>
 
 where:
 
@@ -136,7 +153,7 @@
 * *relative_file_path* points to the file to be included.
 * *attributes* are whitespace-separated name-value pairs in the form *name*<code>=</code>*value*.  These are passed through to the generated <code>img</code> HTML element.
 
 ##### Example Image Descriptions
 
-@[code_block](resolve_image_urls.md)
+@[code_block](resolve.md)
 