markdown_helper 1.5.1 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 38e7b32f5f6e0b8b46878e5ef5586d2f94852c60
-  data.tar.gz: efefe056e97327bc5dafd225774e52ce81955a03
+  metadata.gz: b7bd60eb7a1f8efbccafc0efda8eb504d344e7c1
+  data.tar.gz: c1a3ff13373ee40259f46e3769c300a3ca8c7f4b
 SHA512:
-  metadata.gz: 62891f62df9f8a0a68f1cd865335057285e9a9b1cd28d7ff0d153fdb05e679bb61accec96ec626f6dfc450843e8bc3f6f0fbc7b3b38d09d3de9e7488a2c88e9c
-  data.tar.gz: 588635b8668e9757edcb0d1eaa11364c640763471b3d943410a2a650344f7168d152fd2f9cd6752c494ee57c57405702153f7b57f4da1e1fcec28781144f20ee
+  metadata.gz: e301810ed4eb380b8b5edf4effee8ff17c2acfaf25c49e0e9468068bc983dccb6ebfbc661fe0048a919795ef7866adbd7731814534175135ab01e8a01cf29105
+  data.tar.gz: a6e5f17c0aa9788df2ec2c64f9536590dae2dc49e7701a6e60dc8bab8022084afbce6c3189e08014424c0e0f89e35501aaec6123054f3356f2f658dd4e4868a0

data/Gemfile.lock

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

data/README.md

@@ -1,16 +1,19 @@
-<!-- >>>>>> BEGIN GENERATED FILE (include): SOURCE readme_files/temp_resolved.md -->
-<!-- >>>>>> BEGIN GENERATED FILE (resolve): SOURCE readme_files/README.template.md -->
+<!-- >>>>>> BEGIN GENERATED FILE (include): SOURCE markdown/temp_resolved.md -->
+<!-- >>>>>> BEGIN GENERATED FILE (resolve): SOURCE markdown/README.template.md -->
 # Markdown Helper
 
-<!-- >>>>>> BEGIN RESOLVED IMAGES: INPUT-LINE '![Gem Version](https://badge.fury.io/rb/markdown_helper.svg)
+<!-- >>>>>> BEGIN RESOLVED IMAGES: INPUT-LINE '![Gem Version](https://badge.fury.io/rb/markdown_helper.svg) [Visit gem markdown_helper](https://rubygems.org/gems/markdown_helper)
 ' -->
