markdown_helper 1.7.0 → 1.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 271b429b2a0016330e36fb2afd2c59c141ffb875
-  data.tar.gz: cc509ab4b86e4eeb18a60b5ec435bdf6f840fad1
+  metadata.gz: 6b99bdd941c258fc9c48888bcbcbc0c997519e21
+  data.tar.gz: 84ef4845336cd1b747144c9b9ba03610dd240bf8
 SHA512:
-  metadata.gz: bdfda83d3fecc8f4f80b0762b28878fa0ef3d4374df8bb10abeb1c7df638b42a97d180bda2388517091220a09bd55c5cd3c2a39da3f73e3d98ced011d4a9ca29
-  data.tar.gz: c9acebb1a64ca5f539da782cc451f70e96ef908567770a660e3e60c940714608fa5ae9723861f0fd16b327f444388602ec6f92c8e6ae35304e0042325c2b82d0
+  metadata.gz: cc670ccec98fecb5020389acba9152a8caf9d03121a6cac264257d31e30c54f32ed446681b2fce867fde7740ae93203c2d294b49016a10e2763580a64f9ecebd
+  data.tar.gz: 798314b57e9add79b6723e07be83fc4ba0115fea3d9710e84d7be71e330b3fd5aee6c09ee040f766b2bba96c749be6935439f1f647f03f991c71cf59d9916cc8

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    markdown_helper (1.7.0)
+    markdown_helper (1.8.0)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -12,8 +12,8 @@
 
 Command-line interface is now supported:
 
