markdown_helper 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ccb80bcecf1c22af77afe2d8e9e8038fa3859fdd
-  data.tar.gz: 38849d0c824346ecb21402249e542079752e0b51
+  metadata.gz: b7cb1906c0c35ce609ca9b60c12ec703f6b0c399
+  data.tar.gz: 33acb05767e8cf7f49eafcb8363772b37be0d90f
 SHA512:
-  metadata.gz: 7c7ad470f6d1927e95ee82c3e1a2a726a14bed010c3a0e42a873eb2e306377a199775dd9b9e8f717e33f11b127a52d0aa6a12b5994c238bd5698e02b108bc392
-  data.tar.gz: 026bc9fa396418b313f7e4b788ab0ef9fe0e06e3b7eb81d75e849fb44eae6eccda9d1d728afb55a44d94af636d57dbb2160262baf630207e8274dea0d2c20578
+  metadata.gz: d83a737645f7b576cfb65f0dd829f057d4d6e0f8638b5c2f9daba6adb459d0acb740d2a0c32a613d82d0e4916244268556a061b50134b3b22a3e7e9af0457d67
+  data.tar.gz: 004c46825e01715047c21aa8b106f9f3c6857f4fc590550c252b61d97fb579fcb21ccff7eac24c039ec22d0b8b62f9904c30d99169fc05baffc13123b65ec91e

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    markdown_helper (0.1.3)
+    markdown_helper (0.1.4)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -4,11 +4,13 @@
 
 This markdown helper enables file inclusion in GitHub markdown.
 
-(Actually this README file is built using the file inclusion.)
+(Actually, this README file itself is built using file inclusion.)
 
-You can use it to merge external files into a markdown (</code>.md</code>) file.
+Use the markdown helper to merge external files into a markdown (</code>.md</code>) file.
 
-The merged text can be highlighted in a code block:
+### Merged Text Formats
+
+#### Highlighted Code Block
 
 <code>include.rb</code>
 ```ruby
@@ -19,7 +21,7 @@ class RubyCode
 end
 ```
 
-or plain in a code block:
+#### Plain Code Block
 
 <code>include.rb</code>
 ```
@@ -30,37 +32,34 @@ class RubyCode
 end
 ```
 
-or verbatim (which GitHub renders however it likes).
-
-[Note:  RubyGems.org chooses to highlight both code blocks above.  Go figure.]
+[Note:  In the gem documentation, RubyDoc.info chooses to highlight this code block regardless.  Go figure.]
 
-### Usage
+#### Verbatim
 
-#### Specify Include Files with Pragmas
+Verbatim text is included unadorned.  Most often, verbatim text is markdown to be rendered as part of the markdown page.
 
-<code>include.md</code>
-```verbatim
-@[ruby](include.rb)
+### Usage
 
-@[:code_block](include.rb)
+#### CLI
 
-@[:verbatim](include.rb)
+<code>include.txt</code>
 ```
+Usage:
 
-An inclusion pragma has the form:
+  include template_file_path markdown_file_page
 
-<code>@[</code>*treatment*<code>](</code>*relative_file_path*<code>)</code>
+  where
 
-where:
+    * template_file_path is the path to an existing file.
+    * markdown_file_path is the path to a file to be created.
 
-* *treatment* (in square brackets) is one of the following:
-  * 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>[:verbatim]</code>, to include text verbatim (to be rendered as markdown).
-* *relative_file_path* points to the file to be included.
+  Typically:
 
+    * Both file types are .md.
+    * The template file contains file inclusion pragmas.  See README.md.
+```
 
-#### Include the Files with <code>MarkdownHelper#include</code>
+#### API
 
 <code>usage.rb</code>
 ```ruby