-<img src="https://badge.fury.io/rb/markdown_helper.svg" alt="Gem Version">
-<!-- <<<<<< END RESOLVED IMAGES: INPUT-LINE '![Gem Version](https://badge.fury.io/rb/markdown_helper.svg)
+<img src="https://badge.fury.io/rb/markdown_helper.svg" alt="Gem Version"> [Visit gem markdown_helper](https://rubygems.org/gems/markdown_helper)
+<!-- <<<<<< END RESOLVED IMAGES: INPUT-LINE '![Gem Version](https://badge.fury.io/rb/markdown_helper.svg) [Visit gem markdown_helper](https://rubygems.org/gems/markdown_helper)
 ' -->
 
 ## What's New?
 
-Nested file inclusion is now supported, which means that an included file can include more files.  This applies only to a file included verbatim, not to a file included as a code block or as a markdown comment.
+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```
 
 ## What's This?
 
@@ -54,7 +57,7 @@ Use the markdown helper to merge external files into a markdown (</code>.md</cod
 
 #### Highlighted Code Block
 
-<!-- >>>>>> BEGIN INCLUDED FILE (ruby): SOURCE readme_files/include.rb -->
+<!-- >>>>>> BEGIN INCLUDED FILE (ruby): SOURCE markdown/include.rb -->
 <code>include.rb</code>
 ```ruby
 class RubyCode
@@ -63,11 +66,11 @@ class RubyCode
   end
 end
 ```
-<!-- <<<<<< END INCLUDED FILE (ruby): SOURCE readme_files/include.rb -->
+<!-- <<<<<< END INCLUDED FILE (ruby): SOURCE markdown/include.rb -->
 
 #### Plain Code Block
 
-<!-- >>>>>> BEGIN INCLUDED FILE (code_block): SOURCE readme_files/include.rb -->
+<!-- >>>>>> BEGIN INCLUDED FILE (code_block): SOURCE markdown/include.rb -->
 <code>include.rb</code>
 ```
 class RubyCode
@@ -76,7 +79,7 @@ class RubyCode
   end
 end
 ```
-<!-- <<<<<< END INCLUDED FILE (code_block): SOURCE readme_files/include.rb -->
+<!-- <<<<<< END INCLUDED FILE (code_block): SOURCE markdown/include.rb -->
 
 [Note:  In the gem documentation, RubyDoc.info chooses to highlight this code block regardless.  Go figure.]
 
@@ -94,11 +97,11 @@ The verbatim text is itself scanned for nested includes.
 
 #### CLI
 
-<!-- >>>>>> BEGIN INCLUDED FILE (code_block): SOURCE readme_files/../bin/usage/include.txt -->
+<!-- >>>>>> BEGIN INCLUDED FILE (code_block): SOURCE markdown/../bin/usage/include.txt -->
 <code>include.txt</code>
 ```
 
-Usage: include [options] template_file_path markdown_file_page
+Usage: markdown_helper include [options] template_file_path markdown_file_path
         --pristine                   No comments added
         --help                       Display help
     
@@ -112,11 +115,11 @@ Usage: include [options] template_file_path markdown_file_page
     * Both file types are .md.
     * The template file contains file inclusion descriptions.
 ```
-<!-- <<<<<< END INCLUDED FILE (code_block): SOURCE readme_files/../bin/usage/include.txt -->
+<!-- <<<<<< END INCLUDED FILE (code_block): SOURCE markdown/../bin/usage/include.txt -->
 
 #### API
 
-<!-- >>>>>> BEGIN INCLUDED FILE (ruby): SOURCE readme_files/include_usage.rb -->
+<!-- >>>>>> BEGIN INCLUDED FILE (ruby): SOURCE markdown/include_usage.rb -->
 <code>include_usage.rb</code>
 ```ruby
 require 'markdown_helper'
@@ -132,7 +135,7 @@ markdown_helper.include(template_file_path, markdown_file_path)
 markdown_helper = MarkdownHelper.new(:pristine => true)
 markdown_helper.include(template_file_path, markdown_file_path)
 ```
-<!-- <<<<<< END INCLUDED FILE (ruby): SOURCE readme_files/include_usage.rb -->
+<!-- <<<<<< END INCLUDED FILE (ruby): SOURCE markdown/include_usage.rb -->
 
 #### Include Descriptions
 
@@ -150,7 +153,7 @@ where:
 
 ##### Example Include Descriptions
 
-<!-- >>>>>> BEGIN INCLUDED FILE (code_block): SOURCE readme_files/include.md -->
+<!-- >>>>>> BEGIN INCLUDED FILE (code_block): SOURCE markdown/include.md -->
 <code>include.md</code>
 ```code_block
 @[ruby](my_ruby.rb)
@@ -159,7 +162,7 @@ where:
 
 @[:verbatim](my_markdown.md)
 ```
-<!-- <<<<<< END INCLUDED FILE (code_block): SOURCE readme_files/include.md -->
+<!-- <<<<<< END INCLUDED FILE (code_block): SOURCE markdown/include.md -->
 
 ## Image Path Resolution 
 
@@ -181,10 +184,11 @@ This matters because when markdown becomes part of a Ruby gem, its images will h
 
 #### CLI
 
-<!-- >>>>>> BEGIN INCLUDED FILE (code_block): SOURCE readme_files/../bin/usage/resolve.txt -->
+<!-- >>>>>> BEGIN INCLUDED FILE (code_block): SOURCE markdown/../bin/usage/resolve.txt -->
 <code>resolve.txt</code>
 ```
-Usage: bin/resolve [options] template_file_path markdown_file_page
+
+Usage: markdown_helper resolve [options] template_file_path markdown_file_path
         --pristine                   No comments added
         --help                       Display help
     
@@ -198,11 +202,11 @@ Usage: bin/resolve [options] template_file_path markdown_file_page
     * Both file types are .md.
     * The template file contains image descriptions.
 ```
-<!-- <<<<<< END INCLUDED FILE (code_block): SOURCE readme_files/../bin/usage/resolve.txt -->
+<!-- <<<<<< END INCLUDED FILE (code_block): SOURCE markdown/../bin/usage/resolve.txt -->
 
 #### API
 
-<!-- >>>>>> BEGIN INCLUDED FILE (ruby): SOURCE readme_files/resolve_usage.rb -->
+<!-- >>>>>> BEGIN INCLUDED FILE (ruby): SOURCE markdown/resolve_usage.rb -->
 <code>resolve_usage.rb</code>
 ```ruby
 require 'markdown_helper'
@@ -218,7 +222,7 @@ markdown_helper.resolve(template_file_path, markdown_file_path)
 markdown_helper = MarkdownHelper.new(:pristine => true)
 markdown_helper.resolve(template_file_path, markdown_file_path)
 ```
-<!-- <<<<<< END INCLUDED FILE (ruby): SOURCE readme_files/resolve_usage.rb -->
+<!-- <<<<<< END INCLUDED FILE (ruby): SOURCE markdown/resolve_usage.rb -->
 
 #### Image Descriptions
 
@@ -234,7 +238,7 @@ where:
 
 ##### Example Image Descriptions
 
-<!-- >>>>>> BEGIN INCLUDED FILE (code_block): SOURCE readme_files/resolve.md -->
+<!-- >>>>>> BEGIN INCLUDED FILE (code_block): SOURCE markdown/resolve.md -->
 <code>resolve.md</code>
 ```code_block
 ![my_alt](image/image.png)
@@ -243,7 +247,7 @@ where:
 
 ![my_alt](image/image.png| width=50 height=50)
 ```
-<!-- <<<<<< END INCLUDED FILE (code_block): SOURCE readme_files/resolve.md -->
+<!-- <<<<<< END INCLUDED FILE (code_block): SOURCE markdown/resolve.md -->
 
 ## Image Attributes
 
@@ -263,10 +267,11 @@ Use the markdown helper to add image attributes in a markdown (</code>.md</code>
 
 #### CLI
 
-<!-- >>>>>> BEGIN INCLUDED FILE (code_block): SOURCE readme_files/../bin/usage/resolve.txt -->
+<!-- >>>>>> BEGIN INCLUDED FILE (code_block): SOURCE markdown/../bin/usage/resolve.txt -->
 <code>resolve.txt</code>
 ```
-Usage: bin/resolve [options] template_file_path markdown_file_page
+
+Usage: markdown_helper resolve [options] template_file_path markdown_file_path
         --pristine                   No comments added
         --help                       Display help
     
@@ -280,11 +285,11 @@ Usage: bin/resolve [options] template_file_path markdown_file_page
     * Both file types are .md.
     * The template file contains image descriptions.
 ```
-<!-- <<<<<< END INCLUDED FILE (code_block): SOURCE readme_files/../bin/usage/resolve.txt -->
+<!-- <<<<<< END INCLUDED FILE (code_block): SOURCE markdown/../bin/usage/resolve.txt -->
 
 #### API
 
-<!-- >>>>>> BEGIN INCLUDED FILE (ruby): SOURCE readme_files/resolve_usage.rb -->
+<!-- >>>>>> BEGIN INCLUDED FILE (ruby): SOURCE markdown/resolve_usage.rb -->
 <code>resolve_usage.rb</code>
 ```ruby
 require 'markdown_helper'
@@ -300,7 +305,7 @@ markdown_helper.resolve(template_file_path, markdown_file_path)
 markdown_helper = MarkdownHelper.new(:pristine => true)
 markdown_helper.resolve(template_file_path, markdown_file_path)
 ```
-<!-- <<<<<< END INCLUDED FILE (ruby): SOURCE readme_files/resolve_usage.rb -->
+<!-- <<<<<< END INCLUDED FILE (ruby): SOURCE markdown/resolve_usage.rb -->
 
 #### Image Descriptions
 
@@ -316,7 +321,7 @@ where:
 
 ##### Example Image Descriptions
 
-<!-- >>>>>> BEGIN INCLUDED FILE (code_block): SOURCE readme_files/resolve.md -->
+<!-- >>>>>> BEGIN INCLUDED FILE (code_block): SOURCE markdown/resolve.md -->
 <code>resolve.md</code>
 ```code_block
 ![my_alt](image/image.png)
@@ -325,7 +330,7 @@ where:
 
 ![my_alt](image/image.png| width=50 height=50)
 ```
-<!-- <<<<<< END INCLUDED FILE (code_block): SOURCE readme_files/resolve.md -->
+<!-- <<<<<< END INCLUDED FILE (code_block): SOURCE markdown/resolve.md -->
 
 ## What Should Be Next?
 
@@ -338,5 +343,5 @@ I have opened some enhancement Issues in the GitHub [markdown_helper](https://gi
 * [Pagination](https://github.com/BurdetteLamar/markdown_helper/issues/40):  series of markdown pages connected by prev/next navigation links.
 
 Feel free to comment on any of these, or to add more Issues (enhancement or otherwise).
-<!-- <<<<<< END GENERATED FILE (resolve): SOURCE readme_files/README.template.md -->
-<!-- <<<<<< END GENERATED FILE (include): SOURCE readme_files/temp_resolved.md -->
+<!-- <<<<<< END GENERATED FILE (resolve): SOURCE markdown/README.template.md -->
+<!-- <<<<<< END GENERATED FILE (include): SOURCE markdown/temp_resolved.md -->

data/Rakefile

@@ -14,14 +14,14 @@ namespace :build do
     Rake::Task['build:usages'].invoke
     require_relative 'lib/markdown_helper'
     markdown_helper = MarkdownHelper.new
-    template_file_path = 'readme_files/highlight_ruby_template.md'
-    markdown_file_path = 'readme_files/highlighted_ruby.md'
+    template_file_path = 'markdown/highlight_ruby_template.md'
+    markdown_file_path = 'markdown/highlighted_ruby.md'
     markdown_helper.include(template_file_path, markdown_file_path)
     # Do the resolve before the include, so that the included text is not also resolved.
     # This protects example code from being also resolved, thus damaging the example code.
     # Temp file must be in the same directory as its source (it becomes the source).
-    temp_file_path = 'readme_files/temp_resolved.md'
-    markdown_helper.resolve('readme_files/README.template.md', temp_file_path)
+    temp_file_path = 'markdown/temp_resolved.md'
+    markdown_helper.resolve('markdown/README.template.md', temp_file_path)
     readme_file_path = 'README.md'
     markdown_helper.include(temp_file_path, readme_file_path)
     File.delete(temp_file_path)
@@ -33,7 +33,7 @@ namespace :build do
         include
         resolve
     /.each do |executable_name|
-      usage_text = `ruby bin/#{executable_name} --help`
+      usage_text = `ruby bin/_#{executable_name} --help`
       usage_file_path = "bin/usage/#{executable_name}.txt"
       File.open(usage_file_path, 'w') do |file|
         file.puts(usage_text)

data/bin/_include

@@ -0,0 +1,49 @@
+#!/usr/bin/env ruby
+
+require 'optparse'
+
+require 'markdown_helper'
+
+options = {:pristine => false}
+
+# Save opts for use below.
+opts = nil
+parser = OptionParser.new do |_opts|
+  opts = _opts
+  _opts.banner = "Usage: markdown_helper include [options] template_file_path markdown_file_path"
+  _opts.on('--pristine', 'No comments added') do |_|
+    options[:pristine] = true
+  end
+  _opts.on('--help', 'Display help') do
+    usage(_opts)
+  end
+end
+
+def usage(opts)
+  puts ''
+  puts opts
+  puts <<-EOT
+    
+  where
+
+    * template_file_path is the path to an existing file.
+    * markdown_file_path is the path to a file to be created.
+
+  Typically:
+
+    * Both file types are .md.
+    * The template file contains file inclusion descriptions.
+EOT
+  exit
+end
+
+parser.parse!
+
+template_file_path, markdown_file_path = ARGV
+
+usage(opts) unless ARGV.size == 2
+usage(opts) unless File.readable?(template_file_path)
+usage(opts) unless File.writable?(File.dirname(markdown_file_path))
+
+MarkdownHelper.new(options).include(template_file_path, markdown_file_path)
+

data/bin/_resolve

@@ -0,0 +1,48 @@
+#!/usr/bin/env ruby
+
+require 'optparse'
+
+require 'markdown_helper'
+
+options = {:pristine => false}
+
+# Save opts for use below.
+opts = nil
+parser = OptionParser.new do |_opts|
+  opts = _opts
+  _opts.banner = "Usage: markdown_helper resolve [options] template_file_path markdown_file_path"
+  _opts.on('--pristine', 'No comments added') do |_|
+    options[:pristine] = true
+  end
+  _opts.on('--help', 'Display help') do
+    usage(_opts)
+  end
+end
+
+def usage(opts)
+  puts ''
+  puts opts
+  puts <<-EOT
+    
+  where
+
+    * template_file_path is the path to an existing file.
+    * markdown_file_path is the path to a file to be created.
+
+  Typically:
+
+    * Both file types are .md.
+    * The template file contains image descriptions.
+  EOT
+  exit
+end
+
+parser.parse!
+
+template_file_path, markdown_file_path = ARGV
+
+usage(opts) unless ARGV.size == 2
+usage(opts) unless File.readable?(template_file_path)
+usage(opts) unless File.writable?(File.dirname(markdown_file_path))
+
+MarkdownHelper.new(options).resolve(template_file_path, markdown_file_path)

data/bin/include

@@ -10,7 +10,7 @@ options = {:pristine => false}
 opts = nil
 parser = OptionParser.new do |_opts|
   opts = _opts
-  _opts.banner = "Usage: #{File.basename(__FILE__)} [options] template_file_path markdown_file_page"
+  _opts.banner = "Usage: #{File.basename(__FILE__)} [options] template_file_path markdown_file_path"
   _opts.on('--pristine', 'No comments added') do |_|
     options[:pristine] = true
   end
@@ -45,14 +45,6 @@ usage(opts) unless ARGV.size == 2
 usage(opts) unless File.readable?(template_file_path)
 usage(opts) unless File.writable?(File.dirname(markdown_file_path))
 
-# This code, outside of a class, had interference from Module#include.
-# So now it's in a class.
-class AvoidModule
-  def initialize(template_file_path, markdown_file_path, options)
-    markdown_helper = MarkdownHelper.new(options)
-    markdown_helper.include(template_file_path, markdown_file_path)
-  end
-end
-
-AvoidModule.new(template_file_path, markdown_file_path, options)
+warn('This include is deprecated.  Please use command "markdown_helper include".')
+MarkdownHelper.new(options).include(template_file_path, markdown_file_path)
 

data/bin/markdown_helper

@@ -0,0 +1,37 @@
+#!/usr/bin/env ruby
+
+require 'markdown_helper'
+
+# Each command foo has a corresponding Ruby executable _foo.
+def command_keywords
+  dir_path = File.dirname(__FILE__)
+  dirs = Dir.entries(dir_path)
+  command_file_names = dirs.select{ |x| x.start_with?('_')}
+  command_file_names.collect {|x| x.sub(/^_/, '')}
+end
+
+
+def usage
+  puts <<-EOT
+  Usage: markdown_helper command [options] [args]
+
+  where
+
+    * Command is one of #{command_keywords.inspect}.
+
+  EOT
+  exit
+end
+
+command_keyword = ARGV[0]
+unless command_keywords.include?(command_keyword)
+  usage
+end
+
+bindir = File.dirname(__FILE__)
+bin_file_path = File.absolute_path(File.join(
+                    bindir,
+                    '_' + command_keyword,
+))
+command = "ruby #{bin_file_path}"
+system(command)

data/bin/resolve

@@ -6,17 +6,21 @@ require 'markdown_helper'
 
 options = {:pristine => false}
 
-parser = OptionParser.new do|opts|
-  opts.banner = "Usage: #{__FILE__} [options] template_file_path markdown_file_page"
-  opts.on('--pristine', 'No comments added') do |_|
+# Save opts for use below.
+opts = nil
+parser = OptionParser.new do |_opts|
+  opts = _opts
+  _opts.banner = "Usage: #{File.basename(__FILE__)} [options] template_file_path markdown_file_path"
+  _opts.on('--pristine', 'No comments added') do |_|
     options[:pristine] = true
   end
-  opts.on('--help', 'Display help') do
-    usage(opts)
+  _opts.on('--help', 'Display help') do
+    usage(_opts)
   end
 end
 
 def usage(opts)
+  puts ''
   puts opts
   puts <<-EOT
     
@@ -37,8 +41,9 @@ parser.parse!
 
 template_file_path, markdown_file_path = ARGV
 
-usage(options) unless ARGV.size == 2
-usage(options) unless File.readable?(template_file_path)
-usage(options) unless File.writable?(File.dirname(markdown_file_path))
+usage(opts) unless ARGV.size == 2
+usage(opts) unless File.readable?(template_file_path)
+usage(opts) unless File.writable?(File.dirname(markdown_file_path))
 
+warn('This resolve is deprecated.  Please use command "markdown_helper resolve".')
 MarkdownHelper.new(options).resolve(template_file_path, markdown_file_path)

data/bin/usage/include.txt

@@ -1,5 +1,5 @@
 
-Usage: include [options] template_file_path markdown_file_page
+Usage: markdown_helper include [options] template_file_path markdown_file_path
         --pristine                   No comments added
         --help                       Display help
     

data/bin/usage/resolve.txt

@@ -1,4 +1,5 @@
-Usage: bin/resolve [options] template_file_path markdown_file_page
+
+Usage: markdown_helper resolve [options] template_file_path markdown_file_path
         --pristine                   No comments added
         --help                       Display help
     

data/lib/markdown_helper.rb

@@ -42,7 +42,7 @@ class MarkdownHelper
   #   @[:verbatim](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, paths = [], realpaths = [])
+      send(:include_files, template_file_path, input_lines, output_lines, verbatim_inclusions = {})
     end
   end
 
@@ -106,31 +106,17 @@ class MarkdownHelper
     output
   end
 
-  def include_files(template_file_path, input_lines, output_lines, paths, realpaths)
-    realpath = Pathname.new(template_file_path).realpath
-    i = realpaths.index(realpath)
-    if i
-      old_path = paths[i]
-      new_path = template_file_path
-      realpath = realpaths[i]
-      message = <<EOT
-Includes are circular:
-  Old path:  #{old_path}
-  New path:  #{new_path}
-  Real path: #{realpath}
-EOT
-      raise RuntimeError.new(message)
-    end
-    paths.push(template_file_path)
-    realpaths.push(realpath)
+  def include_files(includer_file_path, input_lines, output_lines, verbatim_inclusions)
 
-    input_lines.each do |input_line|
+    input_lines.each_with_index do |input_line, line_index|
       match_data = input_line.match(INCLUDE_REGEXP)
       unless match_data
         output_lines.push(input_line)
         next
       end
-      treatment = case match_data[1]
+      treatment = match_data[1]
+      relative_included_file_path = match_data[2]
+      treatment = case treatment
                     when ':code_block'
                       :code_block
                     when ':verbatim'
@@ -138,28 +124,46 @@ EOT
                     when ':comment'
                       :comment
                     else
-                      match_data[1]
+                      treatment
                   end
-      relative_file_path = match_data[2]
-      include_file_path = File.join(
-          File.dirname(template_file_path),
-          relative_file_path,
+      new_inclusion = Inclusion.new(
+          includer_file_path,
+          includer_line_number = line_index + 1,
+          relative_included_file_path
       )
-      output_lines.push(comment(" >>>>>> BEGIN INCLUDED FILE (#{treatment}): SOURCE #{include_file_path} ")) unless pristine
-      include_lines = File.readlines(include_file_path)
+      included_real_path = new_inclusion.included_real_path
+      if treatment == :verbatim
+        previously_included = verbatim_inclusions.include?(new_inclusion.included_real_path)
+        if previously_included
+          backtrace = verbatim_inclusions.values.push(new_inclusion)
+          message_lines = ['Includes are circular:']
+          backtrace.each_with_index do |inclusion, i|
+            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}")
+            message_lines.push("    Included file path: #{inclusion.included_file_path}")
+            message_lines.push("    Real file_path: #{inclusion.included_real_path}")
+          end
+          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)
       unless include_lines.last.match("\n")
