markdown_helper 0.2.2 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d13b25bca8211a7b125220f43823d929aa063f18
-  data.tar.gz: 5abf171a884b8a945bd5a53b3c20db59eda73079
+  metadata.gz: f09669b50665a49012e58c114423d8cadbabdd78
+  data.tar.gz: 5e7efd7f10b45d9e55800be245016d8c221451ba
 SHA512:
-  metadata.gz: d806efe553b5be7c0b029f1010f51a714d92399cd55e42ff54ccf8361cefa5f4daa7614ecfc4ec034aca729dd7248378de2288652947a30e6feda5dd762df865
-  data.tar.gz: c27d30e13ac8eb24b5c95b857c103c3b1c0dfe9c7907c68ecbf47b442b6622173d6ae4d05786821d3a0fb0d182cae09db83b79683b3c69e6886b584ef63c26cd
+  metadata.gz: 97c756477a554d5b64800c58154a329512817134004a72ea8daa458190ca13332b93844b4810fcbf41b77f85ac5af3991a03d39b39b7053d6aa723aa6ff2217c
+  data.tar.gz: 5ddf37cb2ab123d4cc24d6aa60f1a45fea125774cb608e06cb2e8a8138b3e9a923d95c2f953586130ac8ecc971ca525de449c8a3088b0959d2c701d3791ab598

data/.gitignore

@@ -7,3 +7,5 @@
 /pkg/
 /spec/reports/
 /tmp/
+/test/tmp/
+

data/Gemfile.lock

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

data/README.md

