markdown_helper 1.0.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9350e847948120c0b6cd8da04deb1eb77a915631
-  data.tar.gz: f5eb9065d158d45ee87d0f4cb0e9e9e74529c48c
+  metadata.gz: d1147c20c56afc8ddb67b90b57845d59d08488c7
+  data.tar.gz: 0d4e6f2363d0921cdc206adc4c7c8d30a654ac1a
 SHA512:
-  metadata.gz: e98b19de2d10445af71e05e271f73c0de7ea563c7d009e9870ab7783b3a8a20a33fae2463fc6ffa1ba841deda72df0edd97f1880352cf5e7fb7fed5e90073602
-  data.tar.gz: c7f039f5e9ec548b713c23c759a6e34918eec4f25f20b900375d002c0f3caaa76124972bbd4a25310a4a84814061811436634a784b933c58773b5eb2f469a08b
+  metadata.gz: ec0b3a986477b6c9780a31073855358880375d6ccef61d669fb5b55ed121d9327c536e46f6d7cdf075dec5129c7b4c3c4be200fd7d8afbed9c128f4a11f5f518
+  data.tar.gz: a172ff12521ec4e2363d17d89b3149f303242fe7c506e17b376ab9499e7912a980905fc0463bb1bc84262165a3bfcc7b6e1d008ccd8e53f35c63f9414b488c8f

data/Gemfile.lock

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

data/README.md

@@ -8,6 +8,10 @@
 <!-- <<<<<< END RESOLVED IMAGES: INPUT-LINE '![Gem Version](https://badge.fury.io/rb/markdown_helper.svg)
 ' -->
 
+## 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.
+
 ## What's This?
 
 Class <code>MarkdownHelper</code> supports:
@@ -18,11 +22,11 @@ Class <code>MarkdownHelper</code> supports:
 
 ## How It Works
 
-The markdown helper reads a markdown document (template) and writes another markdown document.
+The markdown helper is a preprocessor that reads a markdown document (template) and writes another markdown document.
 
 The template can contain certain instructions that call for file inclusions and image resolutions.
 
-## Commented or Pristine?
+### Commented or Pristine?
 
 By default, the output markdown has added comments that show:
 
@@ -84,6 +88,8 @@ Comment text is written into the output between the comment delimiters <code>\<!
 
 Verbatim text is included unadorned.  Most often, verbatim text is markdown to be rendered as part of the markdown page.
 
+The verbatim text is itself scanned for nested includes.
+
 ### Usage
 
 #### CLI
@@ -91,7 +97,8 @@ Verbatim text is included unadorned.  Most often, verbatim text is markdown to b
 <!-- >>>>>> BEGIN INCLUDED FILE (code_block): SOURCE readme_files/../bin/usage/include.txt -->
 <code>include.txt</code>
 ```
-Usage: bin/include [options] template_file_path markdown_file_page
+
+Usage: include [options] template_file_path markdown_file_page
         --pristine                   No comments added
         --help                       Display help
     

data/bin/include

@@ -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_page"
+  _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,18 @@ 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))
+
+# 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)
 
-MarkdownHelper.new(options).include(template_file_path, markdown_file_path)

data/bin/usage/include.txt

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

data/lib/markdown_helper/version.rb

@@ -1,3 +1,3 @@
 class MarkdownHelper
-  VERSION = '1.0.0'
+  VERSION = '1.5.0'
 end

data/lib/markdown_helper.rb

@@ -1,3 +1,4 @@
+require 'pathname'
 require 'markdown_helper/version'
 
 # Helper class for working with GitHub markdown.
@@ -26,17 +27,6 @@ class MarkdownHelper
     end
   end
 
-  # Get the user name and repository name from ENV.
-  def repo_user_and_name
-    repo_user = ENV['REPO_USER']
-    repo_name = ENV['REPO_NAME']
-    unless repo_user and repo_name
-      message = 'ENV values for both REPO_USER and REPO_NAME must be defined.'
-      raise RuntimeError.new(message)
-    end
-    [repo_user, repo_name]
-  end
-
   # Merges external files into markdown text.
   # @param template_file_path [String] the path to the input template markdown file, usually containing include pragmas.
   # @param markdown_file_path [String] the path to the output merged markdown file.
@@ -52,29 +42,7 @@ class MarkdownHelper
   #   @[:verbatim](foo.md)
   def include(template_file_path, markdown_file_path)
     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)
-          next
-        end
-        treatment = case match_data[1]
-                      when ':code_block'
-                        :code_block
-                      when ':verbatim'
-                        :verbatim
-                      when ':comment'
-                        :comment
-                      else
-                        match_data[1]
-                    end
-        relative_file_path = match_data[2]
-        include_file_path = File.join(
-            File.dirname(template_file_path),
-            relative_file_path,
-        )
-        send(:include_file, include_file_path, treatment, output_lines)
-      end
+      send(:include_files, template_file_path, input_lines, output_lines, paths = [], realpaths = [])
     end
     output
   end
@@ -103,24 +71,27 @@ class MarkdownHelper
   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|
-        scan_data = input_line.scan(IMAGE_REGEXP)
-        if scan_data.empty?
-          output_lines.push(input_line)
-          next
-        end
-        send(:resolve_images, scan_data, input_line, output_lines)
-      end
+      send(:resolve_images, input_lines, output_lines)
     end
     output
   end
   alias resolve_image_urls resolve
 
+  private
+
   def comment(text)
     "<!--#{text}-->\n"
   end
 
-  private
+  def repo_user_and_name
+    repo_user = ENV['REPO_USER']
+    repo_name = ENV['REPO_NAME']
+    unless repo_user and repo_name
+      message = 'ENV values for both REPO_USER and REPO_NAME must be defined.'
+      raise RuntimeError.new(message)
+    end
+    [repo_user, repo_name]
+  end
 
   def generate_file(template_file_path, markdown_file_path, method)
     output_lines = []
@@ -137,65 +108,110 @@ 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)
+  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
-    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")
+    paths.push(template_file_path)
+    realpaths.push(realpath)
+
+    input_lines.each do |input_line|
+      match_data = input_line.match(INCLUDE_REGEXP)
+      unless match_data
+        output_lines.push(input_line)
+        next
+      end
+      treatment = case match_data[1]
+                    when ':code_block'
+                      :code_block
+                    when ':verbatim'
+                      :verbatim
+                    when ':comment'
+                      :comment
+                    else
+                      match_data[1]
+                  end
+      relative_file_path = match_data[2]
+      include_file_path = File.join(
+          File.dirname(template_file_path),
+          relative_file_path,
+      )
+      output_lines.push(comment(" >>>>>> BEGIN INCLUDED FILE (#{treatment}): SOURCE #{include_file_path} ")) unless pristine
+      include_lines = File.readlines(include_file_path)
+      unless include_lines.last.match("\n")
+        message = "Warning:  Included file has no trailing newline: #{include_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)
+        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))
+          output_lines.push(file_name_line)
+          # Put into code block.
+          language = treatment == :code_block ? '' : treatment
+          output_lines.push("```#{language}\n")
+          output_lines.push(*include_lines)
+          output_lines.push("```\n")
+      end
+      output_lines.push(comment(" <<<<<< END INCLUDED FILE (#{treatment}): SOURCE #{include_file_path} ")) unless pristine
     end
