markdown_helper 1.8.0 → 1.9.0

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

@@ -0,0 +1,23 @@
+### 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
+
+@[markdown](includee.md)
+
+#### Includer File
+
+@[markdown](includer.md)
+
+The treatment token ```:markdown``` specifies that the included text is to be treated as more markdown.
+
+@[:markdown](../interface.md)
+
+#### File with Inclusion
+
+Here's the output file, after inclusion.
+
+@[markdown](included.md)

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

@@ -1,39 +1,68 @@
-#!/usr/bin/env ruby
+require_relative '../../use_case'
 
-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'
+class GemifyImages < UseCase
 
-resolve_command = "markdown_helper resolve --pristine #{relative_image_file_name} #{absolute_image_file_name}"
+  def self.build
 
-File.write(
-    relative_image_file_name,
-    <<EOT
-![html_image](../../../images/html.png)
-EOT
-)
+    use_case_dir_path = File.absolute_path(File.dirname(__FILE__))
 
-# Example resolution.
-system(resolve_command)
+    use_case = self.new(use_case_dir_path)
 
-File.write(
-    template_file_name,
-    <<EOT
-### Gemify Images
+    reusable_text_file_name = 'reusable_text.md'
+    includer_file_name = 'includer.md'
+    included_file_name = 'included.md'
 
-Use the markdown helper to resolve image paths for a Ruby gem.
+    resolve_command = use_case.construct_resolve_command(includer_file_name, included_file_name, pristine = true)
+    build_command = use_case.construct_include_command(TEMPLATE_FILE_NAME, USE_CASE_FILE_NAME, pristine = true)
 
-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.
+    use_case.commands_to_execute.push(
+        resolve_command,
+        build_command,
+    )
 
-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.
+#
+#     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.
+#
+# #### The Problem
+#
+# 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.
+#
+# #### The Solution
+#
+# 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)
 
-To avoid that error, use the markdown helper to resolve the relative path to an absolute path.
+  end
 
-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)
+end

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

@@ -2,10 +2,14 @@
 
 Use the markdown helper to resolve image paths for a Ruby gem.
 
+#### The Problem
+
 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.
 
+#### The Solution
+
 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_case.rb

@@ -0,0 +1,45 @@
+class UseCase
+
+  attr_accessor :use_case_dir_path, :files_to_write, :commands_to_execute
+
+  USE_CASE_FILE_NAME = 'use_case.md'
+  TEMPLATE_FILE_NAME = 'use_case_template.md'
+
+  def initialize(use_case_dir_path)
+    self.use_case_dir_path = use_case_dir_path
+    self.files_to_write = {}
+    self.commands_to_execute = []
+  end
+
+  def build
+    Dir.chdir(use_case_dir_path) do
+      files_to_write.each_pair do |file_name, text|
+        File.open(file_name, 'w') do |file|
+          file.write(text)
+        end
+      end
+      commands_to_execute.each do |command|
+        system(command)
+      end
+    end
+  end
+
+  def construct_command(command, template_file_path, markdown_file_path, pristine = false)
+    pristine_option = pristine ? '--pristine ' : ''
+    "markdown_helper #{command} #{pristine_option}#{template_file_path} #{markdown_file_path}"
+  end
+
+  def construct_include_command(template_file_path, markdown_file_path, pristine = false)
+    construct_command(:include, template_file_path, markdown_file_path, pristine)
+  end
+
+  def construct_resolve_command(template_file_path, markdown_file_path, pristine = false)
+    construct_command(:resolve, template_file_path, markdown_file_path, pristine)
+  end
+
+  def UseCase.construct_include_command(template_file_path, markdown_file_path, pristine = false)
+    pristine_option = pristine ? '--pristine ' : ''
+    "markdown_helper include #{pristine_option}#{template_file_path} #{markdown_file_path}"
+  end
+
+end

data/markdown/use_cases/use_cases.md

@@ -2,5 +2,12 @@
 
 ## 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)