@@ -71,3 +70,30 @@ template_file_path = 'highlight_ruby_template.md'
 markdown_file_path = 'highlighted_ruby.rb'
 markdown_helper.include(template_file_path, markdown_file_path)
 ```
+
+#### Include Pragmas
+
+Specify each file inclusion via an *include pragma*, which has the form:
+
+<code>@[</code>*format*<code>](</code>*relative_file_path*<code>)</code>
+
+where:
+
+* *format* (in square brackets) is one of the following:
+  * 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>[:verbatim]</code>, to include text verbatim (to be rendered as markdown).
+* *relative_file_path* points to the file to be included.
+
+##### Example Include Pragmas
+
+<code>include.md</code>
+```verbatim
+@[ruby](my_ruby.rb)
+
+@[:code_block](my_language.xyzzy)
+
+@[:verbatim](my_markdown.md)
+```
+
+

data/bin/include

@@ -0,0 +1,23 @@
+#!/usr/bin/env ruby
+
+require 'markdown_helper'
+
+def usage
+  dir_path = File.dirname(File.absolute_path(__FILE__))
+  file_path = File.join(
+                      dir_path,
+                      'usage',
+                      'include.txt'
+  )
+  puts File.read(file_path)
+  exit
+end
+
+template_file_path, markdown_file_path = ARGV
+
+usage unless ARGV.size == 2
+usage unless File.readable?(template_file_path)
+usage unless File.writable?(File.dirname(markdown_file_path))
+
+MarkdownHelper.new.include(template_file_path, markdown_file_path)
+

data/bin/usage/include.txt

@@ -0,0 +1,13 @@
+Usage:
+
+  include template_file_path markdown_file_page
+
+  where
+
+    * template_file_path is the path to an existing file.
+    * markdown_file_path is the path to a file to be created.
+
+  Typically:
+
+    * Both file types are .md.
+    * The template file contains file inclusion pragmas.  See README.md.

data/lib/markdown_helper/version.rb

@@ -1,3 +1,3 @@
 class MarkdownHelper
-  VERSION = '0.1.3'
+  VERSION = '0.1.4'
 end

data/markdown_helper.gemspec

@@ -1,38 +1,38 @@
-
-lib = File.expand_path('../lib', __FILE__)
-$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require 'markdown_helper/version'
-
-Gem::Specification.new do |spec|
-  spec.name          = 'markdown_helper'
-  spec.version       = MarkdownHelper::VERSION
-  spec.authors       = ['burdettelamar']
-  spec.email         = ['BurdetteLamar@Yahoo.com']
-
-  spec.summary       = 'Class to help with GitHub markdown.'
-  spec.description   = 'Class to help with GitHub markdown.  So far:  file inclusion.'
-  spec.homepage      = 'https://rubygems.org/gems/markdown_helper'
-  spec.license       = 'MIT'
-
-  # Prevent pushing this gem to RubyGems.org. To allow pushes either set the 'allowed_push_host'
-  # to allow pushing to a single host or delete this section to allow pushing to any host.
-  # if spec.respond_to?(:metadata)
-  #   spec.metadata['allowed_push_host'] = 'https://rubygems.org/'
-  #   spec.metadata['allowed_push_host'] = "http://rubygems.org"
-  # else
-  #   raise 'RubyGems 2.0 or newer is required to protect against ' \
-  #     'public gem pushes.'
-  # end
-
-  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
-    f.match(%r{^(test|spec|features)/})
-  end
-  spec.bindir        = 'exe'
-  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
-  spec.require_paths = ['lib']
-
-  spec.add_development_dependency 'bundler', '~> 1.14'
-  spec.add_development_dependency 'rake', '~> 10.0'
-  spec.add_development_dependency 'minitest', '~> 5.0'
-  spec.add_development_dependency 'diff-lcs', '~> 1.3'
-end
+
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'markdown_helper/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'markdown_helper'
+  spec.version       = MarkdownHelper::VERSION
+  spec.authors       = ['burdettelamar']
+  spec.email         = ['BurdetteLamar@Yahoo.com']
+
+  spec.summary       = 'Class to help with GitHub markdown.'
+  spec.description   = 'Class to help with GitHub markdown.  So far:  file inclusion.'
+  spec.homepage      = 'https://rubygems.org/gems/markdown_helper'
+  spec.license       = 'MIT'
+
+  # Prevent pushing this gem to RubyGems.org. To allow pushes either set the 'allowed_push_host'
+  # to allow pushing to a single host or delete this section to allow pushing to any host.
+  # if spec.respond_to?(:metadata)
+  #   spec.metadata['allowed_push_host'] = 'https://rubygems.org/'
+  #   spec.metadata['allowed_push_host'] = "http://rubygems.org"
+  # else
+  #   raise 'RubyGems 2.0 or newer is required to protect against ' \
+  #     'public gem pushes.'
+  # end
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'bundler', '~> 1.14'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'minitest', '~> 5.0'
+  spec.add_development_dependency 'diff-lcs', '~> 1.3'
+end

data/readme/README.template.md

@@ -4,41 +4,52 @@
 
 This markdown helper enables file inclusion in GitHub markdown.
 
-(Actually this README file is built using the file inclusion.)
+(Actually, this README file itself is built using file inclusion.)
 
-You can use it to merge external files into a markdown (</code>.md</code>) file.
+Use the markdown helper to merge external files into a markdown (</code>.md</code>) file.
 
-The merged text can be highlighted in a code block:
+### Merged Text Formats
+
+#### Highlighted Code Block
 
 @[ruby](include.rb)
 
-or plain in a code block:
+#### Plain Code Block
 
 @[:code_block](include.rb)
 
-or verbatim (which GitHub renders however it likes).
+[Note:  In the gem documentation, RubyDoc.info chooses to highlight this code block regardless.  Go figure.]
+
+#### Verbatim
 
-[Note:  RubyGems.org chooses to highlight both code blocks above.  Go figure.]
+Verbatim text is included unadorned.  Most often, verbatim text is markdown to be rendered as part of the markdown page.
 
 ### Usage
 
-#### Specify Include Files with Pragmas
+#### CLI
 
-@[verbatim](include.md)
+@[:code_block](../bin/usage/include.txt)
+
+#### API
+
+@[ruby](usage.rb)
+
+#### Include Pragmas
 
-An inclusion pragma has the form:
+Specify each file inclusion via an *include pragma*, which has the form:
 
-<code>@[</code>*treatment*<code>](</code>*relative_file_path*<code>)</code>
+<code>@[</code>*format*<code>](</code>*relative_file_path*<code>)</code>
 
 where:
 
-* *treatment* (in square brackets) is one of the following:
+* *format* (in square brackets) is one of the following:
   * 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>[:verbatim]</code>, to include text verbatim (to be rendered as markdown).
 * *relative_file_path* points to the file to be included.
 
+##### Example Include Pragmas
+
+@[verbatim](include.md)
 
-#### Include the Files with <code>MarkdownHelper#include</code>
 
-@[ruby](usage.rb)

data/readme/include.md

@@ -1,5 +1,5 @@
-@[ruby](include.rb)
+@[ruby](my_ruby.rb)
 
-@[:code_block](include.rb)
+@[:code_block](my_language.xyzzy)
 
-@[:verbatim](include.rb)
+@[:verbatim](my_markdown.md)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: markdown_helper
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.4
 platform: ruby
 authors:
 - burdettelamar
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-02-20 00:00:00.000000000 Z
+date: 2018-02-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -83,7 +83,9 @@ files:
 - README.md
 - Rakefile
 - bin/console
+- bin/include
 - bin/setup
+- bin/usage/include.txt
 - images/include.png
 - lib/markdown_helper.rb
 - lib/markdown_helper/version.rb