markdown_helper 1.8.0 → 1.9.0

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

@@ -0,0 +1,26 @@
+include.rb: Could not read include file, (MarkdownHelper::MissingIncludeeError)
+  Backtrace (innermost include first):
+    Level 0:
+      Includer:
+        Location: markdown/use_cases/include/diagnose_missing_includee/includer_2.md:1
+        Include description: @[: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:1
+        Include description: @[: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:1
+        Include description: @[:markdown](includer_1.md)
+      Includee:
+        File path: markdown/use_cases/include/diagnose_missing_includee/includer_1.md
+    Level 3:
+      Includer:
+        Location: includer.md:1
+        Include description: @[:markdown](includer_0.md)
+      Includee:
+        File path: markdown/use_cases/include/diagnose_missing_includee/includer_0.md

data/markdown/use_cases/include/diagnose_missing_includee/diagnose_missing_includee.rb

@@ -0,0 +1,67 @@
+require_relative '../include_use_case'
+
+class DiagnoseMissingIncludee < 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, 3],
+    ].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 Missing Includee
+
+Use the backtrace of inclusions to diagnose and correct a missing or otherwise unreadable includee file.
+
+The backtrace is especially useful for errors in nested includes.
+
+#### Files To Be Included
+
+These files demonstrate nested inclusion, with a missing includee file.
+
+@[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_missing_includee.err)
+EOT
+    )
+
+    use_case.build
+
+  end
+
+end

data/markdown/use_cases/include/diagnose_missing_includee/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_missing_includee/included.md

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

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,100 @@
+### Diagnose Missing Includee
+
+Use the backtrace of inclusions to diagnose and correct a missing or otherwise unreadable includee file.
+
+The backtrace is especially useful for errors in nested includes.
+
+#### Files To Be Included
+
+These files demonstrate nested inclusion, with a missing includee file.
+
+```includer_0.md```:
+```markdown
+@[:markdown](includer_1.md)
+```
+
+```includer_1.md```:
+```markdown
+@[:markdown](includer_2.md)
+```
+
+```includer_2.md```:
+```markdown
+@[:markdown](includer_3.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_missing_includee.err```:
+```
+include.rb: Could not read include file, (MarkdownHelper::MissingIncludeeError)
+  Backtrace (innermost include first):
+    Level 0:
+      Includer:
+        Location: markdown/use_cases/include/diagnose_missing_includee/includer_2.md:1
+        Include description: @[: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:1
+        Include description: @[: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:1
+        Include description: @[:markdown](includer_1.md)
+      Includee:
+        File path: markdown/use_cases/include/diagnose_missing_includee/includer_1.md
+    Level 3:
+      Includer:
+        Location: includer.md:1
+        Include description: @[:markdown](includer_0.md)
+      Includee:
+        File path: markdown/use_cases/include/diagnose_missing_includee/includer_0.md
+```

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

@@ -0,0 +1,29 @@
+### Diagnose Missing Includee
+
+Use the backtrace of inclusions to diagnose and correct a missing or otherwise unreadable includee file.
+
+The backtrace is especially useful for errors in nested includes.
+
+#### Files To Be Included
+
+These files demonstrate nested inclusion, with a missing includee file.
+
+@[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_missing_includee.err)

data/markdown/use_cases/include/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/include_code_block/hello.rb

@@ -0,0 +1,8 @@
+class HelloWorld
+   def initialize(name)
+      @name = name.capitalize
+   end
+   def sayHi
+      puts "Hello !"
+   end
+end

data/markdown/use_cases/include/include_code_block/include_code_block.rb

@@ -0,0 +1,79 @@
+require_relative '../include_use_case'
+
+class IncludeCodeBlock < IncludeUseCase
+
+  def self.build
+
+    use_case_name = File.basename(__FILE__, '.rb')
+    use_case = self.new(use_case_name)
+
+    includee_file_name = 'hello.rb'
+
+    use_case.files_to_write.store(
+        includee_file_name,
+        <<EOT
+class HelloWorld
+   def initialize(name)
+      @name = name.capitalize
+   end
+   def sayHi
+      puts "Hello #{@name}!"
+   end
+end
+EOT
+    )
+
+    use_case.files_to_write.store(
+        INCLUDER_FILE_NAME,
+        <<EOT
+This file includes the code as a code block.
+
+@[:code_block](#{includee_file_name})
+
+EOT
+    )
+
+    use_case.files_to_write.store(
+        TEMPLATE_FILE_NAME,
+        <<EOT
+### Include a Code Block
+
+Use file inclusion to include text as a code block.
+
+#### File to Be Included
+
+Here's a file containing code to be included:
+
+@[markdown](#{includee_file_name})
+
+#### Includer File
+
+Here's a template file that includes it:
+
+@[markdown](#{INCLUDER_FILE_NAME})
+
+The treatment token ```:code_block``` specifies that the included text is to be treated as a code block.
+
+@[:markdown](../interface.md)
+
+#### File with Inclusion
+
+Here's the finished file with the included code block:
+
+@[:pre](#{INCLUDED_FILE_NAME})
+
+And here's the finished markdown, as rendered on this page:
+
+---
+
+@[:markdown](#{INCLUDED_FILE_NAME})
+
+---
+EOT
+    )
+
+    use_case.build
+
+  end
+
+end

data/markdown/use_cases/include/include_code_block/included.md

@@ -0,0 +1,14 @@
+This file includes the code as a code block.
+
+```hello.rb```:
+```
+class HelloWorld
+   def initialize(name)
+      @name = name.capitalize
+   end
+   def sayHi
+      puts "Hello !"
+   end
+end
+```
+

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

@@ -0,0 +1,4 @@
+This file includes the code as a code block.
+
+@[:code_block](hello.rb)
+

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

@@ -0,0 +1,108 @@
+### Include a Code Block
+
+Use file inclusion to include text as a code block.
+
+#### File to Be Included
+
+Here's a file containing code to be included:
+
+```hello.rb```:
+```markdown
+class HelloWorld
+   def initialize(name)
+      @name = name.capitalize
+   end
+   def sayHi
+      puts "Hello !"
+   end
+end
+```
+
+#### Includer File
+
+Here's a template file that includes it:
+
+```includer.md```:
+```markdown
+This file includes the code as a code block.
+
+@[:code_block](hello.rb)
+
+```
+
+The treatment token ```:code_block``` specifies that the included text is to be treated as a code block.
+
+#### 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
+```
+
+#### File with Inclusion
+
+Here's the finished file with the included code block:
+
+<pre>
+This file includes the code as a code block.
+
+```hello.rb```:
+```
+class HelloWorld
+   def initialize(name)
+      @name = name.capitalize
+   end
+   def sayHi
+      puts "Hello !"
+   end
+end
+```
+
+</pre>
+
+And here's the finished markdown, as rendered on this page:
+
+---
+
+This file includes the code as a code block.
+
+```hello.rb```:
+```
+class HelloWorld
+   def initialize(name)
+      @name = name.capitalize
+   end
+   def sayHi
+      puts "Hello !"
+   end
+end
+```
+
+
+---