+* [Reuse Text](include/reuse_text/use_case.md#reuse-text)
+* [Include with Added Comments](include/include_with_added_comments/use_case.md#include-with-added-comments)
+* [Nest Inclusions](include/nest_inclusions/use_case.md#nest-inclusions)
+* [Include Markdown](include/include_markdown/use_case.md#include-markdown)
+* [Include a Code Block](include/include_code_block/use_case.md#include-code-block)
+* [Include Highlighted Code](include/include_highlighted_code/use_case.md#include-highlighted-code)
+* [Include Generated Text](include/include_generated_text/use_case.md#include-generated-text)
+* [Diagnose Missing Includee](include/diagnose_missing_includee/use_case.md#diagnose-missing-includee)
+* [Diagnose Circular Includes](include/diagnose_circular_includes/use_case.md#diagnose-circular-includes)

data/markdown_helper.gemspec

@@ -7,7 +7,7 @@ Gem::Specification.new do |spec|
   spec.name          = 'markdown_helper'
   spec.version       = MarkdownHelper::VERSION
   spec.authors       = ['burdettelamar']
-  spec.email         = ['BurdetteLamar@Yahoo.com']
+  spec.email         = ['burdettelamar@yahoo.com']
   spec.summary       = 'Class to help with GitHub markdown.'
   spec.description   = <<-EOT
 Class to help with GitHub markdown:

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: markdown_helper
 version: !ruby/object:Gem::Version
-  version: 1.8.0
+  version: 1.9.0
 platform: ruby
 authors:
 - burdettelamar
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-04-29 00:00:00.000000000 Z
+date: 2018-05-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -73,7 +73,7 @@ description: |
   * Image path resolution
   * Image attributes
 email:
-- BurdetteLamar@Yahoo.com
+- burdettelamar@yahoo.com
 executables:
 - markdown_helper
 extensions: []
@@ -103,29 +103,80 @@ files:
 - images/include.png
 - lib/markdown_helper.rb
 - lib/markdown_helper/version.rb
-- markdown/README.template.md
-- markdown/code_block_ruby_template.md
-- markdown/highlight_ruby_template.md
-- markdown/highlighted_ruby.md
-- markdown/include.md
-- markdown/include.rb
-- markdown/include_usage.rb
-- markdown/resolve.md
-- markdown/resolve_usage.rb
+- markdown/readme/README.template.md
+- markdown/readme/code_block_ruby_template.md
+- markdown/readme/highlight_ruby_template.md
+- markdown/readme/highlighted_ruby.md
+- markdown/readme/include.md
+- markdown/readme/include.rb
+- markdown/readme/include_usage.rb
+- markdown/readme/resolve.md
+- markdown/readme/resolve_usage.rb
+- markdown/readme/verbatim_ruby_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/diagnose_circular_includes/diagnose_circular_includes.err
+- markdown/use_cases/include/diagnose_circular_includes/diagnose_circular_includes.rb
+- markdown/use_cases/include/diagnose_circular_includes/include.rb
+- markdown/use_cases/include/diagnose_circular_includes/includer.md
+- markdown/use_cases/include/diagnose_circular_includes/includer_0.md
+- markdown/use_cases/include/diagnose_circular_includes/includer_1.md
+- markdown/use_cases/include/diagnose_circular_includes/includer_2.md
+- markdown/use_cases/include/diagnose_circular_includes/use_case.md
+- markdown/use_cases/include/diagnose_circular_includes/use_case_template.md
+- markdown/use_cases/include/diagnose_missing_includee/diagnose_missing_includee.err
+- markdown/use_cases/include/diagnose_missing_includee/diagnose_missing_includee.rb
+- markdown/use_cases/include/diagnose_missing_includee/include.rb
+- markdown/use_cases/include/diagnose_missing_includee/included.md
+- markdown/use_cases/include/diagnose_missing_includee/includer.md
+- markdown/use_cases/include/diagnose_missing_includee/includer_0.md
+- markdown/use_cases/include/diagnose_missing_includee/includer_1.md
+- markdown/use_cases/include/diagnose_missing_includee/includer_2.md
+- markdown/use_cases/include/diagnose_missing_includee/use_case.md
+- markdown/use_cases/include/diagnose_missing_includee/use_case_template.md
+- markdown/use_cases/include/include.rb
+- markdown/use_cases/include/include_code_block/hello.rb
+- markdown/use_cases/include/include_code_block/include_code_block.rb
+- markdown/use_cases/include/include_code_block/included.md
+- markdown/use_cases/include/include_code_block/includer.md
+- markdown/use_cases/include/include_code_block/use_case.md
+- markdown/use_cases/include/include_code_block/use_case_template.md
+- markdown/use_cases/include/include_generated_text/include_generated_text.rb
+- markdown/use_cases/include/include_generated_text/use_case.md
+- markdown/use_cases/include/include_generated_text/use_case_template.md
+- markdown/use_cases/include/include_highlighted_code/hello.rb
+- markdown/use_cases/include/include_highlighted_code/include_highlighted_code.rb
+- markdown/use_cases/include/include_highlighted_code/included.md
+- markdown/use_cases/include/include_highlighted_code/includer.md
+- markdown/use_cases/include/include_highlighted_code/use_case.md
+- markdown/use_cases/include/include_highlighted_code/use_case_template.md
+- markdown/use_cases/include/include_markdown/include_markdown.rb
+- markdown/use_cases/include/include_markdown/included.md
+- markdown/use_cases/include/include_markdown/includer.md
+- markdown/use_cases/include/include_markdown/markdown.md
+- markdown/use_cases/include/include_markdown/use_case.md
+- markdown/use_cases/include/include_markdown/use_case_template.md
+- markdown/use_cases/include/include_use_case.rb
 - 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/include_with_added_comments/use_case.md
+- markdown/use_cases/include/include_with_added_comments/use_case_template.md
+- markdown/use_cases/include/interface.md
+- markdown/use_cases/include/nest_inclusions/included.md
+- markdown/use_cases/include/nest_inclusions/includee.md
+- markdown/use_cases/include/nest_inclusions/includer.md
+- markdown/use_cases/include/nest_inclusions/nest_inclusions.rb
+- markdown/use_cases/include/nest_inclusions/nested_includee.md
+- markdown/use_cases/include/nest_inclusions/use_case.md
+- markdown/use_cases/include/nest_inclusions/use_case_template.md
+- markdown/use_cases/include/reuse_text/include.rb
 - markdown/use_cases/include/reuse_text/included.md
+- markdown/use_cases/include/reuse_text/includee.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/include/reuse_text/use_case.md
+- markdown/use_cases/include/reuse_text/use_case_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
@@ -133,8 +184,8 @@ files:
 - 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_case.rb
 - markdown/use_cases/use_cases.md
-- markdown/verbatim_ruby_template.md
 - markdown_helper.gemspec
 homepage: https://github.com/BurdetteLamar/markdown_helper
 licenses:

data/markdown/highlighted_ruby.md

@@ -1,12 +0,0 @@
-<!-- >>>>>> BEGIN GENERATED FILE (include): SOURCE markdown/highlight_ruby_template.md -->
-<!-- >>>>>> BEGIN INCLUDED FILE (ruby): SOURCE markdown/include.rb -->
-<code>include.rb</code>
-```ruby
-class RubyCode
-  def initialize
-    raise RuntimeError.new('I am only an example!')
-  end
-end
-```
-<!-- <<<<<< END INCLUDED FILE (ruby): SOURCE markdown/include.rb -->
-<!-- <<<<<< END GENERATED FILE (include): SOURCE markdown/highlight_ruby_template.md -->

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

@@ -1,46 +0,0 @@
-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

@@ -1,37 +0,0 @@
-### 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/reuse_text/reusable_text.md

@@ -1 +0,0 @@
-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

@@ -1,54 +0,0 @@
-### 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).
-```