markdown_helper 0.1.8 → 0.1.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f20468d3adaf8f70c7e5ca62a12d3796d11bf615
-  data.tar.gz: 01d3ae966a7217a012eaa2d32e603b233690ea8c
+  metadata.gz: 28b04055b3976d51cdb7324ab249edeb204fe73d
+  data.tar.gz: e28fd32accb586372b69bffb44e15d39665a5397
 SHA512:
-  metadata.gz: f36d06b2272e6d662288040ba56ee9536c617496516606bf304f9f2d890af3d34dfb8fb200fa8de88f10b4f9341e0162688a33060bc34569280ec937b23a5c63
-  data.tar.gz: a5e5ddb4973689fbcee65d977c1c85edb3090d4c2cc74d7b3f8353ccd2b63ef4af3d03b15ed0c006ad40b6ab21f13510a9b176dc5897b6c6d3f1901acd481db1
+  metadata.gz: 977604ef93870d3ae68665c2ca79c5798551a91beb624f364bc73d73d89cccd98b0f8397800faae5707544a4c457ecab2bc782263ffbaa96f32f4262909904dc
+  data.tar.gz: 3a2f4b3bdc24210d883469c4f0694a2d83cba8c9be3e16ab0537918d79a14d85ab77275604ebb1b178875a89be4c63a1125ad4727ce92217fff73fe6e358e803

data/Gemfile.lock

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

data/README.md

@@ -4,7 +4,7 @@
 
 ## File Inclusion 
 
-<img src="https://raw.githubusercontent.com/BurdetteLamar/MarkdownHelper/master/images/include.png" width="50">
+<img src="https://raw.githubusercontent.com/BurdetteLamar/MarkdownHelper/master/images/include.png" alt="include_icon" width="50">
 
 This markdown helper enables file inclusion in GitHub markdown.
 
@@ -65,13 +65,13 @@ Usage:
 
 #### API
 
-<code>usage.rb</code>
+<code>include_usage.rb</code>
 ```ruby
 require 'markdown_helper'
 
 markdown_helper = MarkdownHelper.new
 template_file_path = 'highlight_ruby_template.md'
-markdown_file_path = 'highlighted_ruby.rb'
+markdown_file_path = 'highlighted_ruby.md'
 markdown_helper.include(template_file_path, markdown_file_path)
 ```
 
@@ -92,7 +92,7 @@ where:
 ##### Example Include Pragmas
 
 <code>include.md</code>
-```verbatim
+```code_block
 @[ruby](my_ruby.rb)
 
 @[:code_block](my_language.xyzzy)