-        message = "Warning:  Included file has no trailing newline: #{include_file_path}"
+        message = "Warning:  Included file has no trailing newline: #{relative_included_file_path}"
         warn(message)
       end
       case treatment
         when :verbatim
           # Pass through unadorned, but honor any nested includes.
-          include_files(include_file_path, include_lines, output_lines, paths, realpaths)
+          include_files(new_inclusion.included_file_path, include_lines, output_lines, verbatim_inclusions)
         when :comment
           output_lines.push(comment(include_lines.join('')))
         else
           # Use the file name as a label.
-          file_name_line = format("<code>%s</code>\n", File.basename(include_file_path))
+          file_name_line = format("<code>%s</code>\n", File.basename(relative_included_file_path))
           output_lines.push(file_name_line)
           # Put into code block.
           language = treatment == :code_block ? '' : treatment
@@ -167,48 +171,77 @@ EOT
           output_lines.push(*include_lines)
           output_lines.push("```\n")
       end
-      output_lines.push(comment(" <<<<<< END INCLUDED FILE (#{treatment}): SOURCE #{include_file_path} ")) unless pristine
+      output_lines.push(comment(" <<<<<< END INCLUDED FILE (#{treatment}): SOURCE #{new_inclusion.included_file_path} ")) unless pristine
     end
   end
 
   def resolve_images(input_lines, output_lines)