-    output_lines.push(comment(" <<<<<< END INCLUDED FILE (#{treatment}): SOURCE #{include_file.path} ")) unless pristine
   end
 
-  def resolve_images(scan_data, input_line, output_lines)
-  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))
+  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
-    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,
+    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
+      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
+      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
 
 end

data/readme_files/README.template.md

@@ -2,6 +2,10 @@
 
 ![Gem Version](https://badge.fury.io/rb/markdown_helper.svg)
 
+## 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.
+
 ## What's This?
 
 Class <code>MarkdownHelper</code> supports:
@@ -12,11 +16,11 @@ Class <code>MarkdownHelper</code> supports:
 
 ## How It Works
 
-The markdown helper reads a markdown document (template) and writes another markdown document.
+The markdown helper is a preprocessor that reads a markdown document (template) and writes another markdown document.
 
 The template can contain certain instructions that call for file inclusions and image resolutions.
 
-## Commented or Pristine?
+### Commented or Pristine?
 
 By default, the output markdown has added comments that show:
 
@@ -56,6 +60,8 @@ Comment text is written into the output between the comment delimiters <code>\<!
 
 Verbatim text is included unadorned.  Most often, verbatim text is markdown to be rendered as part of the markdown page.
 
+The verbatim text is itself scanned for nested includes.
+
 ### Usage
 
 #### CLI

data/readme_files/use_cases/evergreen_examples.md

@@ -0,0 +1,14 @@
+### 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 refreahed the output!
+
+Here's how:
+
+1.  Maintain each code example in a separate executable file.
+1.  Maintain markdown files that have include desctiptions, 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.

data/readme_files/use_cases/generated_text.md

@@ -0,0 +1,5 @@
+### Include Generated Text
+
+Use the markdown helper to include text that is genrated at project "build time."
+
+Example:  Project build runs each executable with option <code>--help</code>, capturing the output into a file.  That file can then be included into the markdown pages for the project.

data/readme_files/use_cases/image_attributes.md

@@ -0,0 +1,8 @@
+### Image Attributes
+
+Use the markdown helper to assign attributes to images.
+
+If you're using the markdown helper to [resolve image file paths for a Ruby gem](./rubygem_images.md), you'll be using the GitHub markdown image-description idiom (begins with exclamation point), and not the HTML <code>img</code> idiom.
+
+The image description does not accept attributes (such as height and width), but the markdown helper does accept those, passing them through to an <code>img</code> HTML element.
+s

data/readme_files/use_cases/reusable_text.md

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

data/readme_files/use_cases/rubygem_images.md

@@ -0,0 +1,9 @@
+### RubyGem 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.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: markdown_helper
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.5.0
 platform: ruby
 authors:
 - burdettelamar
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-03-19 00:00:00.000000000 Z
+date: 2018-04-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -109,6 +109,11 @@ files:
 - 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: