markdown_helper 1.8.0 → 1.9.0

data/lib/markdown_helper/version.rb

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

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

@@ -4,12 +4,21 @@
 
 ## What's New?
 
-Command-line interface is now supported:
-
-* Added first [use cases](markdown/use_cases/use_cases.md#use-cases) (there will be more).
-* Deprecated treatment ```:verbatim```, changing to ```:markdown```.  The older term could be confusing, because although text to be treated ```:verbatim``` is included 'verbatim' (without change), it will be processed as GitHub markdown.
-
-## What's This?
+* The helper now checks whether the working directory is in a ```git``` project, and raises an exception if not.
+
+* There is now a backtrace of inclusions when:
+  * An includee file cannot be read.
+  * A circular inclusion (direct or indirect) is found.
+* The backtrace shows:
+  * Each includer file path.
+  * Its include description.
+  * The includee file path.
+* File paths are relative to the git directory.
+* Use cases are added:
+  * [Diagnose Missing Includee](markdown/use_cases/include/diagnose_missing_includee/use_case.md#diagnose-missing-includee).
+  * [Diagnose Circular Includes](markdown/use_cases/include/diagnose_circular_includes/use_case.md#diagnose-circular-includes).
+
+## What's a Markdown Helper?
 
 Class <code>MarkdownHelper</code> supports:
 
@@ -23,6 +32,10 @@ The markdown helper is a preprocessor that reads a markdown document (template)
 
 The template can contain certain instructions that call for file inclusions and image resolutions.
 
+### Restriction:  ```git``` Only
+
+The helper works only in a ```git``` project:  the working directory or one of ita parents must be a git directory -- one in which command ```git rev-parse --git-dir``` succeeds.
+
 ### Commented or Pristine?
 
 By default, the output markdown has added comments that show:
@@ -35,7 +48,7 @@ You can suppress those comments using the <code>pristine</code> option.
 
 ## File Inclusion 
 
-![include_icon](../images/include.png | width=50)
+![include_icon](../../images/include.png | width=50)
 
 This markdown helper enables file inclusion in GitHub markdown.
 
@@ -69,7 +82,7 @@ The markdown text is itself scanned for nested includes.
 
 #### CLI
 
-@[:code_block](../bin/usage/include.txt)
+@[:code_block](../../bin/usage/include.txt)
 
 #### API
 
@@ -95,7 +108,7 @@ where:
 
 ## Image Path Resolution 
 
-![image_icon](../images/image.png | width=50)
+![image_icon](../../images/image.png | width=50)
 
 This markdown helper enables image path resolution in GitHub markdown.
 
@@ -109,7 +122,7 @@ This matters because when markdown becomes part of a Ruby gem, its images will h
 
 #### CLI
 
-@[:code_block](../bin/usage/resolve.txt)
+@[:code_block](../../bin/usage/resolve.txt)
 
 #### API
 
@@ -133,7 +146,7 @@ where:
 
 ## Image Attributes
 
-![html_icon](../images/html.png | width=50)
+![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).
 
@@ -145,7 +158,7 @@ Use the markdown helper to add image attributes in a markdown (</code>.md</code>
 
 #### CLI
 
-@[:code_block](../bin/usage/resolve.txt)
+@[:code_block](../../bin/usage/resolve.txt)
 
 #### API
 

data/markdown/readme/highlighted_ruby.md

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

data/markdown/use_cases/Rakefile

@@ -1,8 +1,14 @@
+require_relative 'include/include_use_case'
 
 namespace :build do
 
+  def camelize(snake_case_string)
+    snake_case_string.split('_').collect(&:capitalize).join
+  end
+
   desc 'Build use case markdown'
   task :use_cases do
+    # Page that links to use cases.
     File.open('use_cases.md', 'w') do |use_case_file|
       use_case_file.puts(<<EOT
 # Use Cases
@@ -10,46 +16,70 @@ namespace :build do
 EOT
       )
       dir_path = File.dirname(__FILE__)
-      use_case_file_paths = []
-      tbs_file_paths = []
       Dir.chdir(dir_path) do
+        IncludeUseCase.write_interface_file
         use_case_dirs = {
             :include => %w/
                 reuse_text
                 include_with_added_comments
+                nest_inclusions
+                include_markdown
+                include_code_block
+                include_highlighted_code
+                include_generated_text
+                diagnose_missing_includee
+                diagnose_circular_includes
             /,
-            :resolve => %w/
-            /
+            # :resolve => %w/
+                # resize_images
+                # resolve_with_added_comments
+                # gemify_images
+            # /
         }
         use_case_dirs.each_pair do |section, dir_names|
+
+          # Header for section, if any dirs therein.
           use_case_file.puts(<<EOT
 ## #{section.to_s.capitalize}
 
 EOT
 ) unless dir_names.empty?
+
+          backtrace_cases = %w/
+              diagnose_missing_includee
+              diagnose_circular_includes
+          /
           dir_names.each do |dir_name|
-            ruby_file_path = File.join(
-                dir_path,
-                section.to_s,
-                dir_name,
-                "#{dir_name}.rb"
-            )
-            if File.exist?(ruby_file_path)
-              command = "ruby #{ruby_file_path}"
-              system(command)
-            end
-            use_case_file_path = File.join(
-                dir_path,
-                section.to_s,
-                dir_name,
-                "#{dir_name}.md"
-            )
-            if File.exist?(use_case_file_path)
+            Dir.chdir("#{section}/#{dir_name}") do
+              # If the dir has a Ruby file, run it.
+              ruby_file_path = "#{dir_name}.rb"
+              if File.exist?(ruby_file_path)
+                class_name = camelize(dir_name)
+                command = "ruby -I . -r #{dir_name} -e #{class_name}.build"
+                if backtrace_cases.include?(dir_name)
+                  command += " 2> #{dir_name}.err"
+                  begin
+                    system(command)
+                  rescue
+                    #
+                  ensure
+                  end
+                else
+                  system(command)
+                end
+              end
+
+              # If the dir has a use case file, link to it.
+              use_case_file_path = 'use_case.md'
+              unless File.exist?(use_case_file_path)
+                message = "File #{dir_name}/use_case.md does not exist"
+                warn(message)
+                next
+              end
               title_line = File.open(use_case_file_path).grep(/^#/).first.chomp
               title = title_line.split(/\s/, 2).pop
               use_case_file_name = File.basename(use_case_file_path)
-              use_case_name = File.basename(use_case_file_path, '.md')
-              use_case_anchor = use_case_name.gsub('_', '-')
+              use_case_anchor = dir_name.gsub('_', '-')
               use_case_relative_url = File.join(
                   section.to_s,
                   dir_name,

data/markdown/use_cases/include/diagnose_circular_includes/diagnose_circular_includes.err

@@ -0,0 +1,26 @@
+include.rb: Includes are circular: (MarkdownHelper::CircularIncludeError)
+  Backtrace (innermost include first):
+    Level 0:
+      Includer:
+        Location: markdown/use_cases/include/diagnose_circular_includes/includer_2.md:1
+        Include description: @[:markdown](includer_0.md)
+      Includee:
+        File path: markdown/use_cases/include/diagnose_circular_includes/includer_0.md
+    Level 1:
+      Includer:
+        Location: markdown/use_cases/include/diagnose_circular_includes/includer_1.md:1
+        Include description: @[:markdown](includer_2.md)
+      Includee:
+        File path: markdown/use_cases/include/diagnose_circular_includes/includer_2.md
+    Level 2:
+      Includer:
+        Location: markdown/use_cases/include/diagnose_circular_includes/includer_0.md:1
+        Include description: @[:markdown](includer_1.md)
+      Includee:
+        File path: markdown/use_cases/include/diagnose_circular_includes/includer_1.md
+    Level 3:
+      Includer:
+        Location: includer.md:1
+        Include description: @[:markdown](includer_0.md)
+      Includee:
+        File path: markdown/use_cases/include/diagnose_circular_includes/includer_0.md

data/markdown/use_cases/include/diagnose_circular_includes/diagnose_circular_includes.rb

@@ -0,0 +1,65 @@
+require_relative '../include_use_case'
+
+class DiagnoseCircularIncludes < IncludeUseCase
+
+  def self.build
+
+    use_case_name = File.basename(__FILE__, '.rb')
+    use_case = self.new(use_case_name)
+
+    use_case.write_ruby_file(pristine = true)
+
+    [
+        [0, 1],
+        [1, 2],
+        [2, 0],
+    ].each do |indexes|
+      includer_index, includee_index = *indexes
+      includer_file_name = "includer_#{includer_index}.md"
+      includee_file_name = "includer_#{includee_index}.md"
+      if includer_index == 0
+        include_description = "@[:markdown](#{includer_file_name})\n"
+        File.write(INCLUDER_FILE_NAME, include_description)
+      end
+      include_description = "@[:markdown](#{includee_file_name})\n"
+      File.write(includer_file_name, include_description)
+    end
+
+    File.write(
+        TEMPLATE_FILE_NAME,
+        <<EOT
+### Diagnose Circular Includes
+
+Use the backtrace of inclusions to diagnose and correct circular inclusions:  that is inclusions that directly or indirectly cause a file to include itself.
+
+#### Files To Be Included
+
+These files demonstrate nested inclusion, with circular inclusions.
+
+@[markdown](includer_0.md)
+
+@[markdown](includer_1.md)
+
+@[markdown](includer_2.md)
+
+#### Includer File
+
+This file initiates the nested inclusions.
+
+@[markdown](#{INCLUDER_FILE_NAME})
+
+@[:markdown](../interface.md)
+
+#### Error and Backtrace
+
+Here's the resulting backtrace of inclusions.
+
+@[:code_block](diagnose_circular_includes.err)
+EOT
+    )
+
+    use_case.build
+
+  end
+
+end

data/markdown/use_cases/include/diagnose_circular_includes/include.rb

@@ -0,0 +1,5 @@
+require 'markdown_helper'
+
+# Option :pristine suppresses comment insertion.
+markdown_helper = MarkdownHelper.new(:pristine => true)
+markdown_helper.include('includer.md', 'included.md')

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

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

data/markdown/use_cases/include/diagnose_circular_includes/includer_0.md

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

data/markdown/use_cases/include/diagnose_circular_includes/includer_1.md

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

data/markdown/use_cases/include/diagnose_circular_includes/includer_2.md

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

data/markdown/use_cases/include/diagnose_circular_includes/use_case.md

@@ -0,0 +1,98 @@
+### Diagnose Circular Includes
+
+Use the backtrace of inclusions to diagnose and correct circular inclusions:  that is inclusions that directly or indirectly cause a file to include itself.
+
+#### Files To Be Included
+
+These files demonstrate nested inclusion, with circular inclusions.
+
+```includer_0.md```:
+```markdown
+@[:markdown](includer_1.md)
+```
+
+```includer_1.md```:
+```markdown
+@[:markdown](includer_2.md)
+```
+
+```includer_2.md```:
+```markdown
+@[:markdown](includer_0.md)
+```
+
+#### Includer File
+
+This file initiates the nested inclusions.
+
+```includer.md```:
+```markdown
+@[:markdown](includer_0.md)
+```
+
+#### CLI
+
+You can use the command-line interface to perform the inclusion.
+
+##### Command
+
+```sh
+markdown_helper include --pristine includer.md included.md
+```
+
+(Option ```--pristine``` suppresses comment insertion.)
+
+#### API
+
+You can use the API to perform the inclusion.
+
+##### Ruby Code
+
+```include.rb```:
+```ruby
+require 'markdown_helper'
+
+# Option :pristine suppresses comment insertion.
+markdown_helper = MarkdownHelper.new(:pristine => true)
+markdown_helper.include('includer.md', 'included.md')
+```
+
+##### Command
+
+```sh
+ruby include.rb
+```
+
+#### Error and Backtrace
+
+Here's the resulting backtrace of inclusions.
+
+```diagnose_circular_includes.err```:
+```
+include.rb: Includes are circular: (MarkdownHelper::CircularIncludeError)
+  Backtrace (innermost include first):
+    Level 0:
+      Includer:
+        Location: markdown/use_cases/include/diagnose_circular_includes/includer_2.md:1
+        Include description: @[:markdown](includer_0.md)
+      Includee:
+        File path: markdown/use_cases/include/diagnose_circular_includes/includer_0.md
+    Level 1:
+      Includer:
+        Location: markdown/use_cases/include/diagnose_circular_includes/includer_1.md:1
+        Include description: @[:markdown](includer_2.md)
+      Includee:
+        File path: markdown/use_cases/include/diagnose_circular_includes/includer_2.md
+    Level 2:
+      Includer:
+        Location: markdown/use_cases/include/diagnose_circular_includes/includer_0.md:1
+        Include description: @[:markdown](includer_1.md)
+      Includee:
+        File path: markdown/use_cases/include/diagnose_circular_includes/includer_1.md
+    Level 3:
+      Includer:
+        Location: includer.md:1
+        Include description: @[:markdown](includer_0.md)
+      Includee:
+        File path: markdown/use_cases/include/diagnose_circular_includes/includer_0.md
+```

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

@@ -0,0 +1,27 @@
+### Diagnose Circular Includes
+
+Use the backtrace of inclusions to diagnose and correct circular inclusions:  that is inclusions that directly or indirectly cause a file to include itself.
+
+#### Files To Be Included
+
+These files demonstrate nested inclusion, with circular inclusions.
+
+@[markdown](includer_0.md)
+
+@[markdown](includer_1.md)
+
+@[markdown](includer_2.md)
+
+#### Includer File
+
+This file initiates the nested inclusions.
+
+@[markdown](includer.md)
+
+@[:markdown](../interface.md)
+
+#### Error and Backtrace
+
+Here's the resulting backtrace of inclusions.
+
+@[:code_block](diagnose_circular_includes.err)