markdown_helper 2.1.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cee806406f109c72b11a7a4f78c8ad7efc59706f278a0a5b654267e3ae38ddf6
-  data.tar.gz: 4e49e14011eb429bd5d523a314572aff3693876b07fa50b52d9cfecf693fcd3d
+  metadata.gz: '09204d578d4034b5940afc983b9d3989adff2d1b05763b0e6e867e3183b338c8'
+  data.tar.gz: a90232dc47c8d901f1fa1a5bed7964e0deee6fb3b3bd9d2713f46ea105b162b2
 SHA512:
-  metadata.gz: 5d4c4a25171b3ac8df8cfd84766843ae7c8d599c896d70b1d70854353dc7f0cb06741d1832640f5f24fdc500285bf16684f09d7d08450a48c73680d0033cab9f
-  data.tar.gz: 5f81f39ad84273fa2367a03e7bc18773190c97398ff7ac3c8834eac464a2a9dbe8bbedbf566fee79489124d2458fc32bfec96534b85f2edd4a7cadbb1e5dd63c
+  metadata.gz: ad9d3e8cbf0a1fa17eba25579c02165571e5408ea979747600aa6db74b52122fd2157d61d6f2a65e7302eac52a443e40343d10d0c291eae7912d64ccd099ed6f
+  data.tar.gz: 4ee21575e5d049259b9c365ab9842d904127ebe8df9f023304bcb35c34242f3eb81edf37a055aee6cdce61283c635fb4d38bb4ffbfa7cdc54f6b7f8584fb8672

data/Gemfile.lock

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