@@ -100,4 +100,71 @@ where:
 @[:verbatim](my_markdown.md)
 ```
 
+## Image Path Resolution 
+
+<img src="https://raw.githubusercontent.com/BurdetteLamar/MarkdownHelper/master/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>resolve_image_urls.txt</code>
+```
+Usage:
+
+  resolve_image_urls 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 image relative file paths.  See README.md.
+```
+
+#### API
+
+<code>resolve_image_urls_usage.rb</code>
+```ruby
+require 'markdown_helper'
+
+markdown_helper = MarkdownHelper.new
+template_file_path = 'template.md'
+markdown_file_path = 'markdown.md'
+markdown_helper.resolve_image_urls(template_file_path, markdown_file_path)
+```
+
+#### Image Pragmas
+
+Specify each image file via an *image pragma*, 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.
+
+##### Example Image Pragmas
+
+<code>resolve_image_urls.md</code>
+```code_block
+ ![my_alt](image/image.png)
+
+ ![my_alt](image/image.png | width=50)
+
+ ![my_alt](image/image.png| width=50 height=50)
+```
 

data/Rakefile

@@ -15,6 +15,7 @@ namespace :build do
     markdown_helper = MarkdownHelper.new
     markdown_helper.include('readme_files/highlight_ruby_template.md', 'readme_files/highlighted_ruby.md')
     markdown_helper.include('readme_files/README.template.md', 'README.md')
+    markdown_helper.resolve_image_urls('README.md', 'README.md')
   end
 
 end

data/bin/resolve_image_urls

@@ -0,0 +1,22 @@
+#!/usr/bin/env ruby
+
+require 'markdown_helper'
+
+def usage
+  dir_path = File.dirname(File.absolute_path(__FILE__))
+  file_path = File.join(
+                      dir_path,
+                      'usage',
+                      'resolve_image_urls.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.resolve_image_urls(template_file_path, markdown_file_path)

data/bin/usage/resolve_image_urls.txt

@@ -0,0 +1,13 @@
+Usage:
+
+  resolve_image_urls 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 image relative file paths.  See README.md.

data/images_resolved.md

@@ -0,0 +1,96 @@
+# MarkdownHelper
+
+[![Gem Version](https://badge.fury.io/rb/markdown_helper.svg)](https://badge.fury.io/rb/markdown_helper)
+
+## File Inclusion 
+
+<img src="https://raw.githubusercontent.com/BurdetteLamar/MarkdownHelper/master/images/include.png" alt="include_icon" width="50">
+
+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.
+
+### Merged Text Formats
+
+#### Highlighted Code Block
+
+@[ruby](include.rb)
+
+#### Plain Code Block
+
+@[:code_block](include.rb)
+
+[Note:  In the gem documentation, RubyDoc.info chooses to highlight this code block regardless.  Go figure.]
+
+#### Verbatim
+
+Verbatim text is included unadorned.  Most often, verbatim text is markdown to be rendered as part of the markdown page.
+
+### Usage
+
+#### CLI
+
+@[:code_block](../bin/usage/include.txt)
+
+#### API
+
+@[ruby](include_usage.rb)
+
+#### 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_block](include.md)
+
+## Image Path Resolution 
+
+<img src="https://raw.githubusercontent.com/BurdetteLamar/MarkdownHelper/master/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_image_urls.txt)
+
+#### API
+
+@[ruby](resolve_image_urls_usage.rb)
+
+#### Image Pragmas
+
+Specify each image file via an *image pragma*, 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.
+
+##### Example Image Pragmas
+
+@[code_block](resolve_image_urls.md)
+

data/lib/markdown_helper/version.rb

@@ -1,3 +1,3 @@
 class MarkdownHelper
-  VERSION = '0.1.8'
+  VERSION = '0.1.9'
 end

data/lib/markdown_helper.rb

@@ -6,29 +6,36 @@ require 'markdown_helper/version'
 # @author Burdette Lamar
 class MarkdownHelper
 
-  INCLUDE_REGEXP = /^@\[(:code_block|:verbatim|\w+)\]/
+  IMAGE_REGEXP = /^!\[([^\[]+)\]\(([^)]+)\)/
+  INCLUDE_REGEXP = /^@\[([^\[]+)\]\(([^)]+)\)/
+
+  # Get the user name and repository name from ENV.
+  def repo_user_and_name
+    repo_user = ENV['REPO_USER']
+    repo_name = ENV['REPO_NAME']
+    unless repo_user and repo_name
+      message = 'ENV values for both REPO_USER and REPO_NAME must be defined.'
+      raise RuntimeError.new(message)
+    end
+    [repo_user, repo_name]
+  end
 
   # Merges external files into markdown text.
   # @param template_file_path [String] the path to the input template markdown file, usually containing include pragmas.
   # @param markdown_file_path [String] the path to the output merged markdown file.
-  # @raise [RuntimeError] if an include pragma parsing error occurs.
   # @return [String] the resulting markdown text.
   #
-  # @example Pragma to include text as a highlighted code block.
+  # @example pragma to include text as a highlighted code block.
   #   @[ruby](foo.rb)
   #
-  # @example Pragma to include text as a plain code block.
+  # @example pragma to include text as a plain code block.
   #   @[:code_block](foo.xyz)
   #
-  # @example Pragma to include text verbatim, to be rendered as markdown.
+  # @example pragma to include text verbatim, to be rendered as markdown.
   #   @[:verbatim](foo.md)
   def include(template_file_path, markdown_file_path)
     output_lines = []
     File.open(template_file_path, 'r') do |template_file|
-      # For later.
-      # if tag_as_generated
-      #   output_lines.push("<!--- GENERATED FILE, DO NOT EDIT --->\n")
-      # end
       template_file.each_line do |input_line|
         match_data = input_line.match(INCLUDE_REGEXP)
         unless match_data
@@ -43,11 +50,7 @@ class MarkdownHelper
                       else
                         match_data[1]
                     end
-        file_path_in_parens =  input_line.sub(INCLUDE_REGEXP, '')
-        unless file_path_in_parens.start_with?('(') && file_path_in_parens.end_with?(")\n")
-          raise RuntimeError.new(file_path_in_parens.inspect)
-        end
-        relative_file_path = file_path_in_parens.sub('(', '').sub(")\n", '')
+        relative_file_path = match_data[2]
         include_file_path = File.join(
             File.dirname(template_file_path),
             relative_file_path,
@@ -57,10 +60,6 @@ class MarkdownHelper
           message = "Warning:  Included file has no trailing newline: #{include_file_path}"
           warn(message)
         end
-        # For later.
-        # extname = File.extname(include_file_path)
-        # file_ext_key = extname.sub('.', '').to_sym
-        # treatment ||= @treatment_for_file_ext[file_ext_key]
         if treatment == :verbatim
           # Pass through unadorned.
           output_lines.push(included_text)
@@ -83,4 +82,60 @@ class MarkdownHelper
     output
   end
 
-end
+  # Resolves relative image paths to absolute urls in markdown text.
+  # @param template_file_path [String] the path to the input template markdown file, usually containing image pragmas.
+  # @param markdown_file_path [String] the path to the output resolved markdown file.
+  # @return [String] the resulting markdown text.
+  #
+  # 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 paths.
+  # The resolved (absolute) urls, however, will still be valid.
+  #
+  # ENV['REPO_USER'] and ENV['REPO_NAME'] must give the user name and repository name of the relevant GitHub repository.
+  #  must give the repo name of the relevant GitHub repository.
+  #
+  # @example pragma for an image:
+  #   ![image_icon](images/image.png)
+  #
+  # The path resolves to:
+  #
+  #   absolute_file_path = File.join(
+  #       "https://raw.githubusercontent.com/#{repo_user}/#{repo_name}/master",
+  #       relative_file_path,
+  #   )
+  def resolve_image_urls(template_file_path, markdown_file_path)
+    output_lines = []
+    File.open(template_file_path, 'r') do |template_file|
+      output_lines = []
+      template_file.each_line do |input_line|
+        match_data = input_line.match(IMAGE_REGEXP)
+        unless match_data
+          output_lines.push(input_line)
+          next
+        end
+        alt_text = match_data[1]
+        relative_file_path, attributes_s = match_data[2].split(/\s?\|\s?/, 2)
+        attributes = attributes_s ? attributes_s.split(/\s+/) : []
+        formatted_attributes = ['']
+        attributes.each do |attribute|
+          name, value = attribute.split('=', 2)
+          formatted_attributes.push(format('%s="%s"', name, value))
+        end
+        formatted_attributes_s = formatted_attributes.join(' ')
+        repo_user, repo_name = repo_user_and_name
+        absolute_file_path = File.join(
+            "https://raw.githubusercontent.com/#{repo_user}/#{repo_name}/master",
+            relative_file_path,
+        )
+        line = format('<img src="%s" alt="%s"%s>', absolute_file_path, alt_text, formatted_attributes_s) + "\n"
+        output_lines.push(line)
+      end
+    end
+    output = output_lines.join('')
+    File.open(markdown_file_path, 'w') do |md_file|
+      md_file.write(output)
+    end
+    output
+  end
+
+end

data/readme_files/README.template.md

@@ -4,7 +4,7 @@
 
 ## File Inclusion 
 
-<img src="https://raw.githubusercontent.com/BurdetteLamar/MarkdownHelper/master/images/include.png" width="50">
+![include_icon](images/include.png | width=50)
 
 This markdown helper enables file inclusion in GitHub markdown.
 
@@ -36,7 +36,7 @@ Verbatim text is included unadorned.  Most often, verbatim text is markdown to b
 
 #### API
 
-@[ruby](usage.rb)
+@[ruby](include_usage.rb)
 
 #### Include Pragmas
 
@@ -54,6 +54,43 @@ where:
 
 ##### Example Include Pragmas
 
-@[verbatim](include.md)
+@[code_block](include.md)
 
+## Image Path Resolution 
+
+![image_icon](images/image.png | 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_image_urls.txt)
+
+#### API
+
+@[ruby](resolve_image_urls_usage.rb)
+
+#### Image Pragmas
+
+Specify each image file via an *image pragma*, 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.
+
+##### Example Image Pragmas
+
+@[code_block](resolve_image_urls.md)
 

data/readme_files/{usage.rb → include_usage.rb}

@@ -2,5 +2,5 @@ require 'markdown_helper'
 
 markdown_helper = MarkdownHelper.new
 template_file_path = 'highlight_ruby_template.md'
-markdown_file_path = 'highlighted_ruby.rb'
+markdown_file_path = 'highlighted_ruby.md'
 markdown_helper.include(template_file_path, markdown_file_path)

data/readme_files/resolve_image_urls.md

@@ -0,0 +1,5 @@
+ ![my_alt](image/image.png)
+
+ ![my_alt](image/image.png | width=50)
+
+ ![my_alt](image/image.png| width=50 height=50)

data/readme_files/resolve_image_urls_usage.rb

@@ -0,0 +1,6 @@
+require 'markdown_helper'
+
+markdown_helper = MarkdownHelper.new
+template_file_path = 'template.md'
+markdown_file_path = 'markdown.md'
+markdown_helper.resolve_image_urls(template_file_path, markdown_file_path)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: markdown_helper
 version: !ruby/object:Gem::Version
-  version: 0.1.8
+  version: 0.1.9
 platform: ruby
 authors:
 - burdettelamar
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-03-06 00:00:00.000000000 Z
+date: 2018-03-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -84,9 +84,13 @@ files:
 - Rakefile
 - bin/console
 - bin/include
+- bin/resolve_image_urls
 - bin/setup
 - bin/usage/include.txt
+- bin/usage/resolve_image_urls.txt
+- images/image.png
 - images/include.png
+- images_resolved.md
 - lib/markdown_helper.rb
 - lib/markdown_helper/version.rb
 - markdown_helper.gemspec
@@ -96,7 +100,9 @@ files:
 - readme_files/highlighted_ruby.md
 - readme_files/include.md
 - readme_files/include.rb
-- readme_files/usage.rb
+- readme_files/include_usage.rb
+- readme_files/resolve_image_urls.md
+- readme_files/resolve_image_urls_usage.rb
 - readme_files/verbatim_ruby_template.md
 homepage: https://github.com/BurdetteLamar/MarkdownHelper
 licenses: