kramdown-asciidoc 1.0.0.alpha.6 → 1.0.0.alpha.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d7e7b3ea076bc3a4367cee05e190fd4fb7aa867c941786b122ac5696a0f8869e
-  data.tar.gz: 8a964360802076fdd8ccd9aa569c810fd90843b84a3394326e7b6b31d8e76f46
+  metadata.gz: 0f7bd16c11f904bc9f55ca9ef70d3a925882bd4bdba7f118521a5020676ec4b7
+  data.tar.gz: e8e880f21395275db7756e626d77f9f6425d2856b32049174b8074e69717ed30
 SHA512:
-  metadata.gz: 0fd80955421722cfa21688637e06d9d94377ab46679df75958ae8e61b6ba4eb80784beea8a90cf8f1ed415389a95b316a5fc8b349a608edb406704123db92c37
-  data.tar.gz: 284fb8dfbd153aca87bdf10687c24e80995aee0e135709a2aca6b4b22fc4a562e36472c83cd54a7c2d17e6f53a0c7e0fff8056872a29a8218c844078c28fb6af
+  metadata.gz: f2fe378e4963ce01c8119e0512021aef55b3cbb6fe1efc1772d4dc2880d9c1b16cd83edfd20363089e83750447d627a8bec4bed88d3af041ed3a6115124af199
+  data.tar.gz: a8d1cbea734f4db2d71930c1e5e0f3cc6bc198c24e66117de316c1d4e35e946ed43c7181b0147acd24d73d6f7501ae7d0b6b5d20e175b5f849948a9c7fdebe18

data/CHANGELOG.adoc

@@ -5,11 +5,31 @@
 This document provides a high-level view of the changes to {project-name} by release.
 For a detailed view of what has changed, refer to the {uri-repo}/commits/master[commit history] on GitHub.
 
