markdown_helper 2.3.0 → 2.4.0

data/lib/markdown_helper/version.rb

@@ -1,3 +1,3 @@
 class MarkdownHelper
-  VERSION = '2.3.0'
+  VERSION = '2.4.0'
 end

data/markdown/readme/README.template.md

@@ -2,11 +2,11 @@
 
 [![Gem](https://img.shields.io/gem/v/markdown_helper.svg?style=flat)](http://rubygems.org/gems/markdown_helper "View this project in Rubygems")
 
-## What's New?
+@[:page_toc](## Contents)
 
-Inclusion of text as details is added.  See the [use case](markdown/use_cases/include_files/include_text_as_details/use_case.md#include-text-as-details).
+## Installation
 
-@[:page_toc](## Contents)
+```gem install markdown_helper```
 
 ## What's a Markdown Helper?
 
@@ -14,6 +14,7 @@ Class <code>MarkdownHelper</code> supports:
 
 * [File inclusion](#file-inclusion): to include text from other files, as code-block or markdown.
 * [Page TOC](#page-toc): to create and insert the table of contents for a markdown page.
+* [Run irb](#run-irb): to execute Ruby snippets in the Ruby interactive shell (```irb```) and include the output in markdown.
 
 ## How It Works
 
@@ -46,41 +47,41 @@ See all [use cases](markdown/use_cases/use_cases.md#use-cases).
 
 ### Re-use Text
 
-Keep your markdown DRY (Don't Repeat Yourself) by re-using text.  See the [use case](markdown/use_cases/include_files/reuse_text/use_case.md#reuse-text).
+Keep your markdown DRY (Don't Repeat Yourself) by re-using text.  See the [use case](markdown/use_cases/include/reuse_text/use_case.md#reuse-text).
 
 ### Include Generated Text
 
-In particular, you can include text that's built during your "readme build."  See the [use case](markdown/use_cases/include_files/include_generated_text/use_case.md#include-generated-text).
+In particular, you can include text that's built during your "readme build."  See the [use case](markdown/use_cases/include/include_generated_text/use_case.md#include-generated-text).
 
 ### Nest Inclusions
 
-You can nest inclusions.  See the [use case](markdown/use_cases/include_files/nest_inclusions/use_case.md#nest-inclusions).
+You can nest inclusions.  See the [use case](markdown/use_cases/include/nest_inclusions/use_case.md#nest-inclusions).
 
 ### Merged Text Formats
 
 #### Markdown
 
-You can include text that is to be treated simply as markdown.  See the [use case](markdown/use_cases/include_files/include_markdown/use_case.md#include-markdown).
+You can include text that is to be treated simply as markdown.  See the [use case](markdown/use_cases/include/include_markdown/use_case.md#include-markdown).
 
 #### Highlighted Code Block
 
-You can include a code block that's to be highlighted.  See the [use case](markdown/use_cases/include_files/include_highlighted_code/use_case.md#include-highlighted-code).
+You can include a code block that's to be highlighted.  See the [use case](markdown/use_cases/include/include_highlighted_code/use_case.md#include-highlighted-code).
 
 #### Plain Code Block
 
-You can also include a code block without highlighting.  See the [use case](markdown/use_cases/include_files/include_code_block/use_case.md#include-code-block).
+You can also include a code block without highlighting.  See the [use case](markdown/use_cases/include/include_code_block/use_case.md#include-code-block).
 
 #### Comment
 
-You can include text that's to become a comment in the markdown.  See the [use case](markdown/use_cases/include_files/include_text_as_comment/use_case.md#include-text-as-comment).
+You can include text that's to become a comment in the markdown.  See the [use case](markdown/use_cases/include/include_text_as_comment/use_case.md#include-text-as-comment).
 
 #### Details
 
-You can include text that's to become details in the markdown.  See the [use case](markdown/use_cases/include_files/include_text_as_details/use_case.md#include-text-as-details).
+You can include text that's to become details in the markdown.  See the [use case](markdown/use_cases/include/include_text_as_details/use_case.md#include-text-as-details).
 
 ### Pre-Formatted Text
 
-You can include text that's pre-formatted.  See the [use case](markdown/use_cases/include_files/include_text_as_pre/use_case.md#include-text-as-pre).
+You can include text that's pre-formatted.  See the [use case](markdown/use_cases/include/include_text_as_pre/use_case.md#include-text-as-pre).
 
 ### Usage
 
@@ -115,21 +116,25 @@ where:
 
 #### Page TOC
 
-You can specify the location for an automatically-generated page TOC (table of cotents).  See the [use case](markdown/use_cases/include_files/include_page_toc/use_case.md#include-page-toc).
+You can specify the location for an automatically-generated page TOC (table of cotents).  See the [use case](markdown/use_cases/include/include_page_toc/use_case.md#include-page-toc).
 
 #### Diagnostics
 
 ##### "Noisy" (Not Pristine)
 
-By default, the markdown helper inserts comments indicating inclusions.  See the [use case](markdown/use_cases/include_files/include_with_added_comments/use_case.md#include-with-added-comments).
+By default, the markdown helper inserts comments indicating inclusions.  See the [use case](markdown/use_cases/include/include_with_added_comments/use_case.md#include-with-added-comments).
 
 ##### Missing Includee File
 
-A missing includee file causes an exception that shows an inclusion backtrace.  See the [use case](markdown/use_cases/include_files/diagnose_missing_includee/use_case.md#diagnose-missing-includee).
+A missing includee file causes an exception that shows an inclusion backtrace.  See the [use case](markdown/use_cases/include/diagnose_missing_includee/use_case.md#diagnose-missing-includee).
 
 ##### Circular Inclusion
 
-A circular inclusion causes an exception that shows an inclusion backtrace.  See the [use case](markdown/use_cases/include_files/diagnose_circular_includes/use_case.md#diagnose-circular-includes).
+A circular inclusion causes an exception that shows an inclusion backtrace.  See the [use case](markdown/use_cases/include/diagnose_circular_includes/use_case.md#diagnose-circular-includes).
+
+## Run ```irb```
+
+* Execute Ruby snippets in the Ruby interactive shell (```irb```) and include the output in markdown.  See the [use case](markdown/use_cases/run_irb/run_irb/use_case.md#run-irb).
 
 ## What Should Be Next?
 

data/markdown/use_cases/Rakefile

@@ -18,7 +18,7 @@ EOT
       dir_path = File.dirname(__FILE__)
       Dir.chdir(dir_path) do
         use_case_dirs = {
-            :include_files => %w/
+            :include => %w/
                 reuse_text
                 nest_inclusions
                 include_markdown
@@ -33,6 +33,9 @@ EOT
                 diagnose_missing_includee
                 diagnose_circular_includes
             /,
+            :run_irb => %w/
+                run_irb
+            /
         }
         use_case_dirs.each_pair do |section, dir_names|
 
@@ -54,7 +57,7 @@ EOT
           dir_names.each do |dir_name|
             Dir.chdir("#{section}/#{dir_name}") do
               if File.exist?('includer.md')
-                command = 'markdown_helper include --pristine includer.md included.md'
+                command = "markdown_helper #{section} --pristine includer.md included.md"
                 if backtrace_cases.include?(dir_name)
                   # Capture the exception.
                   command += " 2> #{dir_name}.err"
@@ -68,6 +71,10 @@ EOT
                   system(command)
                 end
               end
+              if File.exist?('template.md')
+                command = "markdown_helper #{section} --pristine template.md markdown.md"
+                system(command)
+              end
               command = 'markdown_helper include --pristine use_case_template.md use_case.md'
               system(command)
 

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

@@ -0,0 +1,26 @@
+C:/Ruby26-x64/lib/ruby/gems/2.6.0/gems/markdown_helper-2.3.0/bin/_include: Includes are circular: (MarkdownHelper::CircularIncludeError)
+  Backtrace (innermost include first):
+    Level 0:
+      Includer:
+        Location: markdown/use_cases/include/diagnose_circular_includes/includer_2.md:0
+        Include pragma: @[: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:0
+        Include pragma: @[: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:0
+        Include pragma: @[:markdown](includer_1.md)
+      Includee:
+        File path: markdown/use_cases/include/diagnose_circular_includes/includer_1.md
+    Level 3:
+      Includer:
+        Location: markdown/use_cases/include/diagnose_circular_includes/includer.md:0
+        Include pragma: @[:markdown](includer_0.md)
+      Includee:
+        File path: markdown/use_cases/include/diagnose_circular_includes/includer_0.md

data/markdown/use_cases/{include_files → include}/diagnose_circular_includes/use_case.md

@@ -64,26 +64,26 @@ C:/Ruby26-x64/lib/ruby/gems/2.6.0/gems/markdown_helper-2.3.0/bin/_include: Inclu
   Backtrace (innermost include first):
     Level 0:
       Includer:
-        Location: markdown/use_cases/include_files/diagnose_circular_includes/includer_2.md:0
+        Location: markdown/use_cases/include/diagnose_circular_includes/includer_2.md:0
         Include pragma: @[:markdown](includer_0.md)
       Includee:
-        File path: markdown/use_cases/include_files/diagnose_circular_includes/includer_0.md
+        File path: markdown/use_cases/include/diagnose_circular_includes/includer_0.md
     Level 1:
       Includer:
-        Location: markdown/use_cases/include_files/diagnose_circular_includes/includer_1.md:0
+        Location: markdown/use_cases/include/diagnose_circular_includes/includer_1.md:0
         Include pragma: @[:markdown](includer_2.md)
       Includee:
-        File path: markdown/use_cases/include_files/diagnose_circular_includes/includer_2.md
+        File path: markdown/use_cases/include/diagnose_circular_includes/includer_2.md
     Level 2:
       Includer:
-        Location: markdown/use_cases/include_files/diagnose_circular_includes/includer_0.md:0
+        Location: markdown/use_cases/include/diagnose_circular_includes/includer_0.md:0
         Include pragma: @[:markdown](includer_1.md)
       Includee:
-        File path: markdown/use_cases/include_files/diagnose_circular_includes/includer_1.md
+        File path: markdown/use_cases/include/diagnose_circular_includes/includer_1.md
     Level 3:
       Includer:
-        Location: markdown/use_cases/include_files/diagnose_circular_includes/includer.md:0
+        Location: markdown/use_cases/include/diagnose_circular_includes/includer.md:0
         Include pragma: @[:markdown](includer_0.md)
       Includee:
-        File path: markdown/use_cases/include_files/diagnose_circular_includes/includer_0.md
+        File path: markdown/use_cases/include/diagnose_circular_includes/includer_0.md
 ```

data/markdown/use_cases/include/diagnose_missing_includee/diagnose_missing_includee.err

@@ -0,0 +1,26 @@
+C:/Ruby26-x64/lib/ruby/gems/2.6.0/gems/markdown_helper-2.3.0/bin/_include: Could not read includee file: (MarkdownHelper::UnreadableIncludeeError)
+  Backtrace (innermost include first):
+    Level 0:
+      Includer:
+        Location: markdown/use_cases/include/diagnose_missing_includee/includer_2.md:0
+        Include pragma: @[:markdown](includer_3.md)
+      Includee:
+        File path: markdown/use_cases/include/diagnose_missing_includee/includer_3.md
+    Level 1:
+      Includer:
+        Location: markdown/use_cases/include/diagnose_missing_includee/includer_1.md:0
+        Include pragma: @[:markdown](includer_2.md)
+      Includee:
+        File path: markdown/use_cases/include/diagnose_missing_includee/includer_2.md
+    Level 2:
+      Includer:
+        Location: markdown/use_cases/include/diagnose_missing_includee/includer_0.md:0
+        Include pragma: @[:markdown](includer_1.md)
+      Includee:
+        File path: markdown/use_cases/include/diagnose_missing_includee/includer_1.md
+    Level 3:
+      Includer:
+        Location: markdown/use_cases/include/diagnose_missing_includee/includer.md:0
+        Include pragma: @[:markdown](includer_0.md)
+      Includee:
+        File path: markdown/use_cases/include/diagnose_missing_includee/includer_0.md

data/markdown/use_cases/{include_files → include}/diagnose_missing_includee/use_case.md

@@ -66,26 +66,26 @@ C:/Ruby26-x64/lib/ruby/gems/2.6.0/gems/markdown_helper-2.3.0/bin/_include: Could
   Backtrace (innermost include first):
     Level 0:
       Includer:
-        Location: markdown/use_cases/include_files/diagnose_missing_includee/includer_2.md:0
+        Location: markdown/use_cases/include/diagnose_missing_includee/includer_2.md:0
         Include pragma: @[:markdown](includer_3.md)
       Includee:
-        File path: markdown/use_cases/include_files/diagnose_missing_includee/includer_3.md
+        File path: markdown/use_cases/include/diagnose_missing_includee/includer_3.md
     Level 1:
       Includer:
-        Location: markdown/use_cases/include_files/diagnose_missing_includee/includer_1.md:0
+        Location: markdown/use_cases/include/diagnose_missing_includee/includer_1.md:0
         Include pragma: @[:markdown](includer_2.md)
       Includee:
-        File path: markdown/use_cases/include_files/diagnose_missing_includee/includer_2.md
+        File path: markdown/use_cases/include/diagnose_missing_includee/includer_2.md
     Level 2:
       Includer:
-        Location: markdown/use_cases/include_files/diagnose_missing_includee/includer_0.md:0
+        Location: markdown/use_cases/include/diagnose_missing_includee/includer_0.md:0
         Include pragma: @[:markdown](includer_1.md)
       Includee:
-        File path: markdown/use_cases/include_files/diagnose_missing_includee/includer_1.md
+        File path: markdown/use_cases/include/diagnose_missing_includee/includer_1.md
     Level 3:
       Includer:
-        Location: markdown/use_cases/include_files/diagnose_missing_includee/includer.md:0
+        Location: markdown/use_cases/include/diagnose_missing_includee/includer.md:0
         Include pragma: @[:markdown](includer_0.md)
       Includee:
-        File path: markdown/use_cases/include_files/diagnose_missing_includee/includer_0.md
+        File path: markdown/use_cases/include/diagnose_missing_includee/includer_0.md
 ```

data/markdown/use_cases/run_irb/interface.md

@@ -0,0 +1,16 @@
+#### Run Irb Via <code>markdown_helper</code>
+<details>
+<summary>CLI</summary>
+
+```sh
+markdown_helper run_irb --pristine template.md markdown.md
+```
+
+@[:markdown](../pristine.md)
+</details>
+<details>
+<summary>API</summary>
+
+@[ruby](../run_irb.rb)
+
+</details>