@@ -1,3 +1,5 @@
+<!-- >>>>>> BEGIN GENERATED FILE (include): SOURCE readme_files/temp_resolved.md -->
+<!-- >>>>>> BEGIN GENERATED FILE (resolve): SOURCE readme_files/README.template.md -->
 # MarkdownHelper
 
 [![Gem Version](https://badge.fury.io/rb/markdown_helper.svg)](https://badge.fury.io/rb/markdown_helper)
@@ -12,9 +14,26 @@ 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 
 
+<!-- >>>>>> BEGIN RESOLVED IMAGE: DESCRIPTION '![include_icon](images/include.png | width=50)
+' -->
 <img src="https://raw.githubusercontent.com/BurdetteLamar/MarkdownHelper/master/images/include.png" alt="include_icon" width="50">
+<!-- <<<<<< END RESOLVED IMAGE: DESCRIPTION '![include_icon](images/include.png | width=50)
+' -->
 
 This markdown helper enables file inclusion in GitHub markdown.
 
@@ -26,6 +45,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 -->
 <code>include.rb</code>
 ```ruby
 class RubyCode
@@ -34,9 +54,11 @@ class RubyCode
   end
 end
 ```
+<!-- <<<<<< END INCLUDED FILE (ruby): SOURCE readme_files/include.rb -->
 
 #### Plain Code Block
 
+<!-- >>>>>> BEGIN INCLUDED FILE (code_block): SOURCE readme_files/include.rb -->
 <code>include.rb</code>
 ```
 class RubyCode
@@ -45,9 +67,14 @@ class RubyCode
   end
 end
 ```
+<!-- <<<<<< END INCLUDED FILE (code_block): SOURCE readme_files/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.
@@ -56,12 +83,13 @@ Verbatim text is included unadorned.  Most often, verbatim text is markdown to b
 
 #### CLI
 
+<!-- >>>>>> BEGIN INCLUDED FILE (code_block): SOURCE readme_files/../bin/usage/include.txt -->
 <code>include.txt</code>
 ```
-Usage:
-
-  include template_file_path markdown_file_page
-
+Usage: bin/include [options] template_file_path markdown_file_page
+        --pristine                   No comments added
+        --help                       Display help
+    
   where
 
     * template_file_path is the path to an existing file.
@@ -70,24 +98,33 @@ Usage:
   Typically:
 
     * Both file types are .md.
-    * The template file contains file inclusion pragmas.  See README.md.
+    * The template file contains file inclusion descriptions.
 ```
+<!-- <<<<<< END INCLUDED FILE (code_block): SOURCE readme_files/../bin/usage/include.txt -->
 
 #### API
 
+<!-- >>>>>> BEGIN INCLUDED FILE (ruby): SOURCE readme_files/include_usage.rb -->
 <code>include_usage.rb</code>
 ```ruby
 require 'markdown_helper'
 
-markdown_helper = MarkdownHelper.new
 template_file_path = 'highlight_ruby_template.md'
 markdown_file_path = 'highlighted_ruby.md'
+markdown_helper = MarkdownHelper.new
+markdown_helper.include(template_file_path, markdown_file_path)
+# Pristine.
+markdown_helper.pristine = true
+markdown_helper.include(template_file_path, markdown_file_path)
+# Also pristine.
+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 -->
 
 #### 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>
 
@@ -101,6 +138,7 @@ where:
 
 ##### Example Include Descriptions
 
+<!-- >>>>>> BEGIN INCLUDED FILE (code_block): SOURCE readme_files/include.md -->
 <code>include.md</code>
 ```code_block
 @[ruby](my_ruby.rb)
@@ -109,10 +147,15 @@ where:
 
 @[:verbatim](my_markdown.md)
 ```
+<!-- <<<<<< END INCLUDED FILE (code_block): SOURCE readme_files/include.md -->
 
 ## Image Path Resolution 
 
+<!-- >>>>>> BEGIN RESOLVED IMAGE: DESCRIPTION '![image_icon](images/image.png | width=50)
+' -->
 <img src="https://raw.githubusercontent.com/BurdetteLamar/MarkdownHelper/master/images/image.png" alt="image_icon" width="50">
+<!-- <<<<<< END RESOLVED IMAGE: DESCRIPTION '![image_icon](images/image.png | width=50)
+' -->
 
 This markdown helper enables image path resolution in GitHub markdown.
 
@@ -126,12 +169,13 @@ This matters because when markdown becomes part of a Ruby gem, its images will h
 
 #### CLI
 
-<code>resolve_image_urls.txt</code>
+<!-- >>>>>> BEGIN INCLUDED FILE (code_block): SOURCE readme_files/../bin/usage/resolve.txt -->
+<code>resolve.txt</code>
 ```
-Usage:
-
-  resolve_image_urls template_file_path markdown_file_page
-
+Usage: bin/resolve [options] template_file_path markdown_file_page
+        --pristine                   No comments added
+        --help                       Display help
+    
   where
 
     * template_file_path is the path to an existing file.
@@ -140,24 +184,33 @@ Usage:
   Typically:
 
     * Both file types are .md.
-    * The template file contains image relative file paths.  See README.md.
+    * The template file contains image descriptions.
 ```
+<!-- <<<<<< END INCLUDED FILE (code_block): SOURCE readme_files/../bin/usage/resolve.txt -->
 
 #### API
 
-<code>resolve_image_urls_usage.rb</code>
+<!-- >>>>>> BEGIN INCLUDED FILE (ruby): SOURCE readme_files/resolve_usage.rb -->
+<code>resolve_usage.rb</code>
 ```ruby
 require 'markdown_helper'
 
-markdown_helper = MarkdownHelper.new
 template_file_path = 'template.md'
 markdown_file_path = 'markdown.md'
-markdown_helper.resolve_image_urls(template_file_path, markdown_file_path)
+markdown_helper = MarkdownHelper.new
+markdown_helper.resolve(template_file_path, markdown_file_path)
+# Pristine.
+markdown_helper.pristine = true
+markdown_helper.resolve(template_file_path, markdown_file_path)
+# Also pristine.
+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 -->
 
 #### 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>
 
@@ -169,18 +222,24 @@ where:
 
 ##### Example Image Descriptions
 
-<code>resolve_image_urls.md</code>
+<!-- >>>>>> BEGIN INCLUDED FILE (code_block): SOURCE readme_files/resolve.md -->
+<code>resolve.md</code>
 ```code_block
- ![my_alt](image/image.png)
+![my_alt](image/image.png)
 
- ![my_alt](image/image.png | width=50)
+![my_alt](image/image.png | width=50)
 
- ![my_alt](image/image.png| width=50 height=50)
+![my_alt](image/image.png| width=50 height=50)
 ```
+<!-- <<<<<< END INCLUDED FILE (code_block): SOURCE readme_files/resolve.md -->
 
 ## Image Attributes
 
+<!-- >>>>>> BEGIN RESOLVED IMAGE: DESCRIPTION '![html_icon](images/html.png | width=50)
+' -->
 <img src="https://raw.githubusercontent.com/BurdetteLamar/MarkdownHelper/master/images/html.png" alt="html_icon" width="50">
+<!-- <<<<<< END RESOLVED IMAGE: DESCRIPTION '![html_icon](images/html.png | width=50)
+' -->
 
 This markdown helper enables HTML image attributes in GitHub markdown [image descriptions](https://github.github.com/gfm/#image-description).
 
@@ -192,12 +251,13 @@ Use the markdown helper to add image attributes in a markdown (</code>.md</code>
 
 #### CLI
 
-<code>resolve_image_urls.txt</code>
+<!-- >>>>>> BEGIN INCLUDED FILE (code_block): SOURCE readme_files/../bin/usage/resolve.txt -->
+<code>resolve.txt</code>
 ```
-Usage:
-
-  resolve_image_urls template_file_path markdown_file_page
-
+Usage: bin/resolve [options] template_file_path markdown_file_page
+        --pristine                   No comments added
+        --help                       Display help
+    
   where
 
     * template_file_path is the path to an existing file.
@@ -206,24 +266,33 @@ Usage:
   Typically:
 
     * Both file types are .md.
-    * The template file contains image relative file paths.  See README.md.
+    * The template file contains image descriptions.
 ```
+<!-- <<<<<< END INCLUDED FILE (code_block): SOURCE readme_files/../bin/usage/resolve.txt -->
 
 #### API
 
-<code>resolve_image_urls_usage.rb</code>
+<!-- >>>>>> BEGIN INCLUDED FILE (ruby): SOURCE readme_files/resolve_usage.rb -->
+<code>resolve_usage.rb</code>
 ```ruby
 require 'markdown_helper'
 
-markdown_helper = MarkdownHelper.new
 template_file_path = 'template.md'
 markdown_file_path = 'markdown.md'
-markdown_helper.resolve_image_urls(template_file_path, markdown_file_path)
+markdown_helper = MarkdownHelper.new
+markdown_helper.resolve(template_file_path, markdown_file_path)
+# Pristine.
+markdown_helper.pristine = true
+markdown_helper.resolve(template_file_path, markdown_file_path)
+# Also pristine.
+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 -->
 
 #### 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>
 
@@ -235,12 +304,16 @@ where:
 
 ##### Example Image Descriptions
 
-<code>resolve_image_urls.md</code>
+<!-- >>>>>> BEGIN INCLUDED FILE (code_block): SOURCE readme_files/resolve.md -->
+<code>resolve.md</code>
 ```code_block
- ![my_alt](image/image.png)
+![my_alt](image/image.png)
 
- ![my_alt](image/image.png | width=50)
+![my_alt](image/image.png | width=50)
 
- ![my_alt](image/image.png| width=50 height=50)
+![my_alt](image/image.png| width=50 height=50)
 ```
+<!-- <<<<<< END INCLUDED FILE (code_block): SOURCE readme_files/resolve.md -->
 
+<!-- <<<<<< END GENERATED FILE (resolve): SOURCE readme_files/README.template.md -->
+<!-- <<<<<< END GENERATED FILE (include): SOURCE readme_files/temp_resolved.md -->

data/Rakefile

@@ -11,11 +11,31 @@ namespace :build do
 
   desc 'Build README.md file from README.template.md'
   task :readme do
+    Rake::Task['build:usages'].invoke
     require_relative 'lib/markdown_helper'
     markdown_helper = MarkdownHelper.new
     markdown_helper.include('readme_files/highlight_ruby_template.md', 'readme_files/highlighted_ruby.md')
-    markdown_helper.include('readme_files/README.template.md', 'README.md')
-    markdown_helper.resolve_image_urls('README.md', 'README.md')
+    # Do the resolve before the include, so that the included text is not also resolved.
+    # Thie 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)
+    markdown_helper.include(temp_file_path, 'README.md')
+    File.delete(temp_file_path)
+  end
+
+  desc 'Build usage for executables'
+  task :usages do
+    %w/
+        include
+        resolve
+    /.each do |executable_name|
+      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)
+      end
+    end
   end
 
 end

data/bin/include

@@ -1,23 +1,44 @@
 #!/usr/bin/env ruby
 
+require 'optparse'
+
 require 'markdown_helper'
 
-def usage
-  dir_path = File.dirname(File.absolute_path(__FILE__))
-  file_path = File.join(
-                      dir_path,
-                      'usage',
-                      'include.txt'
-  )
-  puts File.read(file_path)
+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 |_|
+    options[:pristine] = true
+  end
+  opts.on('--help', 'Display help') do
+    usage(opts)
+  end
+end
+
+def usage(opts)
+  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
 
-template_file_path, markdown_file_path = ARGV
+parser.parse!
 
-usage unless ARGV.size == 2
-usage unless File.readable?(template_file_path)
-usage unless File.writable?(File.dirname(markdown_file_path))
+template_file_path, markdown_file_path = ARGV
 
-MarkdownHelper.new.include(template_file_path, markdown_file_path)
+usage(options) unless ARGV.size == 2
+usage(options) unless File.readable?(template_file_path)
+usage(options) unless File.writable?(File.dirname(markdown_file_path))
 
+MarkdownHelper.new(options).include(template_file_path, markdown_file_path)

data/bin/resolve

@@ -0,0 +1,44 @@
+#!/usr/bin/env ruby
+
+require 'optparse'
+
+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 |_|
+    options[:pristine] = true
+  end
+  opts.on('--help', 'Display help') do
+    usage(opts)
+  end
+end
+
+def usage(opts)
+  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(options) unless ARGV.size == 2
+usage(options) unless File.readable?(template_file_path)
+usage(options) unless File.writable?(File.dirname(markdown_file_path))
+
+MarkdownHelper.new(options).resolve(template_file_path, markdown_file_path)

data/bin/usage/include.txt

@@ -1,7 +1,7 @@
-Usage:
-
-  include template_file_path markdown_file_page
-
+Usage: bin/include [options] template_file_path markdown_file_page
+        --pristine                   No comments added
+        --help                       Display help
+    
   where
 
     * template_file_path is the path to an existing file.
@@ -10,4 +10,4 @@ Usage:
   Typically:
 
     * Both file types are .md.
-    * The template file contains file inclusion pragmas.  See README.md.
+    * The template file contains file inclusion descriptions.

data/bin/usage/resolve.txt

@@ -0,0 +1,13 @@
+Usage: bin/resolve [options] template_file_path markdown_file_page
+        --pristine                   No comments added
+        --help                       Display help
+    
+  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.

data/images_resolved.md

@@ -72,11 +72,11 @@ This matters because when markdown becomes part of a Ruby gem, its images will h
 
 #### 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 Pragmas
 
@@ -92,5 +92,5 @@ where:
 
 ##### Example Image Pragmas
 
-@[code_block](resolve_image_urls.md)
+@[code_block](resolve.md)
 

data/lib/markdown_helper.rb

@@ -9,6 +9,23 @@ class MarkdownHelper
   IMAGE_REGEXP = /^!\[([^\[]+)\]\(([^)]+)\)/
   INCLUDE_REGEXP = /^@\[([^\[]+)\]\(([^)]+)\)/
 
+  attr_accessor :pristine
+
+  def initialize(options = {})
+    default_options = {
+        :pristine => false,
+    }
+    merged_options = default_options.merge(options)
+    merged_options.each_pair do |method, value|
+      unless self.respond_to?(method)
+        raise ArgumentError.new("Unknown option: #{method}")
+      end
+      setter_method = "#{method}="
+      send(setter_method, value)
+      merged_options.delete(method)
+    end
+  end
+
   # Get the user name and repository name from ENV.
   def repo_user_and_name
     repo_user = ENV['REPO_USER']
@@ -34,9 +51,8 @@ class MarkdownHelper
   # @example pragma to include text verbatim, to be rendered as markdown.
   #   @[:verbatim](foo.md)
   def include(template_file_path, markdown_file_path)
-    output_lines = []
-    File.open(template_file_path, 'r') do |template_file|
-      template_file.each_line do |input_line|
+    output = send(:generate_file, template_file_path, markdown_file_path, __method__) do |input_lines, output_lines|
+      input_lines.each do |input_line|
         match_data = input_line.match(INCLUDE_REGEXP)
         unless match_data
           output_lines.push(input_line)
@@ -47,6 +63,8 @@ class MarkdownHelper
                         :code_block
                       when ':verbatim'
                         :verbatim
+                      when ':comment'
+                        :comment
                       else
                         match_data[1]
                     end
@@ -55,30 +73,9 @@ class MarkdownHelper
             File.dirname(template_file_path),
             relative_file_path,
         )
-        included_text = File.read(include_file_path)
-        unless included_text.match("\n")
-          message = "Warning:  Included file has no trailing newline: #{include_file_path}"
-          warn(message)
-        end
-        if treatment == :verbatim
-          # Pass through unadorned.
-          output_lines.push(included_text)
-        else
-          # Use the file name as a label.
-          file_name_line = format("<code>%s</code>\n", File.basename(include_file_path))
-          output_lines.push(file_name_line)
-          # Put into code block.
-          language = treatment == :code_block ? '' : treatment
-          output_lines.push("```#{language}\n")
-          output_lines.push(included_text)
-          output_lines.push("```\n")
-        end
+        send(:include_file, include_file_path, treatment, output_lines)
       end
     end
-    output = output_lines.join('')
-    File.open(markdown_file_path, 'w') do |md_file|
-      md_file.write(output)
-    end
     output
   end
 
@@ -103,34 +100,65 @@ class MarkdownHelper
   #       "https://raw.githubusercontent.com/#{repo_user}/#{repo_name}/master",
   #       relative_file_path,
   #   )
-  def resolve_image_urls(template_file_path, markdown_file_path)
-    output_lines = []
-    File.open(template_file_path, 'r') do |template_file|
-      output_lines = []
-      template_file.each_line do |input_line|
+  def resolve(template_file_path, markdown_file_path)
+    # Method :generate_file does the first things, yields the block, does the last things.
+    output = send(:generate_file, template_file_path, markdown_file_path, __method__) do |input_lines, output_lines|
+      input_lines.each do |input_line|
         match_data = input_line.match(IMAGE_REGEXP)
         unless match_data
           output_lines.push(input_line)
           next
         end
-        alt_text = match_data[1]
-        relative_file_path, attributes_s = match_data[2].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))
+        send(:comment_resolve, input_line, output_lines) do
+          alt_text = match_data[1]
+          relative_file_path, attributes_s = match_data[2].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
+          absolute_file_path = nil
+          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
+          following_text = input_line.sub(IMAGE_REGEXP, '').chomp
+          line = format(
+              '<img src="%s" alt="%s"%s>%s',
+              absolute_file_path,
+              alt_text,
+              formatted_attributes_s,
+              following_text
+          ) + "\n"
+          output_lines.push(line)
         end
-        formatted_attributes_s = formatted_attributes.join(' ')
-        repo_user, repo_name = repo_user_and_name
-        absolute_file_path = File.join(
-            "https://raw.githubusercontent.com/#{repo_user}/#{repo_name}/master",
-            relative_file_path,
-        )
-        line = format('<img src="%s" alt="%s"%s>', absolute_file_path, alt_text, formatted_attributes_s) + "\n"
-        output_lines.push(line)
       end
     end
+    output
+  end
+  alias resolve_image_urls resolve
+
+  def comment(text)
+    "<!--#{text}-->\n"
+  end
+
+  private
+
+  def generate_file(template_file_path, markdown_file_path, method)
+    output_lines = []
+    File.open(template_file_path, 'r') do |template_file|
+      output_lines.push(comment(" >>>>>> BEGIN GENERATED FILE (#{method.to_s}): SOURCE #{template_file_path} ")) unless pristine
+      input_lines = template_file.readlines
+      yield input_lines, output_lines
+      output_lines.push(comment(" <<<<<< END GENERATED FILE (#{method.to_s}): SOURCE #{template_file_path} ")) unless pristine
+    end
     output = output_lines.join('')
     File.open(markdown_file_path, 'w') do |md_file|
       md_file.write(output)
@@ -138,4 +166,37 @@ class MarkdownHelper
     output
   end
 
+  def include_file(include_file_path, treatment, output_lines)
+    include_file = File.new(include_file_path, 'r')
+    output_lines.push(comment(" >>>>>> BEGIN INCLUDED FILE (#{treatment}): SOURCE #{include_file.path} ")) unless pristine
+    included_text = include_file.read
+    unless included_text.match("\n")
+      message = "Warning:  Included file has no trailing newline: #{include_file_path}"
+      warn(message)
+    end
+    case treatment
+      when :verbatim
+        # Pass through unadorned.
+        output_lines.push(included_text)
+      when :comment
+        output_lines.push(comment(included_text))
+      else
+        # Use the file name as a label.
+        file_name_line = format("<code>%s</code>\n", File.basename(include_file_path))
+        output_lines.push(file_name_line)
+        # Put into code block.
+        language = treatment == :code_block ? '' : treatment
+        output_lines.push("```#{language}\n")
+        output_lines.push(included_text)
+        output_lines.push("```\n")
+    end
+    output_lines.push(comment(" <<<<<< END INCLUDED FILE (#{treatment}): SOURCE #{include_file.path} ")) unless pristine
+  end
+
+  def comment_resolve(description, output_lines)
+    output_lines.push(comment(" >>>>>> BEGIN RESOLVED IMAGE: DESCRIPTION '#{description}' ")) unless pristine
+    yield
+    output_lines.push(comment(" <<<<<< END RESOLVED IMAGE: DESCRIPTION '#{description}' ")) unless pristine
+  end
+
 end

data/lib/markdown_helper/version.rb

@@ -1,3 +1,3 @@
 class MarkdownHelper
-  VERSION = '0.2.2'
+  VERSION = '0.2.3'
 end

data/readme_files/README.template.md

@@ -12,6 +12,19 @@ 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)
@@ -34,6 +47,10 @@ Use the markdown helper to merge external files into a markdown (</code>.md</cod
 
 [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.
@@ -50,7 +67,7 @@ Verbatim text is included unadorned.  Most often, verbatim text is markdown to b
 
 #### 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>
 
@@ -82,15 +99,15 @@ This matters because when markdown becomes part of a Ruby gem, its images will h
 
 #### 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>
 
@@ -102,7 +119,7 @@ where:
 
 ##### Example Image Descriptions
 
-@[code_block](resolve_image_urls.md)
+@[code_block](resolve.md)
 
 ## Image Attributes
 
@@ -118,15 +135,15 @@ Use the markdown helper to add image attributes in a markdown (</code>.md</code>
 
 #### 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>
 
@@ -138,5 +155,5 @@ where:
 
 ##### Example Image Descriptions
 
-@[code_block](resolve_image_urls.md)
+@[code_block](resolve.md)
 

data/readme_files/highlighted_ruby.md

@@ -1,3 +1,5 @@
+<!-- >>>>>> 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
@@ -6,3 +8,5 @@ class RubyCode
   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/include_usage.rb

@@ -1,6 +1,12 @@
 require 'markdown_helper'
 
-markdown_helper = MarkdownHelper.new
 template_file_path = 'highlight_ruby_template.md'
 markdown_file_path = 'highlighted_ruby.md'
+markdown_helper = MarkdownHelper.new
+markdown_helper.include(template_file_path, markdown_file_path)
+# Pristine.
+markdown_helper.pristine = true
+markdown_helper.include(template_file_path, markdown_file_path)
+# Also pristine.
+markdown_helper = MarkdownHelper.new(:pristine => true)
 markdown_helper.include(template_file_path, markdown_file_path)

data/readme_files/resolve.md

@@ -0,0 +1,5 @@
+![my_alt](image/image.png)
+
+![my_alt](image/image.png | width=50)
+
+![my_alt](image/image.png| width=50 height=50)

data/readme_files/resolve_usage.rb

@@ -0,0 +1,12 @@
+require 'markdown_helper'
+
+template_file_path = 'template.md'
+markdown_file_path = 'markdown.md'
+markdown_helper = MarkdownHelper.new
+markdown_helper.resolve(template_file_path, markdown_file_path)
+# Pristine.
+markdown_helper.pristine = true
+markdown_helper.resolve(template_file_path, markdown_file_path)
+# Also pristine.
+markdown_helper = MarkdownHelper.new(:pristine => true)
+markdown_helper.resolve(template_file_path, markdown_file_path)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: markdown_helper
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.2.3
 platform: ruby
 authors:
 - burdettelamar
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-03-10 00:00:00.000000000 Z
+date: 2018-03-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -89,10 +89,10 @@ files:
 - Rakefile
 - bin/console
 - bin/include
-- bin/resolve_image_urls
+- bin/resolve
 - bin/setup
 - bin/usage/include.txt
-- bin/usage/resolve_image_urls.txt
+- bin/usage/resolve.txt
 - images/html.png
 - images/image.png
 - images/include.png
@@ -107,8 +107,8 @@ files:
 - readme_files/include.md
 - readme_files/include.rb
 - readme_files/include_usage.rb
-- readme_files/resolve_image_urls.md
-- readme_files/resolve_image_urls_usage.rb
+- readme_files/resolve.md
+- readme_files/resolve_usage.rb
 - readme_files/verbatim_ruby_template.md
 homepage: https://github.com/BurdetteLamar/MarkdownHelper
 licenses:

data/bin/resolve_image_urls

@@ -1,22 +0,0 @@
-#!/usr/bin/env ruby
-
-require 'markdown_helper'
-
-def usage
-  dir_path = File.dirname(File.absolute_path(__FILE__))
-  file_path = File.join(
-                      dir_path,
-                      'usage',
-                      'resolve_image_urls.txt'
-  )
-  puts File.read(file_path)
-  exit
-end
-
-template_file_path, markdown_file_path = ARGV
-
-usage unless ARGV.size == 2
-usage unless File.readable?(template_file_path)
-usage unless File.writable?(File.dirname(markdown_file_path))
-
-MarkdownHelper.new.resolve_image_urls(template_file_path, markdown_file_path)

data/bin/usage/resolve_image_urls.txt

@@ -1,13 +0,0 @@
-Usage:
-
-  resolve_image_urls template_file_path markdown_file_page
-
-  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 relative file paths.  See README.md.

data/readme_files/resolve_image_urls.md

@@ -1,5 +0,0 @@
- ![my_alt](image/image.png)
-
- ![my_alt](image/image.png | width=50)
-
- ![my_alt](image/image.png| width=50 height=50)

data/readme_files/resolve_image_urls_usage.rb

@@ -1,6 +0,0 @@
-require 'markdown_helper'
-
-markdown_helper = MarkdownHelper.new
-template_file_path = 'template.md'
-markdown_file_path = 'markdown.md'
-markdown_helper.resolve_image_urls(template_file_path, markdown_file_path)