markdown_helper 1.8.0 → 1.9.0

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

@@ -0,0 +1,33 @@
+### 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](hello.rb)
+
+#### Includer File
+
+Here's a template file that includes it:
+
+@[markdown](includer.md)
+
+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.md)
+
+And here's the finished markdown, as rendered on this page:
+
+---
+
+@[:markdown](included.md)
+
+---

data/markdown/use_cases/include/include_generated_text/include_generated_text.rb

@@ -0,0 +1,38 @@
+require_relative '../include_use_case'
+
+class IncludeGeneratedText < IncludeUseCase
+
+  def self.build
+
+    use_case_name = File.basename(__FILE__, '.rb')
+    use_case = self.new(use_case_name)
+
+    use_case.files_to_write.store(
+        TEMPLATE_FILE_NAME,
+        <<EOT
+### Include Generated Text
+
+#### Generate Includable Text
+
+A handy use of file inclusion is seen in including generated text.
+
+That is, the markdown "build" generates files that are then included in the finished markdown document.
+
+The use cases documented here take advantage of that.  Each use case has an executable Ruby file that has [Here Documents](https://ruby-doc.org/core-2.2.0/doc/syntax/literals_rdoc.html#label-Here+Documents) containing all the relevant text.  The build emits the files that are them used to illustrate the use case.
+
+#### Keeping Example Code "Green"
+
+An especially handy use of file inclusion is seen in including example code and output.
+
+1.  Example code in its own file is executed, and its output captured into another file.
+2.  Then both are included in markdown that uses the example.
+
+Running the example each time the markdown is built keeps the example code "green," because it confirms that the code still works.
+EOT
+    )
+
+    use_case.build
+
+  end
+
+end

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

@@ -0,0 +1,18 @@
+### Include Generated Text
+
+#### Generate Includable Text
+
+A handy use of file inclusion is seen in including generated text.
+
+That is, the markdown "build" generates files that are then included in the finished markdown document.
+
+The use cases documented here take advantage of that.  Each use case has an executable Ruby file that has [Here Documents](https://ruby-doc.org/core-2.2.0/doc/syntax/literals_rdoc.html#label-Here+Documents) containing all the relevant text.  The build emits the files that are them used to illustrate the use case.
+
+#### Keeping Example Code "Green"
+
+An especially handy use of file inclusion is seen in including example code and output.
+
+1.  Example code in its own file is executed, and its output captured into another file.
+2.  Then both are included in markdown that uses the example.
+
+Running the example each time the markdown is built keeps the example code "green," because it confirms that the code still works.

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

@@ -0,0 +1,18 @@
+### Include Generated Text
+
+#### Generate Includable Text
+
+A handy use of file inclusion is seen in including generated text.
+
+That is, the markdown "build" generates files that are then included in the finished markdown document.
+
+The use cases documented here take advantage of that.  Each use case has an executable Ruby file that has [Here Documents](https://ruby-doc.org/core-2.2.0/doc/syntax/literals_rdoc.html#label-Here+Documents) containing all the relevant text.  The build emits the files that are them used to illustrate the use case.
+
+#### Keeping Example Code "Green"
+
+An especially handy use of file inclusion is seen in including example code and output.
+
+1.  Example code in its own file is executed, and its output captured into another file.
+2.  Then both are included in markdown that uses the example.
+
+Running the example each time the markdown is built keeps the example code "green," because it confirms that the code still works.

data/markdown/use_cases/include/include_highlighted_code/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_highlighted_code/include_highlighted_code.rb

@@ -0,0 +1,83 @@
+require_relative '../include_use_case'
+
+class IncludeHighlightedCode < IncludeUseCase
+
+  def self.build
+
+    use_case_name = File.basename(__FILE__, '.rb')
+    use_case = self.new(use_case_name)
+
+    use_case.write_includer_file
+
+    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 highlighted code.
+
+@[ruby](#{includee_file_name})
+
+EOT
+    )
+
+    use_case.files_to_write.store(
+        TEMPLATE_FILE_NAME,
+        <<EOT
+### Include Highlighted Code
+
+Use file inclusion to include text as highlighted code.
+
+#### File to Be Included
+
+Here's a file containing Ruby 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 ```ruby``` specifies that the included text is to be highlighted as Ruby code.
+
+The treatment token can be any Ace mode mentioned in [GitHub Languages](https://github.com/github/linguist/blob/master/lib/linguist/languages.yml).  The file lists about 100 Ace modes, covering just about every language and format.
+
+@[:markdown](../interface.md)
+
+#### File with Inclusion
+
+Here's the finished file with the included highlighted code:
+
+@[: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_highlighted_code/included.md

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

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

@@ -0,0 +1,4 @@
+This file includes the code as highlighted code.
+
+@[ruby](hello.rb)
+

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

@@ -0,0 +1,110 @@
+### Include Highlighted Code
+
+Use file inclusion to include text as highlighted code.
+
+#### File to Be Included
+
+Here's a file containing Ruby 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 highlighted code.
+
+@[ruby](hello.rb)
+
+```
+
+The treatment token ```ruby``` specifies that the included text is to be highlighted as Ruby code.
+
+The treatment token can be any Ace mode mentioned in [GitHub Languages](https://github.com/github/linguist/blob/master/lib/linguist/languages.yml).  The file lists about 100 Ace modes, covering just about every language and format.
+
+#### 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 highlighted code:
+
+<pre>
+This file includes the code as highlighted code.
+
+```hello.rb```:
+```ruby
+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 highlighted code.
+
+```hello.rb```:
+```ruby
+class HelloWorld
+   def initialize(name)
+      @name = name.capitalize
+   end
+   def sayHi
+      puts "Hello !"
+   end
+end
+```
+
+
+---

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

@@ -0,0 +1,35 @@
+### Include Highlighted Code
+
+Use file inclusion to include text as highlighted code.
+
+#### File to Be Included
+
+Here's a file containing Ruby code to be included:
+
+@[markdown](hello.rb)
+
+#### Includer File
+
+Here's a template file that includes it:
+
+@[markdown](includer.md)
+
+The treatment token ```ruby``` specifies that the included text is to be highlighted as Ruby code.
+
+The treatment token can be any Ace mode mentioned in [GitHub Languages](https://github.com/github/linguist/blob/master/lib/linguist/languages.yml).  The file lists about 100 Ace modes, covering just about every language and format.
+
+@[:markdown](../interface.md)
+
+#### File with Inclusion
+
+Here's the finished file with the included highlighted code:
+
+@[:pre](included.md)
+
+And here's the finished markdown, as rendered on this page:
+
+---
+
+@[:markdown](included.md)
+
+---

data/markdown/use_cases/include/include_markdown/include_markdown.rb

@@ -0,0 +1,81 @@
+require_relative '../include_use_case'
+
+class IncludeMarkdown < IncludeUseCase
+
+  def self.build
+
+    use_case_name = File.basename(__FILE__, '.rb')
+    use_case = self.new(use_case_name)
+
+    includee_file_name = 'markdown.md'
+
+    use_case.files_to_write.store(
+        includee_file_name,
+        <<EOT
+This fiie, to be included, is markdown.
+
+### This is a level-three title.
+
+Here's a [link](http://yahoo.com).
+
+This is an unordered list:
+* One.
+* Two.
+* Three.
+EOT
+    )
+
+    use_case.files_to_write.store(
+        INCLUDER_FILE_NAME,
+        <<EOT
+This file includes the markdown file.
+
+@[:markdown](#{includee_file_name})
+
+EOT
+    )
+
+    use_case.files_to_write.store(
+        TEMPLATE_FILE_NAME,
+        <<EOT
+### Include Markdown
+
+Use file inclusion to include markdown.  The whole page, includer and includee, will be rendered when it's pushed to GitHub.
+
+#### File to Be Included
+
+Here's a file containing markdown to be included:
+
+@[markdown](#{includee_file_name})
+
+#### Includer File
+
+Here's a template file that includes it:
+
+@[markdown](#{INCLUDER_FILE_NAME})
+
+The treatment token ```:markdown``` specifies that the included text is to be treated as markdown.
+
+@[:markdown](../interface.md)
+
+#### File with Inclusion
+
+Here's the finished file with the inclusion:
+
+@[markdown](#{INCLUDED_FILE_NAME})
+
+And here's the finished markdown, as rendered on this page:
+
+---
+
+@[:markdown](#{includee_file_name})
+
+---
+EOT
+    )
+
+    use_case.build
+
+  end
+
+end