markdown_helper 1.8.0 → 1.9.0

data/markdown/use_cases/include/include_with_added_comments/{template.md → use_case_template.md}

@@ -13,12 +13,31 @@ By default (that is, without option ```--pristine```) file inclusion adds commen
 
 @[markdown](includer.md)
 
-#### Inclusion Command
+#### CLI
+
+You can use the command-line interface to perform the inclusion.
+
+##### Command
 
 ```sh
 markdown_helper include includer.md included.md
 ```
 
+#### API
+
+You can use the API to perform the inclusion.
+
+##### Ruby Code
+
+```ruby
+require 'markdown_helper'
+
+markdown_helper = MarkdownHelper.new
+markdown_helper.include(includer.md, included.md)
+```
+
 #### File with Inclusion and Added Comments
 
 @[markdown](included.md)
+
+The file path for the included file is relative to the .git directory.

data/markdown/use_cases/include/interface.md

@@ -0,0 +1,25 @@
+#### CLI
+
+You can use the command-line interface to perform the inclusion.
+
+##### Command
+
+```sh
+markdown_helper include --pristine includer.md included.md
+```
+
+@[:markdown](../pristine.md)
+
+#### API
+
+You can use the API to perform the inclusion.
+
+##### Ruby Code
+
+@[ruby](include.rb)
+
+##### Command
+
+```sh
+ruby include.rb
+```

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

@@ -0,0 +1,5 @@
+File to do nested inclusion.
+
+Text for inclusion, and a nested inclusion.
+
+Text for nested inclusion.

data/markdown/use_cases/include/nest_inclusions/includee.md

@@ -0,0 +1,3 @@
+Text for inclusion, and a nested inclusion.
+
+@[:markdown](nested_includee.md)

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

@@ -0,0 +1,3 @@
+File to do nested inclusion.
+
+@[:markdown](includee.md)

data/markdown/use_cases/include/nest_inclusions/nest_inclusions.rb