+== 1.0.0.alpha.7 (2018-07-02) - @mojavelinux
+
+=== Added
+
+* add :wrap option to control line wrapping behavior (:ventilate, :none, and :preserve) (#11)
+* add --wrap CLI option to control :wrap option (#11)
+* add support for unconstrained formatting (em, strong, and codespan) (#6)
+* escape all replaceable text (arrows and ellipses) when converting regular text
+* replace double plus in codespan with \{pp} attribute reference
+* escape attribute references in regular text
+* use passthrough for codespan if text contains an attribute reference
+* use pass macro to escape literal codespan that contains ++
+* escape codespan that contains replacements (#12)
+
+=== Changed
+
+* add replace_line method to Writer
+* replace .md extension with .adoc in text of interdoc xref
+* replace a non-breaking space with a single space instead of \{nbsp}
+
 == 1.0.0.alpha.6 (2018-06-26) - @mojavelinux
 
 === Added
 
-* added options and usage to CLI (#2)
+* add options and usage to CLI (#2)
 * ensure directory of output file exists
 * add option to enable automatic generation of IDs for section titles
 

data/README.adoc

@@ -1,6 +1,6 @@
 = {project-name} (Markdown to AsciiDoc)
 Dan Allen <https://github.com/mojavelinux>
-v1.0.0.alpha.6, 2018-06-26
+v1.0.0.alpha.7, 2018-07-02
 // Aliases:
 :project-name: Kramdown AsciiDoc
 :project-handle: kramdown-asciidoc
@@ -133,6 +133,55 @@ Then, use the `bundle` command to install the project dependencies under the pro
 
 NOTE: You must invoke `bundle` from the project's root directory so it can locate the [.path]_Gemfile_.
 
+=== Run the Tests
+
+The test suite is located in the [.path]_spec_ directory.
+The tests are all based on RSpec.
+
+Most specs are scenarios, located under the [.path]_spec/scenarios_ directory.
+Each scenario consists of a Markdown file that ends in .md (the given), an AsciiDoc file that ends in .adoc (the then), and an optional options file that ends in .opts.
+The test converts the Markdown to AsciiDoc (the when) and validates the result against what's expected.
+The specification name of each scenario is derived from the directory name.
+
+You can run all of the tests using Rake:
+
+ $ bundle exec rake
+
+For more fine-grained control, you can also run the tests directly using RSpec:
+
+ $ bundle exec rspec
+
+To run all the scenarios, point RSpec at the spec file:
+
+ $ bundle exec rspec spec/scenario_spec.rb
+
+==== Run Individual Tests
+
+If you only want to run a single test, or a group of tests, you can do so by tagging the test cases, then filtering the test run using that tag.
+
+Start by adding the `wip` tag to one or more specifications:
+
+[source,ruby]
+----
+it 'should do something new', wip: true do
+  expect(true).to be true
+end
+----
+
+Next, run RSpec with the `wip` flag enabled:
+
+ $ bundle exec rspec -t wip
+
+RSpec will only run the specifications that contain this flag.
+
+You can also filter tests by keyword.
+Let's assume we want to run all the tests that have `wrap` in the description.
+Run RSpec with the example filter:
+
+ $ bundle exec rspec -e wrap
+
+RSpec will only run the specifications that have a description containing the text `wrap`.
+
 === Usage
 
 When running the `kramdoc` command from source, you must prefix the command with `bundle exec`:

data/lib/kramdown-asciidoc/cli.rb

@@ -33,6 +33,10 @@ module Kramdown; module AsciiDoc
           options[:attributes][key] = val
         end
 
+        opts.on '--wrap=preserve|none|ventilate', %w(none preserve ventilate), 'Set how lines are wrapped in the AsciiDoc document (default: preserve)' do |wrap|
+          options[:wrap] = wrap.to_sym
+        end
+
         opts.on '--heading-offset=NUMBER', 'Shift the heading level by the specified number', ::Integer do |offset|
           options[:heading_offset] = offset
         end

data/lib/kramdown-asciidoc/converter.rb

@@ -81,18 +81,23 @@ module Kramdown; module AsciiDoc
 
     NON_DEFAULT_TABLE_ALIGNMENTS = [:center, :right]
 
+    AccidentalReplacementsRx = /[-=]>|<[-=]|\.\.\.|\{\p{Word}[\p{Word}-]*\}/
     CommentPrefixRx = /^ *! ?/m
     CssPropDelimRx = /\s*;\s*/
+    FullStopRx = /(?<=\.)\p{Blank}+(?!\Z)/
     MenuRefRx = /^([\p{Word}&].*?)\s>\s([\p{Word}&].*(?:\s>\s|$))+/
-    ReplaceableTextRx = /[-=]>|<[-=]|\.\.\./
+    ReplaceableTextRx = /[-=]>|<[-=]|--|\*\*|\.\.\.|&\S+;|\{\p{Word}[\p{Word}-]*\}|\((?:C|R|TM)\)/
     SmartApostropheRx = /\b’\b/
     TrailingSpaceRx = / +$/
     TypographicSymbolRx = /[“”‘’—–…]/
+    WordishRx = /[\p{Word};:]/
+    WordRx = /\p{Word}/
     XmlCommentRx = /\A<!--(.*)-->\Z/m
 
     VoidElement = Element.new nil
 
     LF = ?\n
+    NBSP = ?\u00a0
 
     def initialize root, opts
       super
@@ -100,6 +105,7 @@ module Kramdown; module AsciiDoc
       @imagesdir = (@attributes.delete 'implicit-imagesdir') || @attributes['imagesdir']
       @heading_offset = opts[:heading_offset] || 0
       @current_heading_level = nil
+      @wrap = opts[:wrap] || :preserve
     end
 
     def convert el, opts = {}
@@ -114,7 +120,10 @@ module Kramdown; module AsciiDoc
         writer.doctitle ||= fallback_doctitle
       end
       writer.add_attributes @attributes unless @attributes.empty?
-      writer.to_s.gsub TrailingSpaceRx, ''
+      result = writer.to_s.gsub TrailingSpaceRx, ''
+      # QUESTION should we add a preprocessor step to clean the source?
+      result = result.tr NBSP, ' ' if result.include? NBSP
+      result
     end
 
     def convert_heading el, opts
@@ -141,6 +150,7 @@ module Kramdown; module AsciiDoc
       end
       lines = []
       lines << %([#{style.join}]) unless style.empty?
+      # NOTE kramdown removes newlines from heading
       lines << %(#{'=' * level} #{compose_text el, strip: true})
       if level == 1 && writer.empty? && @current_heading_level != 1
         writer.header.push(*lines)
@@ -168,7 +178,7 @@ module Kramdown; module AsciiDoc
       elsif (child_i = children[0]).type == :text && (child_i_text = child_i.value).start_with?(*ADMON_MARKERS)
         marker, child_i_text = child_i_text.split ': ', 2
         children = [(clone child_i, value: %(#{ADMON_TYPE_MAP[marker]}: #{child_i_text}))] + (children.drop 1)
-        lines = compose_text children, parent: el, strip: true, split: true
+        lines = compose_text children, parent: el, strip: true, split: true, wrap: @wrap
       # NOTE detect formatted admonition marker (e.g., *Note:* ...)
       elsif (child_i.type == :strong || child_i.type == :em) &&
           (marker_el = child_i.children[0]) && ((marker = ADMON_FORMATTED_MARKERS[marker_el.value]) ||
@@ -177,10 +187,10 @@ module Kramdown; module AsciiDoc
         children = children.drop 1
         children[0] = clone child_ii, value: (child_ii_text.slice 1, child_ii_text.length) if child_ii
         # Q: should we only rstrip?
-        lines = compose_text children, parent: el, strip: true, split: true
+        lines = compose_text children, parent: el, strip: true, split: true, wrap: @wrap
         lines.unshift %(#{ADMON_TYPE_MAP[marker]}: #{lines.shift})
       else
-        lines = compose_text el, strip: true, split: true
+        lines = compose_text el, strip: true, split: true, wrap: @wrap
       end
       writer.add_lines lines
     end
@@ -200,7 +210,7 @@ module Kramdown; module AsciiDoc
           contents.pop while contents.size > 0 && contents[-1].empty?
         end
         # Q: should writer handle delimited block nesting?
-        delimiter = '____' + (depth > 0 ? '__' * depth : '')
+        delimiter = depth > 0 ? ('____' + '__' * depth) : '_'
         writer.start_delimited_block delimiter
         writer.add_lines contents
         writer.end_delimited_block
@@ -231,7 +241,7 @@ module Kramdown; module AsciiDoc
         writer.add_lines lines
         writer.add_line '....'
       else
-        # NOTE clear the list continuation (is the condition necessary?)
+        # NOTE clear the list continuation
         writer.clear_line if writer.current_line == '+'
         writer.add_line lines.map {|l| %( #{l}) }
       end
@@ -299,7 +309,7 @@ module Kramdown; module AsciiDoc
       indent = (level = opts[:list_level]) - 1
       if (children = el.children)[0].type == :p
         primary, remaining = [(children = children.dup).shift, children]
-        primary_lines = compose_text [primary], parent: el, strip: true, split: true
+        primary_lines = compose_text [primary], parent: el, strip: true, split: true, wrap: @wrap
       else
         remaining = children
         primary_lines = ['{blank}']
@@ -314,6 +324,7 @@ module Kramdown; module AsciiDoc
     end
 
     def convert_dt el, opts
+      # NOTE kramdown removes newlines from term
       term = compose_text el, strip: true
       marker = DLIST_MARKERS[opts[:dlist_level] - 1]
       #opts[:writer].add_blank_line if (prev = opts[:prev]) && prev.options[:compound]
@@ -326,7 +337,7 @@ module Kramdown; module AsciiDoc
         remaining = el.children
       else
         remaining = (children = el.children).drop 1
-        primary_lines = compose_text [children[0]], parent: el, strip: true, split: true
+        primary_lines = compose_text [children[0]], parent: el, strip: true, split: true, wrap: @wrap
         if primary_lines.size == 1
           opts[:writer].append %( #{primary_lines[0]})
         else
@@ -349,14 +360,22 @@ module Kramdown; module AsciiDoc
         colspecs = %("#{colspecs}") if cols > 1
       end
       table_buffer = ['|===']
+      ventilate = @wrap == :ventilate
       el.children.each do |container|
         container.children.each do |row|
           row_buffer = []
           row.children.each do |cell|
-            # TODO if using sentence-per-line, append to row_buffer as separate lines
-            cell_contents = compose_text cell
-            cell_contents = cell_contents.gsub '|', '\|' if cell_contents.include? '|'
-            row_buffer << %(| #{cell_contents})
+            if ventilate
+              cell_contents = (compose_text cell, split: true, wrap: :ventilate).map do |line|
+                (line.include? '|') ? (line.gsub '|', '\|') : line
+              end
+              cell_contents[0] = %(| #{cell_contents[0]})
+              row_buffer += cell_contents
+            else
+              cell_contents = compose_text cell
+              cell_contents = cell_contents.gsub '|', '\|' if cell_contents.include? '|'
+              row_buffer << %(| #{cell_contents})
+            end
           end
           if container.type == :thead
             head = true
@@ -395,43 +414,87 @@ module Kramdown; module AsciiDoc
           opts[:writer].append bare ? url : %(#{url}[#{text.gsub ']', '\]'}])
         end
       elsif url.end_with? '.md'
-        opts[:writer].append %(xref:#{url.slice 0, url.length - 3}.adoc[#{(compose_text el, strip: true).gsub ']', '\]'}])
+        text = (compose_text el, strip: true).gsub ']', '\]'
+        text = %(#{text.slice 0, text.length - 3}.adoc) if text.end_with? '.md'
+        opts[:writer].append %(xref:#{url.slice 0, url.length - 3}.adoc[#{text}])
       else
         opts[:writer].append %(link:#{url}[#{(compose_text el, strip: true).gsub ']', '\]'}])
       end
     end 
 
     def convert_codespan el, opts
-      opts[:writer].append (val = el.value) =~ ReplaceableTextRx ? %(`+#{val}+`) : %(`#{val}`)
+      mark = (unconstrained? opts[:prev], opts[:next], :codespan) ? '``' : '`'
+      text = el.value
+      pass = (replaceable? text) ? :shorthand : nil
+      if text.include? '++'
+        if pass
+          pass = :macro
+        else
+          @attributes['pp'] = '{plus}{plus}'
+          text = text.gsub '++', '{pp}'
+        end
+      end
+      if pass == :shorthand
+        opts[:writer].append %(#{mark}+#{text}+#{mark})
+      elsif pass == :macro
+        opts[:writer].append %(#{mark}pass:[#{text}]#{mark})
+      else
+        opts[:writer].append %(#{mark}#{text}#{mark})
+      end
     end
 
     def convert_em el, opts
-      opts[:writer].append %(_#{compose_text el}_)
+      composed_text = compose_text el
+      mark = (unconstrained? opts[:prev], opts[:next], :em) ? '__' : '_'
+      opts[:writer].append %(#{mark}#{composed_text}#{mark})
     end
 
     def convert_strong el, opts
-      text = compose_text el
-      if (text.include? ' > ') && MenuRefRx =~ text
+      if ((composed_text = compose_text el).include? ' > ') && MenuRefRx =~ composed_text
         @attributes['experimental'] = ''
         opts[:writer].append %(menu:#{$1}[#{$2}])
       else
-        opts[:writer].append %(*#{text}*)
+        mark = (unconstrained? opts[:prev], opts[:next], :strong) ? '**' : '*'
+        opts[:writer].append %(#{mark}#{composed_text}#{mark})
       end
     end
 
+    def unconstrained? prev_el, next_el, enclosure
+      (next_char_word? next_el, enclosure) || (prev_char_wordish? prev_el)
+    end
+
+    def prev_char_wordish? prev_el
+      prev_el && (prev_el.type == :entity || ((prev_ch = prev_el.type == :text && prev_el.value[-1]) && (WordishRx.match? prev_ch)))
+    end
+
+    def next_char_word? next_el, enclosure
+      if next_el.type == :text
+        (next_ch = next_el.value.chr) && ((WordRx.match? next_ch) || (enclosure == :codespan && next_ch == ?'))
+      elsif enclosure == :codespan && next_el.type == :smart_quote
+        true
+      end if next_el
+    end
+
     def convert_text el, opts
-      if (text = el.value).include? '++'
+      text = escape_replacements el.value
+      if text.include? '++'
         @attributes['pp'] = '{plus}{plus}'
         text = text.gsub '++', '{pp}'
       end
-      # Q: should we replace with single space instead?
-      text = text.gsub ' ', '{nbsp}' if text.include? ' '
+      opts[:writer].append text
+    end
+
+    def replaceable? text
+      (ReplaceableTextRx.match? text) || (text != '^' && (text.include? '^'))
+    end
+
+    def escape_replacements text
+      text = text.gsub AccidentalReplacementsRx, '\\\\\0' if AccidentalReplacementsRx.match? text
       text = text.gsub '^', '{caret}' if (text.include? '^') && text != '^'
-      text = text.gsub '<=', '\<=' if text.include? '<='
       unless text.ascii_only?
         text = (text.gsub SmartApostropheRx, ?').gsub TypographicSymbolRx, TYPOGRAPHIC_SYMBOL_TO_MARKUP
       end
-      opts[:writer].append text
+      text
     end
 
     # NOTE this logic assumes the :hard_wrap option is disabled in the parser
@@ -443,10 +506,7 @@ module Kramdown; module AsciiDoc
         writer.append %(#{(writer.current_line.end_with? ' ') ? '' : ' '}+)
       end
       if el.options[:html_tag]
-        siblings = opts[:parent].children
-        unless (next_el = siblings[(siblings.index el) + 1] || VoidElement).type == :text && (next_el.value.start_with? LF)
-          writer.add_blank_line
-        end
+        writer.add_blank_line unless (next_el = opts[:next] || VoidElement).type == :text && (next_el.value.start_with? LF)
       end
     end
 
@@ -470,7 +530,7 @@ module Kramdown; module AsciiDoc
           return
         elsif child_i_i.value == 'span' && ((role = el.attr['class'] || '').start_with? 'note') && child_i_i.attr['class'] == 'notetitle'
           marker = ADMON_FORMATTED_MARKERS[(child_i_i.children[0] || VoidElement).value] || 'Note'
-          lines = compose_text (child_i.children.drop 1), parent: child_i, strip: true, split: true
+          lines = compose_text (child_i.children.drop 1), parent: child_i, strip: true, split: true, wrap: @wrap
           lines.unshift %(#{ADMON_TYPE_MAP[marker]}: #{lines.shift})
           opts[:writer].start_block
           opts[:writer].add_lines lines
@@ -512,8 +572,7 @@ module Kramdown; module AsciiDoc
       else
         if (current_line = writer.current_line) && !(current_line.end_with? LF)
           start_new_line = true
-          # FIXME cleaner API here (writer#strip_line?)
-          writer.current_line.rstrip! if current_line.end_with? ' '
+          writer.replace_line current_line.rstrip if current_line.end_with? ' '
         end
         lines = lines.map {|l| %(// #{l}) }
         if start_new_line
@@ -544,8 +603,7 @@ module Kramdown; module AsciiDoc
       el
     end
 
-    def traverse el, opts = {}
-      prev = nil
+    def traverse el, opts
       if ::Array === el
         nodes = el
         parent = opts[:parent]
@@ -553,25 +611,60 @@ module Kramdown; module AsciiDoc
         nodes = (parent = el).children
       end
       nodes.each_with_index do |child, idx|
-        convert child, (opts.merge parent: parent, index: idx, prev: prev)
-        prev = child
+        convert child, (opts.merge parent: parent, index: idx, prev: (idx == 0 ? nil : nodes[idx - 1]), next: nodes[idx + 1])
       end
       nil
     end
 
     # Q: should we support rstrip in addition to strip?
     # TODO add escaping of closing square bracket
-    # TODO reflow text
     def compose_text el, opts = {}
       strip = opts.delete :strip
       split = opts.delete :split
+      wrap = (opts.delete :wrap) || :preserve
       # Q: do we want to merge or just start fresh?
       traverse el, (opts.merge writer: (span_writer = Writer.new))
       # NOTE there should only ever be one line
       text = span_writer.body.join LF
       text = text.strip if strip
+      text = reflow text, wrap
       split ? (text.split LF) : text
     end
+
+    def reflow str, wrap
+      #return str if str.empty?
+      case wrap
+      when :ventilate
+        unwrap str, true
+      when :none
+        unwrap str
+      else # :preserve
+        str
+      end
+    end
+
+    # NOTE this method requires contiguous non-blank lines
+    def unwrap str, ventilate = false
+      result = []
+      start_new_line = true
+      lines = str.split LF
+      while (line = lines.shift)
+        if line.start_with? '//'
+          result << line
+          start_new_line = true
+        elsif start_new_line
+          result << line
+          start_new_line = false
+        else
+          result << %(#{result.pop} #{line})
+        end
+      end
+      if ventilate
+        result.map {|line| (line.start_with? '//') ? line : ((line.include? '.') ? (line.gsub FullStopRx, LF) : line) }.join LF
+      else
+        result.join LF
+      end
+    end
   end
 end; end
 

data/lib/kramdown-asciidoc/version.rb

@@ -1,3 +1,3 @@
 module Kramdown; module AsciiDoc
-  VERSION = '1.0.0.alpha.6'
+  VERSION = '1.0.0.alpha.7'
 end; end

data/lib/kramdown-asciidoc/writer.rb

@@ -45,7 +45,7 @@ module Kramdown; module AsciiDoc
 
     # Q: perhaps in_list that takes a block?
     # Q: should we keep stack of list depth?
-    def start_list compound = false
+    def start_list compound
       @body << '' unless (compound && @block_separator.last == '+') || empty?
       @block_separator << '+'
       nil
@@ -70,11 +70,6 @@ module Kramdown; module AsciiDoc
       nil
     end
 
-    def clear_line
-      @body[-1] = '' unless empty?
-      nil
-    end
-
     def add_blank_line
       @body << ''
       nil
@@ -99,6 +94,16 @@ module Kramdown; module AsciiDoc
       nil
     end
 
+    def clear_line
+      replace_line ''
+    end
+
+    def replace_line line
+      @body.pop
+      @body << line
+      nil
+    end
+
     def current_line
       @body[-1]
     end

data/spec/cli_spec.rb

@@ -3,6 +3,8 @@ require 'kramdown-asciidoc/cli'
 require 'stringio'
 
 describe Kramdown::AsciiDoc::Cli do
+  subject { Kramdown::AsciiDoc::Cli }
+
   before :each do
     @old_stdout, $stdout = $stdout, StringIO.new
     @old_stderr, $stderr = $stderr, StringIO.new
@@ -15,31 +17,31 @@ describe Kramdown::AsciiDoc::Cli do
   context 'option flags' do
     it 'returns non-zero exit status and displays usage when no arguments are given' do
       expected = 'kramdoc: Please specify a Markdown file to convert.'
-      (expect Kramdown::AsciiDoc::Cli.run []).to eql 1
+      (expect subject.run []).to eql 1
       (expect $stderr.string.chomp).to eql expected
       (expect $stdout.string.chomp).to start_with 'Usage: kramdoc'
     end
 
     it 'returns non-zero exit status and displays usage when more than one argument is given' do
       expected = 'kramdoc: extra arguments detected (unparsed arguments: bar.md)'
-      (expect Kramdown::AsciiDoc::Cli.run %w(foo.md bar.md)).to eql 1
+      (expect subject.run %w(foo.md bar.md)).to eql 1
       (expect $stderr.string.chomp).to eql expected
       (expect $stdout.string.chomp).to start_with 'Usage: kramdoc'
     end
 
     it 'returns non-zero exit status when invalid argument is given' do
-      (expect Kramdown::AsciiDoc::Cli.run %w(--invalid-option)).to eql 1
+      (expect subject.run %w(--invalid-option)).to eql 1
       (expect $stderr.string.chomp).to eql 'kramdoc: invalid option: --invalid-option'
       (expect $stdout.string.chomp).to start_with 'Usage: kramdoc'
     end
 
     it 'displays version when -v flag is used' do
-      (expect Kramdown::AsciiDoc::Cli.run %w(-v)).to eql 0
+      (expect subject.run %w(-v)).to eql 0
       (expect $stdout.string.chomp).to eql %(kramdoc #{Kramdown::AsciiDoc::VERSION})
     end
 
     it 'displays help when -h flag is used' do
-      (expect Kramdown::AsciiDoc::Cli.run %w(-h)).to eql 0
+      (expect subject.run %w(-h)).to eql 0
       (expect $stdout.string.chomp).to start_with 'Usage: kramdoc'
     end
 
@@ -47,7 +49,7 @@ describe Kramdown::AsciiDoc::Cli do
       the_source_file = output_file 'implicit-output.md'
       the_output_file = output_file 'implicit-output.adoc'
       IO.write the_source_file, 'This is just a test.'
-      (expect Kramdown::AsciiDoc::Cli.run %W(#{the_source_file})).to eql 0
+      (expect subject.run %W(#{the_source_file})).to eql 0
       (expect (IO.read the_output_file).chomp).to eql 'This is just a test.'
     end
 
@@ -55,7 +57,7 @@ describe Kramdown::AsciiDoc::Cli do
       the_source_file = output_file 'explicit-output.md'
       the_output_file = output_file 'my-explicit-output.adoc'
       IO.write the_source_file, 'This is only a test.'
-      (expect Kramdown::AsciiDoc::Cli.run %W(-o #{the_output_file} #{the_source_file})).to eql 0
+      (expect subject.run %W(-o #{the_output_file} #{the_source_file})).to eql 0
       (expect (IO.read the_output_file).chomp).to eql 'This is only a test.'
     end
 
@@ -63,13 +65,13 @@ describe Kramdown::AsciiDoc::Cli do
       the_source_file = output_file 'ensure-output-dir.md'
       the_output_file = output_file 'path/to/output/file.adoc'
       IO.write the_source_file, 'Everything is going to be fine.'
-      (expect Kramdown::AsciiDoc::Cli.run %W(-o #{the_output_file} #{the_source_file})).to eql 0
+      (expect subject.run %W(-o #{the_output_file} #{the_source_file})).to eql 0
       (expect (IO.read the_output_file).chomp).to eql 'Everything is going to be fine.'
     end
 
     it 'writes output to stdout when -o option equals -' do
       the_source_file = scenario_file 'p/single-line.md'
-      (expect Kramdown::AsciiDoc::Cli.run %W(-o - #{the_source_file})).to eql 0
+      (expect subject.run %W(-o - #{the_source_file})).to eql 0
       (expect $stdout.string.chomp).to eql 'A paragraph that consists of a single line.'
     end
 
@@ -78,7 +80,7 @@ describe Kramdown::AsciiDoc::Cli do
       begin
         $stdin.puts '- list item'
         $stdin.rewind
-        (expect Kramdown::AsciiDoc::Cli.run %W(-o - -)).to eql 0
+        (expect subject.run %W(-o - -)).to eql 0
         (expect $stdout.string.chomp).to eql '* list item'
       ensure
         $stdin = old_stdin
@@ -87,35 +89,77 @@ describe Kramdown::AsciiDoc::Cli do
 
     it 'removes leading blank lines and trailing whitespace from source' do
       the_source_file = output_file 'leading-trailing-space.md'
-      IO.write the_source_file, %(\n\n\n\n# Heading\n\ncontent.   \n\n)
-      (expect Kramdown::AsciiDoc::Cli.run %W(-o - #{the_source_file})).to eql 0
-      (expect $stdout.string.chomp).to eql %(= Heading\n\ncontent.)
+      IO.write the_source_file, <<~EOS
+      \n\n\n\n
+      # Heading
+
+      Body content.#{'  '}
+      \n\n\n\n
+      EOS
+      (expect subject.run %W(-o - #{the_source_file})).to eql 0
+      (expect $stdout.string.chomp).to eql %(= Heading\n\nBody content.)
+    end
+
+    it 'processes front matter in source' do
+      the_source_file = output_file 'front-matter.md'
+      IO.write the_source_file, <<~EOS
+      ---
+      title: Document Title
+      ---
+      Body content.
+      EOS
+      (expect subject.run %W(-o - #{the_source_file})).to eql 0
+      (expect $stdout.string.chomp).to eql %(= Document Title\n\nBody content.)
+    end
+
+    it 'replaces explicit toc in source' do
+      the_source_file = output_file 'toc.md'
+      IO.write the_source_file, <<~EOS
+      # Guide
+
+      <!-- TOC depthFrom:2 depthTo:6 -->
+      - [Prerequisites](#prerequisites)
+      - [Installation](#installation)
+      - [Deployment](#deployment)
+      <!-- /TOC -->
+
+      ...
+      EOS
+      (expect subject.run %W(-o - #{the_source_file})).to eql 0
+      (expect $stdout.string.chomp).to eql %(= Guide\n:toc: macro\n\ntoc::[]\n\n...)
     end
 
     it 'reads Markdown source using specified format' do
       the_source_file = output_file 'format-markdown.md'
       IO.write the_source_file, '#Heading'
-      (expect Kramdown::AsciiDoc::Cli.run %W(-o - --format=markdown #{the_source_file})).to eql 0
+      (expect subject.run %W(-o - --format=markdown #{the_source_file})).to eql 0
       (expect $stdout.string.chomp).to eql '= Heading'
     end
 
+    it 'wraps output as specified by the --wrap option' do
+      the_source_file = scenario_file 'wrap/ventilate.md'
+      expected = IO.read scenario_file 'wrap/ventilate.adoc'
+      (expect subject.run %W(-o - --wrap=ventilate #{the_source_file})).to eql 0
+      (expect $stdout.string).to eql expected
+    end
+
     it 'shifts headings by offset when --heading-offset is used' do
       the_source_file = scenario_file 'heading/offset.md'
       expected = IO.read scenario_file 'heading/offset.adoc'
-      (expect Kramdown::AsciiDoc::Cli.run %W(-o - --heading-offset=-1 #{the_source_file})).to eql 0
+      (expect subject.run %W(-o - --heading-offset=-1 #{the_source_file})).to eql 0
       (expect $stdout.string).to eql expected
     end
 
     it 'automatically generates IDs for section titles when --auto-ids is used' do
       the_source_file = scenario_file 'heading/auto-ids.md'
       expected = IO.read scenario_file 'heading/auto-ids.adoc'
-      (expect Kramdown::AsciiDoc::Cli.run %W(-o - --auto-ids #{the_source_file})).to eql 0
+      (expect subject.run %W(-o - --auto-ids #{the_source_file})).to eql 0
       (expect $stdout.string).to eql expected
     end
 
     it 'adds specified attributes to document header' do
       the_source_file = scenario_file 'root/header-and-body.md'
-      (expect Kramdown::AsciiDoc::Cli.run %W(-o - -a idprefix -a idseparator=- #{the_source_file})).to eql 0
+      (expect subject.run %W(-o - -a idprefix -a idseparator=- #{the_source_file})).to eql 0
       expected = <<~EOS
       = Document Title
       :idprefix:
@@ -128,7 +172,7 @@ describe Kramdown::AsciiDoc::Cli do
 
     it 'passes through HTML when --no-html-to-native flag is used' do
       the_source_file = scenario_file 'html_element/native.md'
-      (expect Kramdown::AsciiDoc::Cli.run %W(-o - --no-html-to-native #{the_source_file})).to eql 0
+      (expect subject.run %W(-o - --no-html-to-native #{the_source_file})).to eql 0
       expected = <<~EOS
       +++<p>++++++<strong>+++strong emphasis (aka bold)+++</strong>+++ +++<em>+++emphasis (aka italic)+++</em>+++ +++<code>+++monospace+++</code>++++++</p>+++
       EOS
@@ -139,7 +183,7 @@ describe Kramdown::AsciiDoc::Cli do
       old_ARGV = ARGV.dup
       ARGV.replace %w(-v)
       begin
-        (expect Kramdown::AsciiDoc::Cli.run).to eql 0
+        (expect subject.run).to eql 0
         (expect $stdout.string.chomp).to eql %(kramdoc #{Kramdown::AsciiDoc::VERSION})
       ensure
         ARGV.replace old_ARGV

data/spec/converter_spec.rb

@@ -13,6 +13,11 @@ describe Kramdown::AsciiDoc::Converter do
       (expect converter.convert root).to end_with %(\n)
       (expect doc.to_asciidoc).to end_with %(\n)
     end
+
+    # Q: can we find a scenario that covers this?
+    it 'does not crash if element is nil' do
+      (expect converter.convert nil).to be_nil
+    end
   end
 
   context '#clone' do

data/spec/{integration_spec.rb → scenario_spec.rb}

@@ -1,7 +1,7 @@
 require_relative 'spec_helper'
 require 'yaml'
 
-describe 'integration scenario' do
+describe 'scenario' do
   let(:doc) { Kramdown::Document.new input, (Kramdown::AsciiDoc::DEFAULT_PARSER_OPTS.merge extra_options) }
 
   Dir.chdir scenarios_dir do

data/spec/scenarios/a/bare-interdoc-xref.adoc

@@ -0,0 +1 @@
+See the xref:operations-guide.adoc[operations-guide.adoc].

data/spec/scenarios/a/bare-interdoc-xref.md

@@ -0,0 +1 @@
+See the [operations-guide.md](operations-guide.md).

data/spec/scenarios/codespan/literal.adoc

@@ -1,5 +1,11 @@
 Use the `+<=+` operator to define a version that is less than or equal to a specific version.
 
-Use `+(start...end)+` to create a range from start to end that excludes the last element.
+Use `+(start...end)+` to create a sequence that ranges from `+start--end+`, but excludes the last element.
 
 Use an `+<!-- XML comment -->+` to disable or hide markup.
+
+In AsciiDoc, `+{name}+` is the syntax for an attribute reference.
+
+`pass:[{lang}++]` is simply better than `+{lang}+`.
+
+Type `+&copy;+` or `+(C)+` to enter a copyright symbol.

data/spec/scenarios/codespan/literal.md

@@ -1,5 +1,11 @@
 Use the `<=` operator to define a version that is less than or equal to a specific version.
 
-Use `(start...end)` to create a range from start to end that excludes the last element.
+Use `(start...end)` to create a sequence that ranges from `start--end`, but excludes the last element.
 
 Use an `<!-- XML comment -->` to disable or hide markup.
+
+In AsciiDoc, `{name}` is the syntax for an attribute reference.
+
+`{lang}++` is simply better than `{lang}`.
+
+Type `&copy;` or `(C)` to enter a copyright symbol.

data/spec/scenarios/codespan/plus-plus.adoc

@@ -0,0 +1,3 @@
+:pp: {plus}{plus}
+
+`C{pp}` is hard. `C{pp}` is fast.

data/spec/scenarios/codespan/plus-plus.md

@@ -0,0 +1 @@
+`C++` is hard. `C++` is fast.

data/spec/scenarios/codespan/star-star.adoc

@@ -0,0 +1 @@
+`+**+` is the exponent operator in Ruby. For example `+4 ** 2+` is 4 to the power of 2 (i.e., 16).

data/spec/scenarios/codespan/star-star.md

@@ -0,0 +1 @@
+`**` is the exponent operator in Ruby. For example `4 ** 2` is 4 to the power of 2 (i.e., 16).

data/spec/scenarios/codespan/unconstrained.adoc

@@ -0,0 +1,5 @@
+It will be ``npm install``ed (or ``yarn``ed) into `node_modules`.
+Then just run `lerna`--the base command.
+You can re``link`` all related packages using ``lerna``'s `link` command.
+"``foo`` `bar`"
+so `mono` man

data/spec/scenarios/codespan/unconstrained.md

@@ -0,0 +1,5 @@
+It will be `npm install`ed (or `yarn`ed) into `node_modules`.
+Then just run `lerna`--the base command.
+You can re`link` all related packages using `lerna`'s `link` command.
+"`foo` `bar`"
+so ``` mono ``` man

data/spec/scenarios/em/unconstrained.adoc

@@ -0,0 +1,4 @@
+I want you to __re__read the article.
+You will find that she is _right_.
+Ba__boom__.
+©__the authors__

data/spec/scenarios/em/unconstrained.md

@@ -0,0 +1,4 @@
+I want you to *re*read the article.
+You will find that she is *right*.
+Ba*boom*.
+©*the authors*

data/spec/scenarios/strong/unconstrained.adoc

@@ -0,0 +1,7 @@
+**C**reate.
+**R**ead.
+**U**pdate.
+**D**elete.
+Also known as *CRUD*.
+Not to be confused with E**CRU**, which is a color.
+®**CRUD** it is not.

data/spec/scenarios/strong/unconstrained.md

@@ -0,0 +1,7 @@
+**C**reate.
+**R**ead.
+**U**pdate.
+**D**elete.
+Also known as **CRUD**.
+Not to be confused with E**CRU**, which is a color.
+®**CRUD** it is not.

data/spec/scenarios/text/attribute-reference.adoc

@@ -0,0 +1 @@
+The processor will interpolate #\{variables} in the text.

data/spec/scenarios/text/attribute-reference.md

@@ -0,0 +1 @@
+The processor will interpolate #{variables} in the text.

data/spec/scenarios/text/nbsp.adoc

@@ -1 +1 @@
-deceptive{nbsp}spaces{nbsp}live{nbsp}here
+deceptive spaces live here

data/spec/scenarios/text/right-arrow.adoc

@@ -0,0 +1 @@
+a \-> b is the most direct route.

data/spec/scenarios/text/right-arrow.md

@@ -0,0 +1 @@
+a -> b is the most direct route.

data/spec/scenarios/wrap/containing-line-comment.adoc

@@ -0,0 +1,3 @@
+This is
+// only
+a test.

data/spec/scenarios/wrap/containing-line-comment.md

@@ -0,0 +1,3 @@
+This
+is<!-- only -->a
+test.

data/spec/scenarios/wrap/containing-line-comment.opts

@@ -0,0 +1 @@
+:wrap: :none

data/spec/scenarios/wrap/none.adoc

@@ -0,0 +1 @@
+This is a test. This is only a test.

data/spec/scenarios/wrap/none.md

@@ -0,0 +1,4 @@
+This
+is
+a
+test. This is only a test.

data/spec/scenarios/wrap/none.opts

@@ -0,0 +1 @@
+:wrap: :none

data/spec/scenarios/wrap/preserve.adoc

@@ -0,0 +1,5 @@
+This
+is
+a test. This
+is only a
+test.

data/spec/scenarios/wrap/preserve.md

@@ -0,0 +1,5 @@
+This
+is
+a test. This
+is only a
+test.

data/spec/scenarios/wrap/preserve.opts

@@ -0,0 +1 @@
+:wrap: :preserve

data/spec/scenarios/wrap/ventilate-table-cell.adoc

@@ -0,0 +1,6 @@
+[cols=2*]
+|===
+| Turn left.
+Then turn right.
+| left \| right
+|===

data/spec/scenarios/wrap/ventilate-table-cell.md

@@ -0,0 +1,2 @@
+| --------------------------- | ------------- |
+| Turn left. Then turn right. | left \| right |

data/spec/scenarios/wrap/ventilate-table-cell.opts

@@ -0,0 +1 @@
+:wrap: :ventilate

data/spec/scenarios/wrap/ventilate.adoc

@@ -0,0 +1,2 @@
+This is a test.
+This is only a test.

data/spec/scenarios/wrap/ventilate.md

@@ -0,0 +1,6 @@
+This
+is
+a
+test. This
+is
+only a test.

data/spec/scenarios/wrap/ventilate.opts

@@ -0,0 +1 @@
+:wrap: :ventilate

data/spec/writer_spec.rb

@@ -0,0 +1,10 @@
+require_relative 'spec_helper'
+
+describe Kramdown::AsciiDoc::Writer do
+  it 'replaces existing doctitle if present when assigning doctitle' do
+    header_lines = ['[#docid]', '= Document Title', ':experimental:']
+    subject.header.push(*header_lines)
+    subject.doctitle = 'New Document Title'
+    (expect subject.doctitle).to eql 'New Document Title'
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kramdown-asciidoc
 version: !ruby/object:Gem::Version
-  version: 1.0.0.alpha.6
+  version: 1.0.0.alpha.7
 platform: ruby
 authors:
 - Dan Allen
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-06-27 00:00:00.000000000 Z
+date: 2018-07-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: kramdown
@@ -88,7 +88,9 @@ files:
 - lib/kramdown-asciidoc/writer.rb
 - spec/cli_spec.rb
 - spec/converter_spec.rb
-- spec/integration_spec.rb
+- spec/scenario_spec.rb
+- spec/scenarios/a/bare-interdoc-xref.adoc
+- spec/scenarios/a/bare-interdoc-xref.md
 - spec/scenarios/a/bare-url.adoc
 - spec/scenarios/a/bare-url.md
 - spec/scenarios/a/containing-inline-image.adoc
@@ -153,6 +155,12 @@ files:
 - spec/scenarios/codespan/constrained.md
 - spec/scenarios/codespan/literal.adoc
 - spec/scenarios/codespan/literal.md
+- spec/scenarios/codespan/plus-plus.adoc
+- spec/scenarios/codespan/plus-plus.md
+- spec/scenarios/codespan/star-star.adoc
+- spec/scenarios/codespan/star-star.md
+- spec/scenarios/codespan/unconstrained.adoc
+- spec/scenarios/codespan/unconstrained.md
 - spec/scenarios/dl/compound-only.adoc
 - spec/scenarios/dl/compound-only.md
 - spec/scenarios/dl/compound.adoc
@@ -171,6 +179,8 @@ files:
 - spec/scenarios/em/constrained.md
 - spec/scenarios/em/strong.adoc
 - spec/scenarios/em/strong.md
+- spec/scenarios/em/unconstrained.adoc
+- spec/scenarios/em/unconstrained.md
 - spec/scenarios/entity/numeric.adoc
 - spec/scenarios/entity/numeric.md
 - spec/scenarios/entity/reverse.adoc
@@ -313,6 +323,8 @@ files:
 - spec/scenarios/strong/menu.md
 - spec/scenarios/strong/nested-emphasis.adoc
 - spec/scenarios/strong/nested-emphasis.md
+- spec/scenarios/strong/unconstrained.adoc
+- spec/scenarios/strong/unconstrained.md
 - spec/scenarios/table/alignment.adoc
 - spec/scenarios/table/alignment.md
 - spec/scenarios/table/cell-with-image.adoc
@@ -327,6 +339,8 @@ files:
 - spec/scenarios/table/with-header.md
 - spec/scenarios/table/without-header.adoc
 - spec/scenarios/table/without-header.md
+- spec/scenarios/text/attribute-reference.adoc
+- spec/scenarios/text/attribute-reference.md
 - spec/scenarios/text/caret.adoc
 - spec/scenarios/text/caret.md
 - spec/scenarios/text/lte.adoc
@@ -335,6 +349,8 @@ files:
 - spec/scenarios/text/nbsp.md
 - spec/scenarios/text/plus-plus.adoc
 - spec/scenarios/text/plus-plus.md
+- spec/scenarios/text/right-arrow.adoc
+- spec/scenarios/text/right-arrow.md
 - spec/scenarios/text/typographic_sym/apostrophe.adoc
 - spec/scenarios/text/typographic_sym/apostrophe.md
 - spec/scenarios/text/typographic_sym/double-quotes.adoc
@@ -375,6 +391,21 @@ files:
 - spec/scenarios/ul/simple-separated.md
 - spec/scenarios/ul/simple.adoc
 - spec/scenarios/ul/simple.md
+- spec/scenarios/wrap/containing-line-comment.adoc
+- spec/scenarios/wrap/containing-line-comment.md
+- spec/scenarios/wrap/containing-line-comment.opts
+- spec/scenarios/wrap/none.adoc
+- spec/scenarios/wrap/none.md
+- spec/scenarios/wrap/none.opts
+- spec/scenarios/wrap/preserve.adoc
+- spec/scenarios/wrap/preserve.md
+- spec/scenarios/wrap/preserve.opts
+- spec/scenarios/wrap/ventilate-table-cell.adoc
+- spec/scenarios/wrap/ventilate-table-cell.md
+- spec/scenarios/wrap/ventilate-table-cell.opts
+- spec/scenarios/wrap/ventilate.adoc
+- spec/scenarios/wrap/ventilate.md
+- spec/scenarios/wrap/ventilate.opts
 - spec/scenarios/xml_comment/above-header.adoc
 - spec/scenarios/xml_comment/above-header.md
 - spec/scenarios/xml_comment/at-start-of-line.adoc
@@ -396,6 +427,7 @@ files:
 - spec/scenarios/xml_comment/styled.adoc
 - spec/scenarios/xml_comment/styled.md
 - spec/spec_helper.rb
+- spec/writer_spec.rb
 homepage: https://github.com/asciidoctor/kramdown-asciidoc
 licenses:
 - MIT
@@ -427,7 +459,9 @@ summary: A Markdown to AsciiDoc converter based on kramdown
 test_files:
 - spec/cli_spec.rb
 - spec/converter_spec.rb
-- spec/integration_spec.rb
+- spec/scenario_spec.rb
+- spec/scenarios/a/bare-interdoc-xref.adoc
+- spec/scenarios/a/bare-interdoc-xref.md
 - spec/scenarios/a/bare-url.adoc
 - spec/scenarios/a/bare-url.md
 - spec/scenarios/a/containing-inline-image.adoc
@@ -492,6 +526,12 @@ test_files:
 - spec/scenarios/codespan/constrained.md
 - spec/scenarios/codespan/literal.adoc
 - spec/scenarios/codespan/literal.md
+- spec/scenarios/codespan/plus-plus.adoc
+- spec/scenarios/codespan/plus-plus.md
+- spec/scenarios/codespan/star-star.adoc
+- spec/scenarios/codespan/star-star.md
+- spec/scenarios/codespan/unconstrained.adoc
+- spec/scenarios/codespan/unconstrained.md
 - spec/scenarios/dl/compound-only.adoc
 - spec/scenarios/dl/compound-only.md
 - spec/scenarios/dl/compound.adoc
@@ -510,6 +550,8 @@ test_files:
 - spec/scenarios/em/constrained.md
 - spec/scenarios/em/strong.adoc
 - spec/scenarios/em/strong.md
+- spec/scenarios/em/unconstrained.adoc
+- spec/scenarios/em/unconstrained.md
 - spec/scenarios/entity/numeric.adoc
 - spec/scenarios/entity/numeric.md
 - spec/scenarios/entity/reverse.adoc
@@ -652,6 +694,8 @@ test_files:
 - spec/scenarios/strong/menu.md
 - spec/scenarios/strong/nested-emphasis.adoc
 - spec/scenarios/strong/nested-emphasis.md
+- spec/scenarios/strong/unconstrained.adoc
+- spec/scenarios/strong/unconstrained.md
 - spec/scenarios/table/alignment.adoc
 - spec/scenarios/table/alignment.md
 - spec/scenarios/table/cell-with-image.adoc
@@ -666,6 +710,8 @@ test_files:
 - spec/scenarios/table/with-header.md
 - spec/scenarios/table/without-header.adoc
 - spec/scenarios/table/without-header.md
+- spec/scenarios/text/attribute-reference.adoc
+- spec/scenarios/text/attribute-reference.md
 - spec/scenarios/text/caret.adoc
 - spec/scenarios/text/caret.md
 - spec/scenarios/text/lte.adoc
@@ -674,6 +720,8 @@ test_files:
 - spec/scenarios/text/nbsp.md
 - spec/scenarios/text/plus-plus.adoc
 - spec/scenarios/text/plus-plus.md
+- spec/scenarios/text/right-arrow.adoc
+- spec/scenarios/text/right-arrow.md
 - spec/scenarios/text/typographic_sym/apostrophe.adoc
 - spec/scenarios/text/typographic_sym/apostrophe.md
 - spec/scenarios/text/typographic_sym/double-quotes.adoc
@@ -714,6 +762,21 @@ test_files:
 - spec/scenarios/ul/simple-separated.md
 - spec/scenarios/ul/simple.adoc
 - spec/scenarios/ul/simple.md
+- spec/scenarios/wrap/containing-line-comment.adoc
+- spec/scenarios/wrap/containing-line-comment.md
+- spec/scenarios/wrap/containing-line-comment.opts
+- spec/scenarios/wrap/none.adoc
+- spec/scenarios/wrap/none.md
+- spec/scenarios/wrap/none.opts
+- spec/scenarios/wrap/preserve.adoc
+- spec/scenarios/wrap/preserve.md
+- spec/scenarios/wrap/preserve.opts
+- spec/scenarios/wrap/ventilate-table-cell.adoc
+- spec/scenarios/wrap/ventilate-table-cell.md
+- spec/scenarios/wrap/ventilate-table-cell.opts
+- spec/scenarios/wrap/ventilate.adoc
+- spec/scenarios/wrap/ventilate.md
+- spec/scenarios/wrap/ventilate.opts
 - spec/scenarios/xml_comment/above-header.adoc
 - spec/scenarios/xml_comment/above-header.md
 - spec/scenarios/xml_comment/at-start-of-line.adoc
@@ -735,3 +798,4 @@ test_files:
 - spec/scenarios/xml_comment/styled.adoc
 - spec/scenarios/xml_comment/styled.md
 - spec/spec_helper.rb
+- spec/writer_spec.rb