-  input_lines.each do |input_line|
-    scan_data = input_line.scan(IMAGE_REGEXP)
-    if scan_data.empty?
-      output_lines.push(input_line)
-      next
-    end
-    output_lines.push(comment(" >>>>>> BEGIN RESOLVED IMAGES: INPUT-LINE '#{input_line}' ")) unless pristine
-    output_line = input_line
-    scan_data.each do |alt_text, path_and_attributes|
-      relative_file_path, attributes_s =path_and_attributes.split(/\s?\|\s?/, 2)
-      attributes = attributes_s ? attributes_s.split(/\s+/) : []
-      formatted_attributes = ['']
-      attributes.each do |attribute|
-        name, value = attribute.split('=', 2)
-        formatted_attributes.push(format('%s="%s"', name, value))
+    input_lines.each do |input_line|
+      scan_data = input_line.scan(IMAGE_REGEXP)
+      if scan_data.empty?
+        output_lines.push(input_line)
+        next
       end
-      formatted_attributes_s = formatted_attributes.join(' ')
-      repo_user, repo_name = repo_user_and_name
-      if relative_file_path.start_with?('http')
-        absolute_file_path = relative_file_path
-      else
-        absolute_file_path = File.join(
-            "https://raw.githubusercontent.com/#{repo_user}/#{repo_name}/master",
-            relative_file_path,
+      output_lines.push(comment(" >>>>>> BEGIN RESOLVED IMAGES: INPUT-LINE '#{input_line}' ")) unless pristine
+      output_line = input_line
+      scan_data.each do |alt_text, path_and_attributes|
+        relative_file_path, attributes_s =path_and_attributes.split(/\s?\|\s?/, 2)
+        attributes = attributes_s ? attributes_s.split(/\s+/) : []
+        formatted_attributes = ['']
+        attributes.each do |attribute|
+          name, value = attribute.split('=', 2)
+          formatted_attributes.push(format('%s="%s"', name, value))
+        end
+        formatted_attributes_s = formatted_attributes.join(' ')
+        repo_user, repo_name = repo_user_and_name
+        if relative_file_path.start_with?('http')
+          absolute_file_path = relative_file_path
+        else
+          absolute_file_path = File.join(
+              "https://raw.githubusercontent.com/#{repo_user}/#{repo_name}/master",
+              relative_file_path,
+          )
+        end
+        img_element = format(
+            '<img src="%s" alt="%s"%s>',
+            absolute_file_path,
+            alt_text,
+            formatted_attributes_s,
         )
+        output_line = output_line.sub(IMAGE_REGEXP, img_element)
       end
-      img_element = format(
-          '<img src="%s" alt="%s"%s>',
-          absolute_file_path,
-          alt_text,
-          formatted_attributes_s,
-      )
-      output_line = output_line.sub(IMAGE_REGEXP, img_element)
+      output_lines.push(output_line)
+      output_lines.push(comment(" <<<<<< END RESOLVED IMAGES: INPUT-LINE '#{input_line}' ")) unless pristine
     end
-    output_lines.push(output_line)
-    output_lines.push(comment(" <<<<<< END RESOLVED IMAGES: INPUT-LINE '#{input_line}' ")) unless pristine
+
   end
+
+  class Inclusion
+
+    attr_accessor \
+      :includer_file_path,
+      :includer_line_number,
+      :relative_included_file_path,
+      :included_file_path,
+      :included_real_path
+
+    def initialize(
+        includer_file_path,
+        includer_line_number,
+        relative_included_file_path
+    )
+      included_file_path = File.join(
+          File.dirname(includer_file_path),
+          relative_included_file_path,
+      )
+      self.includer_file_path = includer_file_path
+      self.includer_line_number = includer_line_number
+      self.relative_included_file_path = relative_included_file_path
+      self.included_file_path = included_file_path
+      self.included_real_path = Pathname.new(included_file_path).realpath.to_s
+    end
+
   end
 
 end
+

data/lib/markdown_helper/version.rb

@@ -1,3 +1,3 @@
 class MarkdownHelper
-  VERSION = '1.5.1'
+  VERSION = '1.6.0'
 end

data/{readme_files → markdown}/README.template.md

@@ -1,10 +1,13 @@
 # Markdown Helper
 
-![Gem Version](https://badge.fury.io/rb/markdown_helper.svg)
+![Gem Version](https://badge.fury.io/rb/markdown_helper.svg) [Visit gem markdown_helper](https://rubygems.org/gems/markdown_helper)
 
 ## What's New?
 
-Nested file inclusion is now supported, which means that an included file can include more files.  This applies only to a file included verbatim, not to a file included as a code block or as a markdown comment.
+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```
 
 ## What's This?
 

data/markdown/highlighted_ruby.md

@@ -0,0 +1,12 @@
+<!-- >>>>>> 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/reusable_text/build.rb

@@ -0,0 +1,67 @@
+reusable_text_file_name = 'reusable_text.md'
+includer_file_name = 'includer.md'
+included_file_name = 'included.md'
+template_file_name = 'template.md'
+use_case_file_name = 'use_case.md'
+
+include_command = "ruby ../../../bin/include --pristine #{includer_file_name} #{included_file_name}"
+build_command = "ruby ../../../bin/include --pristine #{template_file_name} #{use_case_file_name}"
+
+template = <<EOT
+### Reusable 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.
+
+#### Separate File
+
+Here's a file containing some text that can be included in more than one place:
+
+@[:code_block](#{reusable_text_file_name})
+
+#### Template 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}
+```
+
+#### Included File
+
+Here's the finished file with the inclusion:
+
+@[:code_block](#{included_file_name})
+EOT
+
+reusable_text = <<EOT
+This is some useful text that can be included in more than one place (actually, in more than one file).
+EOT
+
+includer = <<EOT
+This file includes the useful text.
+
+@[:verbatim](#{reusable_text_file_name})
+EOT
+
+# Write markdown files.
+{
+  template_file_name => template,
+  reusable_text_file_name => reusable_text,
+  includer_file_name => includer,
+}.each_pair do |file_name, text|
+  File.write(file_name, text)
+end
+
+# Perform the inclusion.
+system(include_command)
+
+# Build the use case.
+system(build_command)

data/markdown/use_cases/reusable_text/included.md

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

data/markdown/use_cases/reusable_text/includer.md

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

data/markdown/use_cases/reusable_text/reusable_text.md

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

data/markdown/use_cases/reusable_text/template.md

@@ -0,0 +1,31 @@
+### Reusable 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.
+
+#### Separate File
+
+Here's a file containing some text that can be included in more than one place:
+
+@[:code_block](reusable_text.md)
+
+#### Template File
+
+Here's a template file that includes it:
+
+@[:code_block](includer.md)
+
+#### Command
+
+Here's the command to perform the inclusion (```--pristine``` suppresses inclusion comments):
+
+```sh
+ruby ../../../bin/include --pristine includer.md included.md
+```
+
+#### Included File
+
+Here's the finished file with the inclusion:
+
+@[:code_block](included.md)

data/markdown/use_cases/reusable_text/use_case.md

@@ -0,0 +1,44 @@
+### Reusable 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.
+
+#### Separate File
+
+Here's a file containing some text that can be included in more than one place:
+
+<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).
+```
+
+#### Template 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
+ruby ../../../bin/include --pristine includer.md included.md
+```
+
+#### Included File
+
+Here's the finished file with the inclusion:
+
+<code>included.md</code>
+```
+This file includes the useful text.
+
+This is some useful text that can be included in more than one place (actually, in more than one file).
+```

data/markdown_helper.gemspec

@@ -8,7 +8,6 @@ Gem::Specification.new do |spec|
   spec.version       = MarkdownHelper::VERSION
   spec.authors       = ['burdettelamar']
   spec.email         = ['BurdetteLamar@Yahoo.com']
-
   spec.summary       = 'Class to help with GitHub markdown.'
   spec.description   = <<-EOT
 Class to help with GitHub markdown:
@@ -33,8 +32,8 @@ EOT
   spec.files         = `git ls-files -z`.split("\x0").reject do |f|
     f.match(%r{^(test|spec|features)/})
   end
-  spec.bindir        = 'exe'
-  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.bindir        = 'bin'
+  spec.executables   = ['markdown_helper']
   spec.require_paths = ['lib']
 
   spec.add_development_dependency 'bundler', '~> 1.14'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: markdown_helper
 version: !ruby/object:Gem::Version
-  version: 1.5.1
+  version: 1.6.0
 platform: ruby
 authors:
 - burdettelamar
 autorequire: 
-bindir: exe
+bindir: bin
 cert_chain: []
-date: 2018-04-08 00:00:00.000000000 Z
+date: 2018-04-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -74,7 +74,8 @@ description: |
   * Image attributes
 email:
 - BurdetteLamar@Yahoo.com
-executables: []
+executables:
+- markdown_helper
 extensions: []
 extra_rdoc_files: []
 files:
@@ -88,8 +89,11 @@ files:
 - README.md
 - Rakefile
 - _config.yml
+- bin/_include
+- bin/_resolve
 - bin/console
 - bin/include
+- bin/markdown_helper
 - bin/resolve
 - bin/setup
 - bin/usage/include.txt
@@ -99,22 +103,27 @@ 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/use_cases/evergreen_examples.md
+- markdown/use_cases/generated_text.md
+- markdown/use_cases/image_attributes.md
+- markdown/use_cases/reusable_text/build.rb
+- markdown/use_cases/reusable_text/included.md
+- markdown/use_cases/reusable_text/includer.md
+- markdown/use_cases/reusable_text/reusable_text.md
+- markdown/use_cases/reusable_text/template.md
+- markdown/use_cases/reusable_text/use_case.md
+- markdown/use_cases/rubygem_images.md
+- markdown/verbatim_ruby_template.md
 - markdown_helper.gemspec
-- readme_files/README.template.md
-- readme_files/code_block_ruby_template.md
-- readme_files/highlight_ruby_template.md
-- readme_files/highlighted_ruby.md
-- readme_files/include.md
-- readme_files/include.rb
-- readme_files/include_usage.rb
-- readme_files/resolve.md
-- readme_files/resolve_usage.rb
-- readme_files/use_cases/evergreen_examples.md
-- readme_files/use_cases/generated_text.md
-- readme_files/use_cases/image_attributes.md
-- readme_files/use_cases/reusable_text.md
-- readme_files/use_cases/rubygem_images.md
-- readme_files/verbatim_ruby_template.md
 homepage: https://github.com/BurdetteLamar/markdown_helper
 licenses:
 - MIT

data/readme_files/highlighted_ruby.md

@@ -1,12 +0,0 @@
-<!-- >>>>>> BEGIN GENERATED FILE (include): SOURCE readme_files/highlight_ruby_template.md -->
-<!-- >>>>>> BEGIN INCLUDED FILE (ruby): SOURCE readme_files/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 readme_files/include.rb -->
-<!-- <<<<<< END GENERATED FILE (include): SOURCE readme_files/highlight_ruby_template.md -->

data/readme_files/use_cases/reusable_text.md

@@ -1,7 +0,0 @@
-### Reusable Text
-
-Use the markdown helper to stay DRY (Don't Repeat Yourself).
-
-Text that will be needed in more than one place in the documentation can be maintained in a separate file, then included wherever it's needed.
-
-Note that the included text may itself be markdown, which can be included verbatim, or it may be code or other example data, which can be included into a code block.