@@ -0,0 +1,61 @@
+require_relative '../include_use_case'
+
+class NestInclusions < IncludeUseCase
+
+  def self.build
+
+    use_case_name = File.basename(__FILE__, 'rb')
+    use_case = self.new(use_case_name)
+
+    nested_includee_file_name = 'nested_includee.md'
+
+    use_case.files_to_write.store(
+        nested_includee_file_name,
+        <<EOT
+Text for nested inclusion.
+EOT
+    )
+
+    use_case.files_to_write.store(
+        INCLUDER_FILE_NAME,
+        <<EOT
+File to do nested inclusion.
+
+@[:markdown](#{INCLUDEE_FILE_NAME})
+EOT
+    )
+
+    use_case.files_to_write.store(
+        TEMPLATE_FILE_NAME,
+        <<EOT
+### Nest Inclusions
+
+An included markdown file can itself include more files.
+
+#### File To Be Included
+
+@[markdown](#{INCLUDEE_FILE_NAME})
+
+#### File For Nested Inclusion
+
+@[markdown](#{nested_includee_file_name})
+
+#### Includer File
+
+@[markdown](#{INCLUDER_FILE_NAME})
+
+@[:markdown](../interface.md)
+
+#### File with Inclusion
+
+Here's the finished file with the inclusion and nested inclusion:
+
+@[markdown](#{INCLUDED_FILE_NAME})
+EOT
+    )
+
+    use_case.build
+
+  end
+
+end

data/markdown/use_cases/include/nest_inclusions/nested_includee.md

@@ -0,0 +1 @@
+Text for nested inclusion.

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

@@ -0,0 +1,74 @@
+### Nest Inclusions
+
+An included markdown file can itself include more files.
+
+#### File To Be Included
+
+```includee.md```:
+```markdown
+Text for inclusion, and a nested inclusion.
+
+@[:markdown](nested_includee.md)
+```
+
+#### File For Nested Inclusion
+
+```nested_includee.md```:
+```markdown
+Text for nested inclusion.
+```
+
+#### Includer File
+
+```includer.md```:
+```markdown
+File to do nested inclusion.
+
+@[:markdown](includee.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
+```
+
+#### File with Inclusion
+
+Here's the finished file with the inclusion and nested inclusion:
+
+```included.md```:
+```markdown
+File to do nested inclusion.
+
+Text for inclusion, and a nested inclusion.
+
+Text for nested inclusion.
+```

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

@@ -0,0 +1,23 @@
+### Nest Inclusions
+
+An included markdown file can itself include more files.
+
+#### File To Be Included
+
+@[markdown](includee.md)
+
+#### File For Nested Inclusion
+
+@[markdown](nested_includee.md)
+
+#### Includer File
+
+@[markdown](includer.md)
+
+@[:markdown](../interface.md)
+
+#### File with Inclusion
+
+Here's the finished file with the inclusion and nested inclusion:
+
+@[markdown](included.md)

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

@@ -1,7 +1,4 @@
-This file includes the useful text.
+Text in includer file.
 
-This is some reusable text that can be included in more than one place (actually, in more than one file).
+Text in includee file.
 
-Then includes it again.
-
-This is some reusable text that can be included in more than one place (actually, in more than one file).

data/markdown/use_cases/include/reuse_text/includee.md

@@ -0,0 +1 @@
+Text in includee file.

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

@@ -1,7 +1,4 @@
-This file includes the useful text.
+Text in includer file.
 
-@[:markdown](reusable_text.md)
+@[:markdown](includee.md)
 
-Then includes it again.
-
-@[:markdown](reusable_text.md)

data/markdown/use_cases/include/reuse_text/reuse_text.rb

@@ -1,100 +1,47 @@
-#!/usr/bin/env ruby
-
-use_case_dir_path = File.absolute_path(File.dirname(__FILE__))
-
-reusable_text_file_name = 'reusable_text.md'
-reusable_text_file_path = File.join(
-    use_case_dir_path,
-    reusable_text_file_name,
-)
-
-includer_file_name = 'includer.md'
-includer_file_path = File.join(
-    use_case_dir_path,
-    includer_file_name,
-)
-
-included_file_name = 'included.md'
-
-use_case_file_name = 'reuse_text.md'
-use_case_file_path = File.join(
-    use_case_dir_path,
-    use_case_file_name,
-)
-
-template_file_name = 'template.md'
-template_file_path = File.join(
-    use_case_dir_path,
-    template_file_name,
-)
-
-include_command = "markdown_helper include --pristine #{includer_file_name} #{included_file_name}"
-
-File.write(
-    reusable_text_file_path,
-    <<EOT
-This is some reusable text that can be included in more than one place (actually, in more than one file).
-EOT
-)
-
-
-File.write(
-    includer_file_path,
-    <<EOT
-This file includes the useful text.
+require_relative '../include_use_case'
 
-@[:markdown](#{reusable_text_file_name})
+class ReuseText < IncludeUseCase
 
-Then includes it again.
+  def self.build
 
-@[:markdown](#{reusable_text_file_name})
-EOT
-)
+    use_case_name = File.basename(__FILE__, '.rb')
+    use_case = self.new(use_case_name)
 
-# Example inclusion.
-Dir.chdir(use_case_dir_path) do
-  system(include_command)
-end
+    use_case.write_includee_file
+    use_case.write_includer_file
+    use_case.write_ruby_file(pristine = true)
 
-File.write(
-    template_file_path,
-    <<EOT
+    File.write(
+        TEMPLATE_FILE_NAME,
+        <<EOT
 ### Reuse Text
 
 Use file inclusion to stay DRY (Don't Repeat Yourself).
 
 Maintain reusable text in a separate file, then include it wherever it's needed.
 
-#### File to Be Included
-
-Here's a file containing some text that can be included:
+#### File To Be Included
 
-@[markdown](#{reusable_text_file_name})
+@[markdown](#{INCLUDEE_FILE_NAME})
 
 #### Includer File
 
-Here's a template file that includes it:
+@[markdown](#{INCLUDER_FILE_NAME})
 
-@[markdown](#{includer_file_name})
+The treatment token ```:markdown``` specifies that the included text is to be treated as more markdown.
 
-#### Command
-
-Here's the command to perform the inclusion:
-
-```sh
-#{include_command}
-```
-
-@[:markdown](../../pristine.md)
+@[:markdown](../interface.md)
 
 #### File with Inclusion
 
-Here's the finished file with the inclusion:
+Here's the output file, after inclusion.
 
-@[markdown](#{included_file_name})
+@[markdown](#{INCLUDED_FILE_NAME})
 EOT
-)
+    )
 
-# Build use case.
-build_command = "markdown_helper include --pristine #{template_file_path} #{use_case_file_path}"
-system(build_command)
+    use_case.build
+
+  end
+
+end

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

@@ -0,0 +1,69 @@
+### Reuse Text
+
+Use file inclusion to stay DRY (Don't Repeat Yourself).
+
+Maintain reusable text in a separate file, then include it wherever it's needed.
+
+#### File To Be Included
+
+```includee.md```:
+```markdown
+Text in includee file.
+```
+
+#### Includer File
+
+```includer.md```:
+```markdown
+Text in includer file.
+
+@[:markdown](includee.md)
+
+```
+
+The treatment token ```:markdown``` specifies that the included text is to be treated as more markdown.
+
+#### 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 output file, after inclusion.
+
+```included.md```:
+```markdown
+Text in includer file.
+
+Text in includee file.
+
+```