-* ```markdown_helper include [options] template_file_path markdown_file_path```
-* ```markdown_helper resolve [options] template_file_path markdown_file_path```
+* Added first [use cases](markdown/use_cases/use_cases.md#use-cases) (there will be more).
+* Deprecated treatment ```:verbatim```, changing to ```:markdown```.  The older term could be confusing, because although text to be treated ```:verbatim``` is included 'verbatim' (without change), it will be processed as GitHub markdown.
 
 ## What's This?
 
@@ -87,11 +87,11 @@ end
 
 Comment text is written into the output between the comment delimiters <code>\<!--</code> and <code>--></code>
 
-#### Verbatim
+#### Markdown
 
-Verbatim text is included unadorned.  Most often, verbatim text is markdown to be rendered as part of the markdown page.
+Markdown text is included unadorned, and will be processed on GitHub as markdown.
 
-The verbatim text is itself scanned for nested includes.
+The markdown text is itself scanned for nested includes.
 
 ### Usage
 
@@ -148,7 +148,7 @@ where:
 * *format* (in square brackets) is one of the following:
   * Highlighting mode such as <code>[ruby]</code>, to include a highlighted code block.  This can be any Ace mode mentioned in [GitHub Languages](https://github.com/github/linguist/blob/master/lib/linguist/languages.yml).
   * <code>[:code_block]</code>, to include a plain code block.
-  * <code>[:verbatim]</code>, to include text verbatim (to be rendered as markdown).
+  * <code>[:markdown]</code>, to include text markdown (to be rendered as markdown).
 * *relative_file_path* points to the file to be included.
 
 ##### Example Include Descriptions
@@ -160,7 +160,7 @@ where:
 
 @[:code_block](my_language.xyzzy)
 
-@[:verbatim](my_markdown.md)
+@[:markdown](my_markdown.md)
 ```
 <!-- <<<<<< END INCLUDED FILE (code_block): SOURCE markdown/include.md -->
 

data/lib/markdown_helper.rb

@@ -38,11 +38,11 @@ class MarkdownHelper
   # @example pragma to include text as a plain code block.
   #   @[:code_block](foo.xyz)
   #
-  # @example pragma to include text verbatim, to be rendered as markdown.
-  #   @[:verbatim](foo.md)
+  # @example pragma to include text markdown, to be rendered as markdown.
+  #   @[:markdown](foo.md)
   def include(template_file_path, markdown_file_path)
     send(:generate_file, template_file_path, markdown_file_path, __method__) do |input_lines, output_lines|
-      send(:include_files, template_file_path, input_lines, output_lines, verbatim_inclusions = {})
+      send(:include_files, template_file_path, input_lines, output_lines, markdown_inclusions = {})
     end
   end
 
@@ -106,7 +106,7 @@ class MarkdownHelper
     output
   end
 
-  def include_files(includer_file_path, input_lines, output_lines, verbatim_inclusions)
+  def include_files(includer_file_path, input_lines, output_lines, markdown_inclusions)
 
     input_lines.each_with_index do |input_line, line_index|
       match_data = input_line.match(INCLUDE_REGEXP)
@@ -119,8 +119,12 @@ class MarkdownHelper
       treatment = case treatment
                     when ':code_block'
                       :code_block
+                    when ':markdown'
+                      :markdown
                     when ':verbatim'
-                      :verbatim
+                      message = "Treatment ':verbatim' is deprecated; please use treatment ':markdown'."
+                      warn(message)
+                      :markdown
                     when ':comment'
                       :comment
                     else
@@ -132,12 +136,14 @@ class MarkdownHelper
           relative_included_file_path
       )
       included_real_path = new_inclusion.included_real_path
-      if treatment == :verbatim
-        previously_included = verbatim_inclusions.include?(new_inclusion.included_real_path)
+      if treatment == :markdown
+        previously_included = markdown_inclusions.include?(included_real_path)
         if previously_included
-          backtrace = verbatim_inclusions.values.push(new_inclusion)
+          markdown_inclusions.store(included_real_path, new_inclusion)
           message_lines = ['Includes are circular:']
-          backtrace.each_with_index do |inclusion, i|
+           i = 0
+          markdown_inclusions.each_with_index do |path_and_inclusion, i|
+            _, inclusion = *path_and_inclusion
             message_lines.push("  Level #{i}:")
             message_lines.push("    Includer: #{inclusion.includer_file_path}:#{inclusion.includer_line_number}")
             message_lines.push("    Relative file path: #{inclusion.relative_included_file_path}")
@@ -147,7 +153,6 @@ class MarkdownHelper
           message = message_lines.join("\n")
           raise RuntimeError.new(message)
         end
-        verbatim_inclusions[included_real_path] = new_inclusion
       end
       output_lines.push(comment(" >>>>>> BEGIN INCLUDED FILE (#{treatment}): SOURCE #{new_inclusion.included_file_path} ")) unless pristine
       include_lines = File.readlines(new_inclusion.included_file_path)
@@ -156,9 +161,11 @@ class MarkdownHelper
         warn(message)
       end
       case treatment
-        when :verbatim
+        when :markdown
           # Pass through unadorned, but honor any nested includes.
-          include_files(new_inclusion.included_file_path, include_lines, output_lines, verbatim_inclusions)
+          markdown_inclusions.store(included_real_path, new_inclusion)
+          include_files(new_inclusion.included_file_path, include_lines, output_lines, markdown_inclusions)
+          markdown_inclusions.delete(included_real_path)
         when :comment
           output_lines.push(comment(include_lines.join('')))
         else

data/lib/markdown_helper/version.rb

@@ -1,3 +1,3 @@
 class MarkdownHelper
-  VERSION = '1.7.0'
+  VERSION = '1.8.0'
 end

data/markdown/README.template.md

@@ -6,8 +6,8 @@
 
 Command-line interface is now supported:
 
-* ```markdown_helper include [options] template_file_path markdown_file_path```
-* ```markdown_helper resolve [options] template_file_path markdown_file_path```
+* Added first [use cases](markdown/use_cases/use_cases.md#use-cases) (there will be more).
+* Deprecated treatment ```:verbatim```, changing to ```:markdown```.  The older term could be confusing, because although text to be treated ```:verbatim``` is included 'verbatim' (without change), it will be processed as GitHub markdown.
 
 ## What's This?
 
@@ -59,11 +59,11 @@ Use the markdown helper to merge external files into a markdown (</code>.md</cod
 
 Comment text is written into the output between the comment delimiters <code>\<!--</code> and <code>--></code>
 
-#### Verbatim
+#### Markdown
 
-Verbatim text is included unadorned.  Most often, verbatim text is markdown to be rendered as part of the markdown page.
+Markdown text is included unadorned, and will be processed on GitHub as markdown.
 
-The verbatim text is itself scanned for nested includes.
+The markdown text is itself scanned for nested includes.
 
 ### Usage
 
@@ -86,7 +86,7 @@ where:
 * *format* (in square brackets) is one of the following:
   * Highlighting mode such as <code>[ruby]</code>, to include a highlighted code block.  This can be any Ace mode mentioned in [GitHub Languages](https://github.com/github/linguist/blob/master/lib/linguist/languages.yml).
   * <code>[:code_block]</code>, to include a plain code block.
-  * <code>[:verbatim]</code>, to include text verbatim (to be rendered as markdown).
+  * <code>[:markdown]</code>, to include text markdown (to be rendered as markdown).
 * *relative_file_path* points to the file to be included.
 
 ##### Example Include Descriptions

data/markdown/include.md

@@ -2,4 +2,4 @@
 
 @[:code_block](my_language.xyzzy)
 
-@[:verbatim](my_markdown.md)
+@[:markdown](my_markdown.md)

data/markdown/use_cases/Rakefile

@@ -0,0 +1,66 @@
+
+namespace :build do
+
+  desc 'Build use case markdown'
+  task :use_cases do
+    File.open('use_cases.md', 'w') do |use_case_file|
+      use_case_file.puts(<<EOT
+# Use Cases
+
+EOT
+      )
+      dir_path = File.dirname(__FILE__)
+      use_case_file_paths = []
+      tbs_file_paths = []
+      Dir.chdir(dir_path) do
+        use_case_dirs = {
+            :include => %w/
+                reuse_text
+                include_with_added_comments
+            /,
+            :resolve => %w/
+            /
+        }
+        use_case_dirs.each_pair do |section, dir_names|
+          use_case_file.puts(<<EOT
+## #{section.to_s.capitalize}
+
+EOT
+) unless dir_names.empty?
+          dir_names.each do |dir_name|
+            ruby_file_path = File.join(
+                dir_path,
+                section.to_s,
+                dir_name,
+                "#{dir_name}.rb"
+            )
+            if File.exist?(ruby_file_path)
+              command = "ruby #{ruby_file_path}"
+              system(command)
+            end
+            use_case_file_path = File.join(
+                dir_path,
+                section.to_s,
+                dir_name,
+                "#{dir_name}.md"
+            )
+            if File.exist?(use_case_file_path)
+              title_line = File.open(use_case_file_path).grep(/^#/).first.chomp
+              title = title_line.split(/\s/, 2).pop
+              use_case_file_name = File.basename(use_case_file_path)
+              use_case_name = File.basename(use_case_file_path, '.md')
+              use_case_anchor = use_case_name.gsub('_', '-')
+              use_case_relative_url = File.join(
+                  section.to_s,
+                  dir_name,
+                  use_case_file_name + '#' + use_case_anchor,
+              )
+              use_case_file.puts("* [#{title}](#{use_case_relative_url})")
+            end
+          end
+        end
+      end
+    end
+  end
+
+end

data/markdown/use_cases/include/include_generated_text/build.rb

@@ -0,0 +1,46 @@
+template_file_name = 'template.md'
+use_case_file_name = 'use_case.md'
+
+help_text_file_name = 'include_help.txt'
+includer_file_name = 'includer.md'
+included_file_name = 'included.md'
+
+help_command = "markdown_helper include --help > #{help_text_file_name}"
+include_command = 'markdown_helper include --pristine including_file.md include_help.txt'
+include_command = "markdown_helper include --pristine #{includer_file_name} #{included_file_name}"
+build_command = "markdown_helper include --pristine #{template_file_name} #{use_case_file_name}"
+build_command = "markdown_helper include --pristine #{template_file_name} #{use_case_file_name}"
+
+
+
+template = <<EOT
+### Include Generated Text
+
+Use the markdown helper to include text that is generated at project "build time."
+
+#### Example
+
+In this project, some markdown pages include help text from the project's executables.  At project "build" time, each executable is run with option ```--help```, and the help text is captured in a file.  That file is then included wherever it's needed.
+
+Thus the displayed help text is always up-to-date.
+
+### Command to Generate Help Text
+
+```sh
+#{help_command}
+```
+
+### Help Text
+
+@[:code_block](#{help_text_file_path})
+
+###
+
+EOT
+
+includer_file = <<EOT
+### File to Include Help
+
+@[:code_block](including_file.md)
+EOT
+

data/markdown/use_cases/include/include_with_added_comments/include_with_added_comments.md

@@ -0,0 +1,37 @@
+### Include with Added Comments
+
+By default (that is, without option ```--pristine```) file inclusion adds comments that:
+
+* Identify the includer file.
+* Identify each includee file.
+
+#### Includee File
+
+<code>includee.md</code>
+```markdown
+Text to be included.
+```
+
+#### Includer File
+
+<code>includer.md</code>
+```markdown
+@[:markdown](includee.md)
+```
+
+#### Inclusion Command
+
+```sh
+markdown_helper include includer.md included.md
+```
+
+#### File with Inclusion and Added Comments
+
+<code>included.md</code>
+```markdown
+<!-- >>>>>> BEGIN GENERATED FILE (include): SOURCE includer.md -->
+<!-- >>>>>> BEGIN INCLUDED FILE (markdown): SOURCE ./includee.md -->
+Text to be included.
+<!-- <<<<<< END INCLUDED FILE (markdown): SOURCE ./includee.md -->
+<!-- <<<<<< END GENERATED FILE (include): SOURCE includer.md -->
+```

data/markdown/use_cases/include/include_with_added_comments/include_with_added_comments.rb

@@ -0,0 +1,84 @@
+#!/usr/bin/env ruby
+
+use_case_dir_path = File.absolute_path(File.dirname(__FILE__))
+
+includee_file_name = 'includee.md'
+includee_file_path = File.join(
+    use_case_dir_path,
+    includee_file_name,
+)
+
+includer_file_name = 'includer.md'
+includer_file_path = File.join(
+    use_case_dir_path,
+    includer_file_name,
+)
+
+included_file_name = 'included.md'
+
+use_case_file_name = 'include_with_added_comments.md'
+use_case_file_path = File.join(
+    use_case_dir_path,
+    use_case_file_name,
+)
+
+template_file_name = 'template.md'
+template_file_path = File.join(
+    use_case_dir_path,
+    template_file_name,
+)
+
+include_command = "markdown_helper include #{includer_file_name} #{included_file_name}"
+
+File.write(
+    includee_file_path,
+    <<EOT
+Text to be included.
+EOT
+)
+
+File.write(
+    includer_file_path,
+    <<EOT
+@[:markdown](#{includee_file_name})
+EOT
+)
+
+# Example inclusion.
+Dir.chdir(use_case_dir_path) do
+  system(include_command)
+end
+
+File.write(
+    template_file_path,
+    <<EOT
+### Include with Added Comments
+
+By default (that is, without option ```--pristine```) file inclusion adds comments that:
+
+* Identify the includer file.
+* Identify each includee file.
+
+#### Includee File
+
+@[markdown](#{includee_file_name})
+
+#### Includer File
+
+@[markdown](#{includer_file_name})
+
+#### Inclusion Command
+
+```sh
+#{include_command}
+```
+
+#### File with Inclusion and Added Comments
+
+@[markdown](#{included_file_name})
+EOT
+)
+
+# Build use case.
+build_command = "markdown_helper include --pristine #{template_file_path} #{use_case_file_path}"
+system(build_command)

data/markdown/use_cases/include/include_with_added_comments/included.md

@@ -0,0 +1,5 @@
+<!-- >>>>>> BEGIN GENERATED FILE (include): SOURCE includer.md -->
+<!-- >>>>>> BEGIN INCLUDED FILE (markdown): SOURCE ./includee.md -->
+Text to be included.
+<!-- <<<<<< END INCLUDED FILE (markdown): SOURCE ./includee.md -->
+<!-- <<<<<< END GENERATED FILE (include): SOURCE includer.md -->

data/markdown/use_cases/include/include_with_added_comments/includee.md

@@ -0,0 +1 @@
+Text to be included.

data/markdown/use_cases/include/include_with_added_comments/includer.md

@@ -0,0 +1 @@
+@[:markdown](includee.md)

data/markdown/use_cases/include/include_with_added_comments/template.md

@@ -0,0 +1,24 @@
+### Include with Added Comments
+
+By default (that is, without option ```--pristine```) file inclusion adds comments that:
+
+* Identify the includer file.
+* Identify each includee file.
+
+#### Includee File
+
+@[markdown](includee.md)
+
+#### Includer File
+
+@[markdown](includer.md)
+
+#### Inclusion Command
+
+```sh
+markdown_helper include includer.md included.md
+```
+
+#### File with Inclusion and Added Comments
+
+@[markdown](included.md)

data/markdown/use_cases/include/reuse_text/included.md

@@ -0,0 +1,7 @@
+This file includes the useful text.
+
+This is some reusable text that can be included in more than one place (actually, in more than one file).
+
+Then includes it again.
+
+This is some reusable text that can be included in more than one place (actually, in more than one file).

data/markdown/use_cases/include/reuse_text/includer.md

@@ -0,0 +1,7 @@
+This file includes the useful text.
+
+@[:markdown](reusable_text.md)
+
+Then includes it again.
+
+@[:markdown](reusable_text.md)

data/markdown/use_cases/include/reuse_text/reusable_text.md

@@ -0,0 +1 @@
+This is some reusable text that can be included in more than one place (actually, in more than one file).

data/markdown/use_cases/include/reuse_text/reuse_text.md

@@ -0,0 +1,54 @@
+### Reuse Text
+
+Use file inclusion to stay DRY (Don't Repeat Yourself).
+
+Maintain reusable text in a separate file, then include it wherever it's needed.
+
+#### File to Be Included
+
+Here's a file containing some text that can be included:
+
+<code>reusable_text.md</code>
+```markdown
+This is some reusable text that can be included in more than one place (actually, in more than one file).
+```
+
+#### Includer File
+
+Here's a template file that includes it:
+
+<code>includer.md</code>
+```markdown
+This file includes the useful text.
+
+@[:markdown](reusable_text.md)
+
+Then includes it again.
+
+@[:markdown](reusable_text.md)
+```
+
+#### Command
+
+Here's the command to perform the inclusion:
+
+```sh
+markdown_helper include --pristine includer.md included.md
+```
+
+(Option ```--pristine``` suppresses comment insertion.)
+
+#### File with Inclusion
+
+Here's the finished file with the inclusion:
+
+<code>included.md</code>
+```markdown
+This file includes the useful text.
+
+This is some reusable text that can be included in more than one place (actually, in more than one file).
+
+Then includes it again.
+
+This is some reusable text that can be included in more than one place (actually, in more than one file).
+```

data/markdown/use_cases/include/reuse_text/reuse_text.rb

@@ -0,0 +1,100 @@
+#!/usr/bin/env ruby
+
+use_case_dir_path = File.absolute_path(File.dirname(__FILE__))
+
+reusable_text_file_name = 'reusable_text.md'
+reusable_text_file_path = File.join(
+    use_case_dir_path,
+    reusable_text_file_name,
+)
+
+includer_file_name = 'includer.md'
+includer_file_path = File.join(
+    use_case_dir_path,
+    includer_file_name,
+)
+
+included_file_name = 'included.md'
+
+use_case_file_name = 'reuse_text.md'
+use_case_file_path = File.join(
+    use_case_dir_path,
+    use_case_file_name,
+)
+
+template_file_name = 'template.md'
+template_file_path = File.join(
+    use_case_dir_path,
+    template_file_name,
+)
+
+include_command = "markdown_helper include --pristine #{includer_file_name} #{included_file_name}"
+
+File.write(
+    reusable_text_file_path,
+    <<EOT
+This is some reusable text that can be included in more than one place (actually, in more than one file).
+EOT
+)
+
+
+File.write(
+    includer_file_path,
+    <<EOT
+This file includes the useful text.
+
+@[:markdown](#{reusable_text_file_name})
+
+Then includes it again.
+
+@[:markdown](#{reusable_text_file_name})
+EOT
+)
+
+# Example inclusion.
+Dir.chdir(use_case_dir_path) do
+  system(include_command)
+end
+
+File.write(
+    template_file_path,
+    <<EOT
+### Reuse Text
+
+Use file inclusion to stay DRY (Don't Repeat Yourself).
+
+Maintain reusable text in a separate file, then include it wherever it's needed.
+
+#### File to Be Included
+
+Here's a file containing some text that can be included:
+
+@[markdown](#{reusable_text_file_name})
+
+#### Includer File
+
+Here's a template file that includes it:
+
+@[markdown](#{includer_file_name})
+
+#### Command
+
+Here's the command to perform the inclusion:
+
+```sh
+#{include_command}
+```
+
+@[:markdown](../../pristine.md)
+
+#### File with Inclusion
+
+Here's the finished file with the inclusion:
+
+@[markdown](#{included_file_name})
+EOT
+)
+
+# Build use case.
+build_command = "markdown_helper include --pristine #{template_file_path} #{use_case_file_path}"
+system(build_command)

data/markdown/use_cases/{reuse_text → include/reuse_text}/template.md

@@ -1,4 +1,4 @@
-### Use Case: Reuse Text
+### Reuse Text
 
 Use file inclusion to stay DRY (Don't Repeat Yourself).
 
@@ -8,24 +8,26 @@ Maintain reusable text in a separate file, then include it wherever it's needed.
 
 Here's a file containing some text that can be included:
 
-@[:code_block](reusable_text.md)
+@[markdown](reusable_text.md)
 
 #### Includer File
 
 Here's a template file that includes it:
 
-@[:code_block](includer.md)
+@[markdown](includer.md)
 
 #### Command
 
-Here's the command to perform the inclusion (```--pristine``` suppresses inclusion comments):
+Here's the command to perform the inclusion:
 
 ```sh
-markdown_helper include includer.md included.md
+markdown_helper include --pristine includer.md included.md
 ```
 
+@[:markdown](../../pristine.md)
+
 #### File with Inclusion
 
 Here's the finished file with the inclusion:
 
-@[:code_block](included.md)
+@[markdown](included.md)

data/markdown/use_cases/pristine.md

@@ -0,0 +1 @@
+(Option ```--pristine``` suppresses comment insertion.)

data/markdown/use_cases/resolve/gemify_images/gemify_images.md

@@ -0,0 +1,11 @@
+### Gemify Images
+
+Use the markdown helper to resolve image paths for a Ruby gem.
+
+When you release your GitHub project to  gem at RubyGems.org, the documentation is rebuilt into files on RubyDoc.info.  When YARD performs this rebuilding, it does some directory restructuring.
+
+If a markdown file contains an image description that has a relative file path, that path will not be valid in the documentation on RubyDoc.info, and the image will not display in the documentation.
+
+To avoid that error, use the markdown helper to resolve the relative path to an absolute path.
+
+This new absolute path points to a file that's automatically maintained in the GitHub project.  For that reason,

data/markdown/use_cases/resolve/gemify_images/gemify_images.rb

@@ -0,0 +1,39 @@
+#!/usr/bin/env ruby
+
+relative_image_file_name = 'relative_image.md'
+absolute_image_file_name = 'resolved_image.md'
+template_file_name = 'template.md'
+use_case_file_name = 'gemify_images.md'
+
+resolve_command = "markdown_helper resolve --pristine #{relative_image_file_name} #{absolute_image_file_name}"
+
+File.write(
+    relative_image_file_name,
+    <<EOT
+![html_image](../../../images/html.png)
+EOT
+)
+
+# Example resolution.
+system(resolve_command)
+
+File.write(
+    template_file_name,
+    <<EOT
+### Gemify Images
+
+Use the markdown helper to resolve image paths for a Ruby gem.
+
+When you release your GitHub project to  gem at RubyGems.org, the documentation is rebuilt into files on RubyDoc.info.  When YARD performs this rebuilding, it does some directory restructuring.
+
+If a markdown file contains an image description that has a relative file path, that path will not be valid in the documentation on RubyDoc.info, and the image will not display in the documentation.
+
+To avoid that error, use the markdown helper to resolve the relative path to an absolute path.
+
+This new absolute path points to a file that's automatically maintained in the GitHub project.  For that reason,
+EOT
+)
+
+# Build use case.
+build_command = "markdown_helper include --pristine #{template_file_name} #{use_case_file_name}"
+system(build_command)

data/markdown/use_cases/resolve/gemify_images/relative_image.md

@@ -0,0 +1 @@
+![html_image](../../../images/html.png)

data/markdown/use_cases/resolve/gemify_images/resolved_image.md

@@ -0,0 +1 @@
+<img src="" alt="html_image">

data/markdown/use_cases/{gemify_images → resolve/gemify_images}/template.md

@@ -1,4 +1,4 @@
-### RubyGem Images
+### Gemify Images
 
 Use the markdown helper to resolve image paths for a Ruby gem.
 
@@ -6,4 +6,6 @@ When you release your GitHub project to  gem at RubyGems.org, the documentation
 
 If a markdown file contains an image description that has a relative file path, that path will not be valid in the documentation on RubyDoc.info, and the image will not display in the documentation.
 
-To avoid that error, use the markdown helper to resolve the relative path to an absolute path.  This new absolute path points to a file that's automatically maintained in the GitHub project.
+To avoid that error, use the markdown helper to resolve the relative path to an absolute path.
+
+This new absolute path points to a file that's automatically maintained in the GitHub project.  For that reason,

data/markdown/use_cases/use_cases.md

@@ -0,0 +1,6 @@
+# Use Cases
+
+## Include
+
+* [Reuse Text](include/reuse_text/reuse_text.md#reuse-text)
+* [Include with Added Comments](include/include_with_added_comments/include_with_added_comments.md#include-with-added-comments)

data/markdown/verbatim_ruby_template.md

@@ -1 +1 @@
-@[:verbatim](include.rb)
+@[:markdown](include.rb)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: markdown_helper
 version: !ruby/object:Gem::Version
-  version: 1.7.0
+  version: 1.8.0
 platform: ruby
 authors:
 - burdettelamar
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-04-26 00:00:00.000000000 Z
+date: 2018-04-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -112,15 +112,28 @@ files:
 - markdown/include_usage.rb
 - markdown/resolve.md
 - markdown/resolve_usage.rb
-- markdown/use_cases/gemify_images/template.md
-- markdown/use_cases/resize_images/template.md
-- markdown/use_cases/reuse_text/included.md
-- markdown/use_cases/reuse_text/includer.md
-- markdown/use_cases/reuse_text/reusable_text.md
-- markdown/use_cases/reuse_text/reuse_text.md
-- markdown/use_cases/reuse_text/reuse_text.rb
-- markdown/use_cases/reuse_text/template.md
-- markdown/use_cases/verify_examples/template.md
+- markdown/use_cases/Rakefile
+- markdown/use_cases/include/include_generated_text/build.rb
+- markdown/use_cases/include/include_with_added_comments/include_with_added_comments.md
+- markdown/use_cases/include/include_with_added_comments/include_with_added_comments.rb
+- markdown/use_cases/include/include_with_added_comments/included.md
+- markdown/use_cases/include/include_with_added_comments/includee.md
+- markdown/use_cases/include/include_with_added_comments/includer.md
+- markdown/use_cases/include/include_with_added_comments/template.md
+- markdown/use_cases/include/reuse_text/included.md
+- markdown/use_cases/include/reuse_text/includer.md
+- markdown/use_cases/include/reuse_text/reusable_text.md
+- markdown/use_cases/include/reuse_text/reuse_text.md
+- markdown/use_cases/include/reuse_text/reuse_text.rb
+- markdown/use_cases/include/reuse_text/template.md
+- markdown/use_cases/pristine.md
+- markdown/use_cases/resolve/gemify_images/gemify_images.md
+- markdown/use_cases/resolve/gemify_images/gemify_images.rb
+- markdown/use_cases/resolve/gemify_images/relative_image.md
+- markdown/use_cases/resolve/gemify_images/resolved_image.md
+- markdown/use_cases/resolve/gemify_images/template.md
+- markdown/use_cases/resolve/resize_images/template.md
+- markdown/use_cases/use_cases.md
 - markdown/verbatim_ruby_template.md
 - markdown_helper.gemspec
 homepage: https://github.com/BurdetteLamar/markdown_helper

data/markdown/use_cases/reuse_text/included.md

@@ -1,7 +0,0 @@
-<!-- >>>>>> BEGIN GENERATED FILE (include): SOURCE includer.md -->
-This file includes the useful text.
-
-<!-- >>>>>> BEGIN INCLUDED FILE (verbatim): SOURCE ./reusable_text.md -->
-This is some useful text that can be included in more than one place (actually, in more than one file).
-<!-- <<<<<< END INCLUDED FILE (verbatim): SOURCE ./reusable_text.md -->
-<!-- <<<<<< END GENERATED FILE (include): SOURCE includer.md -->

data/markdown/use_cases/reuse_text/includer.md

@@ -1,3 +0,0 @@
-This file includes the useful text.
-
-@[:verbatim](reusable_text.md)

data/markdown/use_cases/reuse_text/reusable_text.md

@@ -1 +0,0 @@
-This is some useful text that can be included in more than one place (actually, in more than one file).

data/markdown/use_cases/reuse_text/reuse_text.md

@@ -1,48 +0,0 @@
-### Use Case: Reuse Text
-
-Use file inclusion to stay DRY (Don't Repeat Yourself).
-
-Maintain reusable text in a separate file, then include it wherever it's needed.
-
-#### File to Be Included
-
-Here's a file containing some text that can be included:
-
-<code>reusable_text.md</code>
-```
-This is some useful text that can be included in more than one place (actually, in more than one file).
-```
-
-#### Includer File
-
-Here's a template file that includes it:
-
-<code>includer.md</code>
-```
-This file includes the useful text.
-
-@[:verbatim](reusable_text.md)
-```
-
-#### Command
-
-Here's the command to perform the inclusion (```--pristine``` suppresses inclusion comments):
-
-```sh
-markdown_helper include includer.md included.md
-```
-
-#### File with Inclusion
-
-Here's the finished file with the inclusion:
-
-<code>included.md</code>
-```
-<!-- >>>>>> BEGIN GENERATED FILE (include): SOURCE includer.md -->
-This file includes the useful text.
-
-<!-- >>>>>> BEGIN INCLUDED FILE (verbatim): SOURCE ./reusable_text.md -->
-This is some useful text that can be included in more than one place (actually, in more than one file).
-<!-- <<<<<< END INCLUDED FILE (verbatim): SOURCE ./reusable_text.md -->
-<!-- <<<<<< END GENERATED FILE (include): SOURCE includer.md -->
-```

data/markdown/use_cases/reuse_text/reuse_text.rb

@@ -1,69 +0,0 @@
-#!/usr/bin/env ruby
-
-reusable_text_file_name = 'reusable_text.md'
-includer_file_name = 'includer.md'
-included_file_name = 'included.md'
-use_case_file_name = 'reuse_text.md'
-template_file_name = 'template.md'
-
-include_command = "markdown_helper include #{includer_file_name} #{included_file_name}"
-
-File.write(
-    reusable_text_file_name,
-    <<EOT
-This is some useful text that can be included in more than one place (actually, in more than one file).
-EOT
-)
-
-File.write(
-    includer_file_name,
-    <<EOT
-This file includes the useful text.
-
-@[:verbatim](#{reusable_text_file_name})
-EOT
-)
-
-# Example inclusion.
-system(include_command)
-
-File.write(
-    template_file_name,
-    <<EOT
-### Use Case: Reuse Text
-
-Use file inclusion to stay DRY (Don't Repeat Yourself).
-
-Maintain reusable text in a separate file, then include it wherever it's needed.
-
-#### File to Be Included
-
-Here's a file containing some text that can be included:
-
-@[:code_block](#{reusable_text_file_name})
-
-#### Includer File
-
-Here's a template file that includes it:
-
-@[:code_block](#{includer_file_name})
-
-#### Command
-
-Here's the command to perform the inclusion (```--pristine``` suppresses inclusion comments):
-
-```sh
-#{include_command}
-```
-
-#### File with Inclusion
-
-Here's the finished file with the inclusion:
-
-@[:code_block](#{included_file_name})
-EOT
-)
-
-# Build use case.
-build_command = "markdown_helper include --pristine #{template_file_name} #{use_case_file_name}"
-system(build_command)

data/markdown/use_cases/verify_examples/template.md

@@ -1,14 +0,0 @@
-### Evergreen Examples
-
-Example code and output that's embedded in a markdown file is dead text that may no longer be correct.
-
-Use the markdown helper to include example code and output -- but only after the project "build" has re-run the code and refreshed the output!
-
-Here's how:
-
-1.  Maintain each code example in a separate executable file.
-1.  Maintain markdown files that have include descriptions, rather than embedded code and output.
-1.  At project "build time" (controlled by a suitable build tool):
-    1.  Execute each code example, capturing its output to one or more files.
-    1.  Check output for errors and validity.
-    1.  Run the markdown helper to re-assemble the markdown files.