data/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2018 Burdette Lamar
+Copyright (c) 2018-2019 Burdette Lamar
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,16 +1,11 @@
-<!-- >>>>>> BEGIN GENERATED FILE (include): SOURCE README.template.md -->
+<!-- >>>>>> BEGIN GENERATED FILE (include): SOURCE markdown/readme/README.template.md -->
 # Markdown Helper
 
 [![Gem](https://img.shields.io/gem/v/markdown_helper.svg?style=flat)](http://rubygems.org/gems/markdown_helper "View this project in Rubygems")
 
 ## What's New?
 
-Page TOC (table of contents) is improved:
-
-- **Old**:  You would first run the markdown helper to generate a page TOC, then run the helper a second time to include the page TOC where you want it.
-- **New**:  You specify the site for the page TOC in the page itself, and the page TOC is automatically generated and inserted there.  See the [use case](markdown/use_cases/include_files/include_page_toc/use_case.md#include-page-toc)
-
-The old way is now deprecated.
+Command line creation of page TOC (table of contents), previously deprecated, is removed.
 
 ## Contents
 - [What's a Markdown Helper?](#whats-a-markdown-helper)
@@ -172,7 +167,7 @@ where:
 
 <!-- >>>>>> BEGIN INCLUDED FILE (code_block): SOURCE markdown/readme/include.md -->
 ```include.md```:
-```code_block
+```
 @[ruby](my_ruby.rb)
 
 @[:code_block](my_language.xyzzy)
@@ -213,4 +208,4 @@ I have opened some enhancement Issues in the GitHub [markdown_helper](https://gi
 * [Pagination](https://github.com/BurdetteLamar/markdown_helper/issues/40):  series of markdown pages connected by prev/next navigation links.
 
 Feel free to comment on any of these, or to add more Issues (enhancement or otherwise).
-<!-- <<<<<< END GENERATED FILE (include): SOURCE README.template.md -->
+<!-- <<<<<< END GENERATED FILE (include): SOURCE markdown/readme/README.template.md -->

data/Rakefile

@@ -26,7 +26,6 @@ namespace :build do
   desc 'Build usage for executables'
   task :usages do
     %w/
-        create_page_toc
         include
     /.each do |executable_name|
       usage_text = `ruby bin/_#{executable_name} --help`

data/lib/markdown_helper.rb

@@ -1,19 +1,20 @@
 require 'pathname'
+
 require 'markdown_helper/version'
 
 class MarkdownHelper
 
   class MarkdownHelperError < RuntimeError; end
-  class CircularIncludeError < MarkdownHelperError; end
-  class UnreadableInputError < MarkdownHelperError; end
-  class TocHeadingsError < MarkdownHelperError; end
   class OptionError < MarkdownHelperError; end
-  class EnvironmentError < MarkdownHelperError; end
-  class InvalidTocTitleError < MarkdownHelperError; end
-  class MisplacedPageTocError < MarkdownHelperError; end
   class MultiplePageTocError < MarkdownHelperError; end
+  class InvalidTocTitleError < MarkdownHelperError; end
+  class UnreadableTemplateError < MarkdownHelperError; end
+  class UnwritableMarkdownError < MarkdownHelperError; end
+  class CircularIncludeError < MarkdownHelperError; end
+  class UnreadableIncludeeError < MarkdownHelperError; end
 
   INCLUDE_REGEXP = /^@\[([^\[]+)\]\(([^)]+)\)$/
+  INCLUDE_MARKDOWN_REGEXP = /^@\[:markdown\]\(([^)]+)\)$/
 
   attr_accessor :pristine
 
@@ -35,187 +36,192 @@ class MarkdownHelper
       send(setter_method, value)
       merged_options.delete(method)
     end
+    @inclusions = []
   end
 
   def include(template_file_path, markdown_file_path)
-    send(:generate_file, template_file_path, markdown_file_path, __method__) do |input_lines, output_lines|
-      send(:include_files, template_file_path, input_lines, output_lines, Inclusions.new)
-    end
-  end
-
-  def create_page_toc(markdown_file_path, toc_file_path)
-    message = <<EOT
-Method create_page_toc is deprecated.
-Please use method include with embedded :page_toc treatment.
-See https://github.com/BurdetteLamar/markdown_helper/blob/master/markdown/use_cases/include_files/include_page_toc/use_case.md#include-page-toc.
-EOT
-    warn(message)
-    send(:generate_file, markdown_file_path, toc_file_path, __method__) do |input_lines, output_lines|
-      send(:_create_page_toc, input_lines, output_lines)
+    send(:generate_file, template_file_path, markdown_file_path) do |output_lines|
+      Dir.chdir(File.dirname(template_file_path)) do
+        markdown_lines = include_markdown(template_file_path)
+        markdown_lines = include_page_toc(markdown_lines)
+        include_all(template_file_path, markdown_lines, output_lines)
+      end
     end
   end
 
   private
 
-  class Heading
-
-    attr_accessor :level, :title
-
-    def initialize(level, title)
-      self.level = level
-      self.title = title
-    end
-
-    def self.parse(line)
-      # Four leading spaces not allowed (but three are allowed).
-      return nil if line.start_with?(' ' * 4)
-      stripped_line = line.sub(/^ */, '')
-      # Now must begin with hash marks and space.
-      return nil unless stripped_line.match(/^#+ /)
-      hash_marks, title = stripped_line.split(' ', 2)
-      level = hash_marks.size
-      # Seventh level heading not allowed.
-      return nil if level > 6
-      self.new(level, title)
-    end
-
-
-    def link
-      remove_regexp = /[\#\(\)\[\]\{\}\.\?\+\*\`\"\']+/
-      to_hyphen_regexp = /\W+/
-      anchor = title.
-          gsub(remove_regexp, '').
-          gsub(to_hyphen_regexp, '-').
-          downcase
-      "[#{title}](##{anchor})"
+  def generate_file(template_file_path, markdown_file_path)
+    template_path_in_project = MarkdownHelper.path_in_project(template_file_path)
+    output_lines = []
+    yield output_lines
+    unless pristine
+      output_lines.unshift(MarkdownHelper.comment(" >>>>>> BEGIN GENERATED FILE (include): SOURCE #{template_path_in_project} "))
+      output_lines.push(MarkdownHelper.comment(" <<<<<< END GENERATED FILE (include): SOURCE #{template_path_in_project} "))
     end
-
+    output_lines.push('')
+    output = output_lines.join("\n")
+    File.write(markdown_file_path, output)
   end
 
-  def self.comment(text)
-    "<!--#{text}-->\n"
-  end
-
-  def generate_file(template_file_path, markdown_file_path, method)
-    unless File.readable?(template_file_path)
-      message = [
-          Inclusions::UNREADABLE_INPUT_EXCEPTION_LABEL,
-          template_file_path.inspect,
-      ].join("\n")
-      raise UnreadableInputError.new(message)
-    end
-    output_lines = []
-    File.open(template_file_path, 'r') do |template_file|
-      template_path_in_project = MarkdownHelper.path_in_project(template_file_path)
-      output_lines.push(MarkdownHelper.comment(" >>>>>> BEGIN GENERATED FILE (#{method.to_s}): SOURCE #{template_path_in_project} ")) unless pristine
-      input_lines = template_file.readlines
-      yield input_lines, output_lines
-      output_lines.push(MarkdownHelper.comment(" <<<<<< END GENERATED FILE (#{method.to_s}): SOURCE #{template_path_in_project} ")) unless pristine
-    end
-    File.open(markdown_file_path, 'w') do |file|
-      output_lines.each do |line|
-        file.write(line)
+  def include_markdown(template_file_path)
+    Dir.chdir(File.dirname(template_file_path)) do
+      markdown_lines = []
+      unless File.readable?(template_file_path)
+        message = [
+            'Could not read template file:',
+            MarkdownHelper.backtrace_inclusions(@inclusions),
+        ].join("\n")
+        e = UnreadableTemplateError.new(message)
+        e.set_backtrace([])
+        raise e
+      end
+      template_lines = File.readlines(template_file_path)
+      template_lines.each_with_index do |template_line, i|
+        template_line.chomp!
+        treatment, includee_file_path = *parse_include(template_line)
+        if treatment.nil?
+          markdown_lines.push(template_line)
+          next
+        end
+        if treatment == ':page_toc'
+          markdown_lines.push(template_line)
+          next
+        end
+        inclusion = Inclusion.new(
+            template_file_path,
+            template_line,
+            i,
+            treatment,
+            includee_file_path,
+            @inclusions
+            )
+        treatment.sub!(/^:/, '')
+        case treatment
+        when 'markdown'
+          check_includee(inclusion)
+          check_circularity(inclusion)
+          @inclusions.push(inclusion)
+          includee_lines = include_markdown(File.absolute_path(includee_file_path))
+          markdown_lines.concat(includee_lines)
+        when 'comment'
+          text = File.read(includee_file_path)
+          markdown_lines.push(MarkdownHelper.comment(text))
+          @inclusions.push(inclusion)
+        when 'pre'
+          text = File.read(includee_file_path)
+          markdown_lines.push(MarkdownHelper.pre(text))
+          @inclusions.push(inclusion)
+        else
+          markdown_lines.push(template_line)
+          next
+        end
+        @inclusions.pop
+        add_inclusion_comments(treatment, includee_file_path, markdown_lines)
       end
+      markdown_lines
     end
   end
 
-  def _create_page_toc(input_lines, output_lines)
+  def include_page_toc(template_lines)
+    toc_line_index = nil
+    toc_title = nil
+    template_lines.each_with_index do |template_line, i|
+      match_data = template_line.match(INCLUDE_REGEXP)
+      next unless match_data
+      treatment = match_data[1]
+      next unless treatment == ':page_toc'
+      unless toc_line_index.nil?
+        message = 'Multiple page TOC not allowed'
+        raise MultiplePageTocError.new(message)
+      end
+      toc_line_index = i
+      toc_title = match_data[2]
+      title_regexp = /^\#{1,6}\s/
+      unless toc_title.match(title_regexp)
+        message = "TOC title must be a valid markdown header, not #{toc_title}"
+        raise InvalidTocTitleError.new(message)
+      end
+    end
+    return template_lines unless toc_line_index
+    toc_lines = [toc_title]
     first_heading_level = nil
-    input_lines.each do |input_line|
+    template_lines.each_with_index do |input_line, i|
+      next if i < toc_line_index
       line = input_line.chomp
       heading = Heading.parse(line)
       next unless heading
       first_heading_level ||= heading.level
       indentation = '  ' * (heading.level - first_heading_level)
-      output_line = "#{indentation}- #{heading.link}"
-      output_lines.push("#{output_line}\n")
+      toc_line = "#{indentation}- #{heading.link}"
+      toc_lines.push(toc_line)
     end
+    template_lines.delete_at(toc_line_index)
+    template_lines.insert(toc_line_index, *toc_lines)
+    template_lines
   end
 
-  def include_files(includer_file_path, input_lines, output_lines, inclusions)
-    markdown_lines = []
-    page_toc_inclusion = nil
-    input_lines.each_with_index do |input_line, line_index|
-      match_data = input_line.match(INCLUDE_REGEXP)
-      unless match_data
-        markdown_lines.push(input_line)
+  def include_all(template_file_path, template_lines, output_lines)
+    template_lines.each_with_index do |template_line, i|
+      treatment, includee_file_path = *parse_include(template_line)
+      if treatment.nil?
+        output_lines.push(template_line)
         next
       end
-      treatment = match_data[1]
-      cited_includee_file_path = match_data[2]
-      new_inclusion = Inclusion.new(
-          input_line.chomp,
-          includer_file_path,
-          line_index + 1,
-          cited_includee_file_path,
-          treatment
+      inclusion = Inclusion.new(
+          template_file_path,
+          template_line,
+          i,
+          treatment,
+          includee_file_path,
+          @inclusions
       )
-      case treatment
-      when ':markdown'
-        inclusions.include(
-            new_inclusion,
-            markdown_lines,
-            self
-        )
-      when ':page_toc'
-        unless inclusions.inclusions.size == 0
-          message = 'Page TOC must be in outermost markdown file.'
-          raise MisplacedPageTocError.new(message)
-        end
-        unless page_toc_inclusion.nil?
-          message = 'Only one page TOC allowed.'
-          raise MultiplePageTocError.new(message)
-        end
-        page_toc_inclusion = new_inclusion
-        toc_title = match_data[2]
-        title_regexp = /^\#{1,6}\s/
-        unless toc_title.match(title_regexp)
-          message = "TOC title must be a valid markdown header, not #{toc_title}"
-          raise InvalidTocTitleError.new(message)
-        end
-        page_toc_inclusion.page_toc_title = toc_title
-        page_toc_inclusion.page_toc_line = input_line
-        markdown_lines.push(input_line)
-      else
-        markdown_lines.push(input_line)
-      end
-    end
-    # If needed, create page TOC and insert into markdown_lines.
-    unless page_toc_inclusion.nil?
-      toc_lines = [
-          page_toc_inclusion.page_toc_title + "\n",
-          '',
-      ]
-      page_toc_index =  markdown_lines.index(page_toc_inclusion.page_toc_line)
-      lines_to_scan = markdown_lines[page_toc_index + 1..-1]
-      _create_page_toc(lines_to_scan, toc_lines)
-      markdown_lines.delete_at(page_toc_index)
-      markdown_lines.insert(page_toc_index, *toc_lines)
+      check_includee(inclusion)
+      @inclusions.push(inclusion)
+      file_marker = format('```%s```:', File.basename(includee_file_path))
+      begin_backticks = '```'
+      end_backticks = '```'
+      begin_backticks += treatment unless treatment.start_with?(':')
+      includee_lines = File.read(includee_file_path).split("\n")
+      includee_lines.unshift(begin_backticks)
+      includee_lines.unshift(file_marker)
+      includee_lines.push(end_backticks)
+      add_inclusion_comments(treatment.sub(':', ''), includee_file_path, includee_lines)
+      output_lines.concat(includee_lines)
     end
-    # Now review the markdown and include everything.
-    markdown_lines.each_with_index do |markdown_line, line_index|
-      match_data = markdown_line.match(INCLUDE_REGEXP)
-      unless match_data
-        output_lines.push(markdown_line)
-        next
-      end
-      treatment = match_data[1]
-      cited_includee_file_path = match_data[2]
-      new_inclusion = Inclusion.new(
-          markdown_line.chomp,
-          includer_file_path,
-          line_index + 1,
-          cited_includee_file_path,
-          treatment
-      )
-      inclusions.include(
-          new_inclusion,
-          output_lines,
-          self
-      )
+  end
+
+  def add_inclusion_comments(treatment, includee_file_path, lines)
+    path_in_project = MarkdownHelper.path_in_project(includee_file_path)
+    unless pristine
+      comment = format(' >>>>>> BEGIN INCLUDED FILE (%s): SOURCE %s ', treatment, path_in_project)
+      lines.unshift(MarkdownHelper.comment(comment))
+      comment = format(' <<<<<< END INCLUDED FILE (%s): SOURCE %s ', treatment, path_in_project)
+      lines.push(MarkdownHelper.comment(comment))
     end
   end
 
+  def parse_include(line)
+    match_data = line.match(INCLUDE_REGEXP)
+    return [nil, nil] unless match_data
+    treatment = match_data[1]
+    includee_file_path = match_data[2]
+    [treatment, includee_file_path]
+  end
+
+  def self.path_in_project(file_path)
+    abs_path = File.absolute_path(file_path)
+    abs_path.sub(self.git_clone_dir_path + '/', '')
+  end
+
+  def self.comment(text)
+    "<!--#{text}-->"
+  end
+
+  def self.pre(text)
+    "<pre>\n#{text}</pre>"
+  end
+
   def self.git_clone_dir_path
     git_dir = `git rev-parse --show-toplevel`.chomp
     unless $?.success?
@@ -229,157 +235,122 @@ EOT
     git_dir
   end
 
-  def self.path_in_project(path)
-    path.sub(MarkdownHelper.git_clone_dir_path + '/', '')
-  end
+  class Heading
 
-  class Inclusions
+    attr_accessor :level, :title
 
-    attr_accessor :inclusions
+    def initialize(level, title)
+      self.level = level
+      self.title = title
+    end
 
-    def initialize
-      self.inclusions = []
+    def self.parse(line)
+      # Four leading spaces not allowed (but three are allowed).
+      return nil if line.start_with?(' ' * 4)
+      stripped_line = line.sub(/^ */, '')
+      # Now must begin with hash marks and space.
+      return nil unless stripped_line.match(/^#+ /)
+      hash_marks, title = stripped_line.split(' ', 2)
+      level = hash_marks.size
+      # Seventh level heading not allowed.
+      return nil if level > 6
+      self.new(level, title)
     end
 
-    def include(
-      new_inclusion,
-      output_lines,
-      markdown_helper
-    )
-      treatment = case new_inclusion.treatment
-                    when ':code_block'
-                      :code_block
-                    when ':markdown'
-                      :markdown
-                    when ':verbatim'
-                      message = "Treatment ':verbatim' is deprecated; please use treatment ':markdown'."
-                      warn(message)
-                      :markdown
-                    when ':comment'
-                      :comment
-                    when ':pre'
-                      :pre
-                    else
-                      new_inclusion.treatment
-                  end
-      if treatment == :markdown
-        check_circularity(new_inclusion)
-      end
-       includee_path_in_project = MarkdownHelper.path_in_project(new_inclusion.absolute_includee_file_path)
-      output_lines.push(MarkdownHelper.comment(" >>>>>> BEGIN INCLUDED FILE (#{treatment}): SOURCE #{includee_path_in_project} ")) unless markdown_helper.pristine
-      begin
-        include_lines = File.readlines(new_inclusion.absolute_includee_file_path)
-      rescue => e
-        inclusions.push(new_inclusion)
-        message = [
-            MISSING_INCLUDEE_EXCEPTION_LABEL,
-            backtrace_inclusions,
-        ].join("\n")
-        e = UnreadableInputError.new(message)
-        e.set_backtrace([])
-        raise e
-      end
-      last_line = include_lines.last
-      unless last_line && last_line.match("\n")
-        message = "Warning:  Included file has no trailing newline: #{new_inclusion.cited_includee_file_path}"
-        warn(message)
-      end
-      case treatment
-        when :markdown
-          # Pass through unadorned, but honor any nested includes.
-          inclusions.push(new_inclusion)
-          markdown_helper.send(:include_files, new_inclusion.absolute_includee_file_path, include_lines, output_lines, self)
-          inclusions.pop
-        when :comment
-          output_lines.push(MarkdownHelper.comment(include_lines.join('')))
-        when :pre
-          output_lines.push("<pre>\n")
-          output_lines.push(include_lines.join(''))
-          output_lines.push("</pre>\n")
-        else
-          # Use the file name as a label.
-          file_name_line = format("```%s```:\n", File.basename(new_inclusion.cited_includee_file_path))
-          output_lines.push(file_name_line)
-          # Put into code block.
-          language = treatment == :code_block ? '' : treatment
-          output_lines.push("```#{language}\n")
-          output_lines.push(*include_lines)
-          output_lines.push("```\n")
-      end
-      output_lines.push(MarkdownHelper.comment(" <<<<<< END INCLUDED FILE (#{treatment}): SOURCE #{includee_path_in_project} ")) unless markdown_helper.pristine
+
+    def link
+      remove_regexp = /[\#\(\)\[\]\{\}\.\?\+\*\`\"\']+/
+      to_hyphen_regexp = /\W+/
+      anchor = title.
+          gsub(remove_regexp, '').
+          gsub(to_hyphen_regexp, '-').
+          downcase
+      "[#{title}](##{anchor})"
     end
 
-    CIRCULAR_EXCEPTION_LABEL = 'Includes are circular:'
-    UNREADABLE_INPUT_EXCEPTION_LABEL = 'Could not read input file.'
-    UNWRITABLE_OUTPUT_EXCEPTION_LABEL = 'Could not write output file.'
-    MISSING_INCLUDEE_EXCEPTION_LABEL = 'Could not read include file,'
-    LEVEL_LABEL = '    Level'
-    BACKTRACE_LABEL = '  Backtrace (innermost include first):'
-
-    def check_circularity(new_inclusion)
-      previous_inclusions = inclusions.collect {|x| x.real_includee_file_path}
-      previously_included = previous_inclusions.include?(new_inclusion.real_includee_file_path)
-      if previously_included
-        inclusions.push(new_inclusion)
-        message = [
-            CIRCULAR_EXCEPTION_LABEL,
-            backtrace_inclusions,
-            ].join("\n")
-        e = MarkdownHelper::CircularIncludeError.new(message)
-        e.set_backtrace([])
-        raise e
-      end
+  end
+
+  def check_circularity(inclusion)
+    included_file_paths = @inclusions.collect { |x| x.includee_real_file_path}
+    previously_included = included_file_paths.include?(inclusion.includee_real_file_path)
+    if previously_included
+      @inclusions.push(inclusion)
+      message = [
+          'Includes are circular:',
+          MarkdownHelper.backtrace_inclusions(@inclusions),
+      ].join("\n")
+      e = MarkdownHelper::CircularIncludeError.new(message)
+      e.set_backtrace([])
+      raise e
     end
+  end
 
-    def backtrace_inclusions
-      lines = [BACKTRACE_LABEL]
-      inclusions.reverse.each_with_index do |inclusion, i|
-        lines.push("#{LEVEL_LABEL} #{i}:")
-        level_lines = inclusion.to_lines(indentation_level = 3)
-        lines.push(*level_lines)
-      end
-      lines.join("\n")
+  def check_includee(inclusion)
+    unless File.readable?(inclusion.includee_absolute_file_path)
+      @inclusions.push(inclusion)
+      message = [
+          'Could not read includee file:',
+          MarkdownHelper.backtrace_inclusions(@inclusions),
+      ].join("\n")
+      e = MarkdownHelper::UnreadableIncludeeError.new(message)
+      e.set_backtrace([])
+      raise e
     end
 
   end
 
-  class Inclusion
+  def self.backtrace_inclusions(inclusions)
+    lines = ['  Backtrace (innermost include first):']
+    inclusions.reverse.each_with_index do |inclusion, i|
+      lines.push("#{'    Level'} #{i}:")
+      level_lines = inclusion.to_lines(indentation_level = 3)
+      lines.push(*level_lines)
+    end
+    lines.join("\n")
+  end
 
-    LINE_COUNT = 5
+  class Inclusion
 
     attr_accessor \
       :includer_file_path,
+      :includer_absolute_file_path,
+      :include_pragma,
+      :treatment,
       :includer_line_number,
-      :include_description,
-      :absolute_includee_file_path,
       :cited_includee_file_path,
-      :treatment,
-      :page_toc_title,
-      :page_toc_line
+      :includee_absolute_file_path
 
     def initialize(
-        include_description,
         includer_file_path,
+        include_pragma,
         includer_line_number,
+        treatment,
         cited_includee_file_path,
-        treatment
-    )
-      self.include_description = include_description
+        inclusions
+        )
       self.includer_file_path = includer_file_path
+      self.include_pragma = include_pragma
       self.includer_line_number = includer_line_number
-      self.cited_includee_file_path = cited_includee_file_path
-      self.absolute_includee_file_path = absolute_includee_file_path
       self.treatment = treatment
-      self.absolute_includee_file_path = File.absolute_path(File.join(
+      self.cited_includee_file_path = cited_includee_file_path
+
+      self.includer_absolute_file_path = File.absolute_path(includer_file_path)
+      unless File.exist?(self.includer_absolute_file_path)
+        fail self.includer_absolute_file_path
+      end
+
+      self.includee_absolute_file_path = File.absolute_path(File.join(
           File.dirname(includer_file_path),
           cited_includee_file_path,
-      ))
+          ))
+    end
+
+    def includer_real_file_path
+      Pathname.new(includer_absolute_file_path).realpath.to_s
     end
 
-    def real_includee_file_path
-      # Would raise exception unless exists.
-      return nil unless File.exist?(absolute_includee_file_path)
-      Pathname.new(absolute_includee_file_path).realpath.to_s
+    def includee_real_file_path
+      Pathname.new(includee_absolute_file_path).realpath.to_s
     end
 
     def indentation(level)
@@ -388,11 +359,11 @@ EOT
 
     def to_lines(indentation_level)
       relative_inluder_file_path = MarkdownHelper.path_in_project(includer_file_path)
-      relative_inludee_file_path = MarkdownHelper.path_in_project(absolute_includee_file_path)
+      relative_inludee_file_path = MarkdownHelper.path_in_project(includee_absolute_file_path)
        text = <<EOT
 #{indentation(indentation_level)}Includer:
 #{indentation(indentation_level+1)}Location: #{relative_inluder_file_path}:#{includer_line_number}
-#{indentation(indentation_level+1)}Include description: #{include_description}
+#{indentation(indentation_level+1)}Include pragma: #{include_pragma}
 #{indentation(indentation_level)}Includee:
 #{indentation(indentation_level+1)}File path: #{relative_inludee_file_path}
 EOT
@@ -402,4 +373,3 @@ EOT
   end
 
 end
-