markdown_helper 2.0.0 → 2.1.0

data/lib/markdown_helper/version.rb

@@ -1,3 +1,3 @@
 class MarkdownHelper
-  VERSION = '2.0.0'
+  VERSION = '2.1.0'
 end

data/markdown/readme/README.template.md

@@ -1,37 +1,32 @@
 # Markdown Helper
 
-![Gem Version](https://badge.fury.io/rb/markdown_helper.svg) [Visit gem markdown_helper](https://rubygems.org/gems/markdown_helper)
-
-## Deprecated
-
-- Method ```:resolve```.
-- Command ```markdown_helper resolve```.
+[![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?
 
-Treatments for included file:
+Page TOC (table of contents) is improved:
 
-- Support is added for including a file as a comment.  See the [use case](markdown/use_cases/include_files/include_text_as_comment/use_case.md#include-text-as-comment).
-- Support is added for including a file as pre-formatted.  See the [use case](markdown/use_cases/include_files/include_text_as_pre/use_case.md#include-text-as-pre).
+- **Old**:  You would first run the markdown helper to generate a page TOC, then run the helper a second time to include the page TOC where you want it.
+- **New**:  You specify the site for the page TOC in the page itself, and the page TOC is automatically generated and inserted there.  See the [use case](markdown/use_cases/include_files/include_page_toc/use_case.md#include-page-toc)
 
-(The new version, 2.0.0, is not a major increment over version 1.9.9.  Numbers just ran out.)
+The old way is now deprecated.
+
+@[:page_toc](## Contents)
 
 ## What's a Markdown Helper?
 
 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 the table of contents for a markdown page.
-* [Image path resolution](#image-path-resolution): to resolve relative image paths to absolute URL paths (so they work even in gem documentation). [Deprecated]**
-* [Image attributes](#image-attributes): image attributes are passed through to an HTML <code>img</code> tag.  [Deprecated]**
+* [Page TOC](#page-toc): to create and insert the table of contents for a markdown page.
 
 ## How It Works
 
 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.
+The template can contain certain instructions that call for file inclusions.
 
-### Restriction:  ```git``` Only
+### 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.
 
@@ -41,11 +36,10 @@ 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.  [Deprecated]**
 
 You can suppress those comments using the <code>pristine</code> option.
 
-## File Inclusion 
+## File Inclusion
 
 <img src="images/include.png" alt="include_icon" width="50">
 
@@ -53,31 +47,41 @@ This markdown helper enables file inclusion in GitHub markdown.
 
 (Actually, this README file itself is built using file inclusion.)
 
-Use the markdown helper to merge external files into a markdown (</code>.md</code>) file.
+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).
+
+### 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).
 
-See the [use cases](markdown/use_cases/use_cases.md#use-cases).
+### Nest Inclusions
+
+You can nest inclusions.  See the [use case](markdown/use_cases/include_files/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).
+
 #### Highlighted Code Block
 
-@[ruby](include.rb)
+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).
 
 #### Plain Code Block
 
-@[:code_block](include.rb)
-
-[Note:  In the gem documentation, RubyDoc.info chooses to highlight this code block regardless.  Go figure.]
+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).
 
 #### Comment
 
-Comment text is written into the output between the comment delimiters <code>\<!--</code> and <code>--></code>
-
-#### Markdown
+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).
 
-Markdown text is included unadorned, and will be processed on GitHub as markdown.
+### Pre-Formattted Text
 
-The markdown text is itself scanned for nested includes.
+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).
 
 ### Usage
 
@@ -101,93 +105,31 @@ where:
   * Highlighting mode such as <code>[ruby]</code>, to include a highlighted code block.  This can be any Ace mode mentioned in [GitHub Languages](https://github.com/github/linguist/blob/master/lib/linguist/languages.yml).
   * <code>[:code_block]</code>, to include a plain code block.
   * <code>[:markdown]</code>, to include text markdown (to be rendered as markdown).
+  * <code>[:comment]</code>, to insert text as a markdown comment.
+  * <code>[:pre]</code>, to include pre-formatted text.
 * *relative_file_path* points to the file to be included.
 
 ##### Example Include Descriptions
 
 @[code_block](include.md)
 
-## Page TOC
-
-The markdown helper can create the table of contents for a markdown page.
-- The TOC is a tree of links to the headers on the page, suitable for inclusion with the page itself.
-- See the [use case](markdown/use_cases/tables_of_contents/create_and_include_page_toc/use_case.md#create-and-include-page-toc).
-
-
-
-## Image Path Resolution **[Deprecated]**
-
-<img src="images/image.png" alt="image_icon" width="50">
-
-This markdown helper enables image path resolution in GitHub markdown.
-
-(Actually, this README file itself is built using image path resolution.)
-
-Use the markdown helper to resolve image relative paths in a markdown (</code>.md</code>) file.
-
-This matters because when markdown becomes part of a Ruby gem, its images will have been relocated in the documentation at RubyDoc.info, breaking the relative paths. The resolved (absolute) urls, however, will still be valid.
-
-### Usage
-
-#### CLI
-
-@[:code_block](../../bin/usage/resolve.txt)
-
-#### API
-
-@[ruby](resolve_usage.rb)
-
-#### Image Descriptions
-
-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>
+#### Page TOC
 
-where:
-
-* *alt_text* is the usual alt text for an HTML image.
-* *relative_file_path* points to the file to be included.
-* *attributes* specify image attributes.  See [Image Attributes](#image-attributes) below.
-
-##### Example Image Descriptions
+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).
 
-@[code_block](resolve.md)
+#### Diagnostics
 
-## Image Attributes
+##### "Noisy" (Not Pristine)
 
-<img src="images/html.png" alt="html_icon" width="50">
+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).
 
-This markdown helper enables HTML image attributes in GitHub markdown [image descriptions](https://github.github.com/gfm/#image-description).
+##### Missing Includee File
 
-(Actually, this README file itself is built using image attributes.)
-
-Use the markdown helper to add image attributes in a markdown (</code>.md</code>) file.
-
-### Usage
-
-#### CLI
-
-@[:code_block](../../bin/usage/resolve.txt)
-
-#### API
-
-@[ruby](resolve_usage.rb)
-
-#### Image Descriptions
-
-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>
-
-where:
-
-* *alt_text* is the usual alt text for an HTML image.
-* *relative_file_path* points to the file to be included.
-* *attributes* are whitespace-separated name-value pairs in the form *name*<code>=</code>*value*.  These are passed through to the generated <code>img</code> HTML element.
+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).
 
-##### Example Image Descriptions
+##### Circular Inclusion
 
-@[code_block](resolve.md)
+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).
 
 ## What Should Be Next?
 

data/markdown/readme/include.md

@@ -3,3 +3,7 @@
 @[:code_block](my_language.xyzzy)
 
 @[:markdown](my_markdown.md)
+
+@[:comment](my_comment.txt)
+
+@[:pre](my_preformatted.txt)

data/markdown/readme/include_usage.rb

@@ -2,9 +2,8 @@ require 'markdown_helper'
 
 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 = MarkdownHelper.new
 markdown_helper.pristine = true
 markdown_helper.include(template_file_path, markdown_file_path)
 # Also pristine.

data/markdown/use_cases/Rakefile

@@ -22,24 +22,23 @@ EOT
         use_case_dirs = {
             :include_files => %w/
                 reuse_text
-                include_with_added_comments
                 nest_inclusions
                 include_markdown
                 include_code_block
                 include_highlighted_code
+                include_page_toc
                 include_text_as_comment
                 include_text_as_pre
                 include_generated_text
+                include_with_added_comments
                 diagnose_missing_includee
                 diagnose_circular_includes
             /,
-            :tables_of_contents => %w/
-                create_and_include_page_toc
-            /,
-            # :resolve => %w/
-                # resize_images
-                # resolve_with_added_comments
-                # gemify_images
+
+            # include_page_toc
+
+            # :tables_of_contents => %w/
+            #     create_and_include_page_toc
             # /,
         }
         use_case_dirs.each_pair do |section, dir_names|
@@ -52,40 +51,38 @@ EOT
 EOT
 ) unless dir_names.empty?
 
+          # Be careful with use case that has a backtrace.
           backtrace_cases = %w/
               diagnose_missing_includee
               diagnose_circular_includes
           /
+
+          # Each use case is in a separate directory.
           dir_names.each do |dir_name|
             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
+
+              # There should be a conventionally-named ruby file to build the use case.
+              fail dir_name unless File.exist?(UseCase::BUILDER_FILE_NAME)
+
+              # There should be a conventionally-named use-case template.
+              fail dir_name unless File.exist?(UseCase::TEMPLATE_FILE_NAME)
+
+              class_name = camelize(dir_name)
+              command = "ruby -I . -r #{UseCase::BUILDER_FILE_NAME} -e #{class_name}.build"
+              if backtrace_cases.include?(dir_name)
+                command += " 2> #{dir_name}.err"
+                begin
                   system(command)
+                rescue
+                  #
                 end
+              else
+                system(command)
               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_line = File.open(UseCase::TEMPLATE_FILE_NAME).grep(/^#/).first.chomp
               title = title_line.split(/\s/, 2).pop
-              use_case_file_name = File.basename(use_case_file_path)
+              use_case_file_name = File.basename(UseCase::USE_CASE_FILE_NAME)
               use_case_anchor = dir_name.gsub('_', '-')
               use_case_relative_url = File.join(
                   section.to_s,

data/markdown/use_cases/include_files/diagnose_circular_includes/diagnose_circular_includes.err

@@ -1,4 +1,4 @@
-include.rb: Includes are circular: (MarkdownHelper::CircularIncludeError)
+C:/Ruby25-x64/lib/ruby/gems/2.5.0/gems/markdown_helper-2.1.0/bin/_include: Includes are circular: (MarkdownHelper::CircularIncludeError)
   Backtrace (innermost include first):
     Level 0:
       Includer:

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

@@ -69,7 +69,7 @@ Here's the resulting backtrace of inclusions.
 
 ```diagnose_circular_includes.err```:
 ```
-include.rb: Includes are circular: (MarkdownHelper::CircularIncludeError)
+C:/Ruby25-x64/lib/ruby/gems/2.5.0/gems/markdown_helper-2.1.0/bin/_include: Includes are circular: (MarkdownHelper::CircularIncludeError)
   Backtrace (innermost include first):
     Level 0:
       Includer:

data/markdown/use_cases/include_files/diagnose_circular_includes/{diagnose_circular_includes.rb → use_case_builder.rb}

@@ -4,8 +4,7 @@ class DiagnoseCircularIncludes < IncludeUseCase
 
   def self.build
 
-    use_case_name = File.basename(__FILE__, '.rb')
-    use_case = self.new(use_case_name)
+    use_case = self.new
 
     use_case.write_ruby_file(pristine = true)
 

data/markdown/use_cases/include_files/diagnose_missing_includee/diagnose_missing_includee.err

@@ -1,4 +1,4 @@
-include.rb: Could not read include file, (MarkdownHelper::UnreadableInputError)
+C:/Ruby25-x64/lib/ruby/gems/2.5.0/gems/markdown_helper-2.1.0/bin/_include: Could not read include file, (MarkdownHelper::UnreadableInputError)
   Backtrace (innermost include first):
     Level 0:
       Includer:

data/markdown/use_cases/include_files/diagnose_missing_includee/use_case.md

@@ -71,7 +71,7 @@ Here's the resulting backtrace of inclusions.
 
 ```diagnose_missing_includee.err```:
 ```
-include.rb: Could not read include file, (MarkdownHelper::UnreadableInputError)
+C:/Ruby25-x64/lib/ruby/gems/2.5.0/gems/markdown_helper-2.1.0/bin/_include: Could not read include file, (MarkdownHelper::UnreadableInputError)
   Backtrace (innermost include first):
     Level 0:
       Includer:

data/markdown/use_cases/include_files/diagnose_missing_includee/{diagnose_missing_includee.rb → use_case_builder.rb}

@@ -4,8 +4,7 @@ class DiagnoseMissingIncludee < IncludeUseCase
 
   def self.build
 
-    use_case_name = File.basename(__FILE__, '.rb')
-    use_case = self.new(use_case_name)
+    use_case = self.new
 
     use_case.write_ruby_file(pristine = true)
 

data/markdown/use_cases/include_files/include_code_block/{include_code_block.rb → use_case_builder.rb}

@@ -4,8 +4,7 @@ class IncludeCodeBlock < IncludeUseCase
 
   def self.build
 
-    use_case_name = File.basename(__FILE__, '.rb')
-    use_case = self.new(use_case_name)
+    use_case = self.new
 
     includee_file_name = 'hello.rb'
 

data/markdown/use_cases/include_files/include_generated_text/{include_generated_text.rb → use_case_builder.rb}

@@ -4,8 +4,7 @@ class IncludeGeneratedText < IncludeUseCase
 
   def self.build
 
-    use_case_name = File.basename(__FILE__, '.rb')
-    use_case = self.new(use_case_name)
+    use_case = self.new
 
     use_case.files_to_write.store(
         TEMPLATE_FILE_NAME,

data/markdown/use_cases/include_files/include_highlighted_code/{include_highlighted_code.rb → use_case_builder.rb}

@@ -4,8 +4,7 @@ class IncludeHighlightedCode < IncludeUseCase
 
   def self.build
 
-    use_case_name = File.basename(__FILE__, '.rb')
-    use_case = self.new(use_case_name)
+    use_case = self.new
 
     use_case.write_includer_file
 

data/markdown/use_cases/include_files/include_markdown/{include_markdown.rb → use_case_builder.rb}

@@ -4,8 +4,7 @@ class IncludeMarkdown < IncludeUseCase
 
   def self.build
 
-    use_case_name = File.basename(__FILE__, '.rb')
-    use_case = self.new(use_case_name)
+    use_case = self.new
 
     includee_file_name = 'markdown.md'
 

data/markdown/use_cases/include_files/include_page_toc/included.md

@@ -0,0 +1,48 @@
+<!-- >>>>>> BEGIN GENERATED FILE (include): SOURCE includer.md -->
+# Page Title
+
+## Page Contents
+- [Includer level-two title.](#includer-level-two-title)
+  - [Includer level-three title.](#includer-level-three-title)
+  - [Another includer level-three title.](#another-includer-level-three-title)
+- [Another includer level-two title.](#another-includer-level-two-title)
+- [Includee 0 level-two title.](#includee-0-level-two-title)
+  - [Includee 0 level-three title.](#includee-0-level-three-title)
+  - [Another includee 0 level-three title.](#another-includee-0-level-three-title)
+- [Another includee 0 level-two title.](#another-includee-0-level-two-title)
+- [Includee 1 level-two title.](#includee-1-level-two-title)
+  - [Includee 1 level-three title.](#includee-1-level-three-title)
+  - [Another includee 1 level-three title.](#another-includee-1-level-three-title)
+- [Another includee 1 level-two title.](#another-includee-1-level-two-title)
+
+## Includer level-two title.
+
+### Includer level-three title.
+
+### Another includer level-three title.
+
+## Another includer level-two title.
+
+<!-- >>>>>> BEGIN INCLUDED FILE (markdown): SOURCE markdown/use_cases/include_files/include_page_toc/markdown_0.md -->
+        
+## Includee 0 level-two title.
+
+### Includee 0 level-three title.
+
+### Another includee 0 level-three title.
+
+## Another includee 0 level-two title.
+<!-- <<<<<< END INCLUDED FILE (markdown): SOURCE markdown/use_cases/include_files/include_page_toc/markdown_0.md -->
+
+<!-- >>>>>> BEGIN INCLUDED FILE (markdown): SOURCE markdown/use_cases/include_files/include_page_toc/markdown_1.md -->
+        
+## Includee 1 level-two title.
+
+### Includee 1 level-three title.
+
+### Another includee 1 level-three title.
+
+## Another includee 1 level-two title.
+<!-- <<<<<< END INCLUDED FILE (markdown): SOURCE markdown/use_cases/include_files/include_page_toc/markdown_1.md -->
+
+<!-- <<<<<< END GENERATED FILE (include): SOURCE includer.md -->