kramdown-man 0.1.9 → 1.0.0

data/lib/kramdown/{converter/man.rb → man/converter.rb}

@@ -1,21 +1,25 @@
 # frozen_string_literal: true
 
-require_relative '../man/version'
+require 'kramdown/man/version'
 
 require 'kramdown/converter/base'
 
 module Kramdown
-  module Converter
+  module Man
     #
     # Converts markdown into a roff man-page.
     #
-    class Man < ::Kramdown::Converter::Base
+    # @since 1.0.0
+    #
+    # @api private
+    #
+    class Converter < Kramdown::Converter::Base
 
       # Comment header
-      HEADER = [
-        ".\\\" Generated by kramdown-man #{::Kramdown::Man::VERSION}",
-        ".\\\" https://github.com/postmodern/kramdown-man#readme"
-      ].join("\n")
+      HEADER = <<~ROFF
+                 .\\\" Generated by kramdown-man #{VERSION}
+                 .\\\" https://github.com/postmodern/kramdown-man#readme
+               ROFF
 
       # Typographic Symbols and their UTF8 chars
       TYPOGRAPHIC_SYMS = {
@@ -427,7 +431,7 @@ module Kramdown
       #   The roff output.
       #
       def convert(root)
-        "#{HEADER}\n#{convert_root(root)}"
+        "#{HEADER}#{convert_root(root)}"
       end
 
       #
@@ -440,9 +444,7 @@ module Kramdown
       #   The roff output.
       #
       def convert_root(root)
-        root.children.map { |child|
-          convert_element(child)
-        }.compact.join("\n")
+        convert_children_of(root)
       end
 
       #
@@ -456,20 +458,19 @@ module Kramdown
       #
       def convert_element(element)
         method = "convert_#{element.type}"
+
         send(method,element) if respond_to?(method)
       end
-
+      
       #
       # Converts a `kd:blank` element.
       #
       # @param [Kramdown::Element] blank
       #   A `kd:blank` element.
       #
-      # @return [String]
-      #   The roff output.
+      # @return [nil]
       #
       def convert_blank(blank)
-        '.LP'
       end
 
       #
@@ -482,7 +483,7 @@ module Kramdown
       #   The roff output.
       #
       def convert_text(text)
-        escape(text.value.gsub(/^(  +|\t)/,''))
+        escape(text.value)
       end
 
       #
@@ -524,23 +525,30 @@ module Kramdown
         text = header.options[:raw_text]
 
         case header.options[:level]
-        when 1 then ".TH #{text}"
-        when 2 then ".SH #{text}"
-        else        ".SS #{text}"
+        when 1
+          <<~ROFF
+            .TH #{text}
+          ROFF
+        when 2
+          <<~ROFF
+            .SH #{text}
+          ROFF
+        else
+          <<~ROFF
+            .SS #{text}
+          ROFF
         end
       end
 
       #
-      # Converts a `kd:hr` element.
+      # Ignore `kd:hr` elements.
       #
       # @param [Kramdown::Element] hr
       #   A `kd:hr` element.
       #
-      # @return [String]
-      #   The roff output.
+      # @return [nil]
       #
       def convert_hr(hr)
-        ".ti 0\n\\l'\\n(.lu'"
       end
 
       #
@@ -553,9 +561,17 @@ module Kramdown
       #   The roff output.
       #
       def convert_ul(ul)
-        content = ul.children.map { |li| convert_ul_li(li) }.join("\n")
+        contents = String.new(encoding: Encoding::UTF_8)
+
+        ul.children.each do |li|
+          contents << convert_ul_li(li)
+        end
 
-        return ".RS\n#{content}\n.RE"
+        return <<~ROFF
+          .RS
+          #{contents.chomp}
+          .RE
+        ROFF
       end
 
       #
@@ -568,15 +584,27 @@ module Kramdown
       #   The roff output.
       #
       def convert_ul_li(li)
-        li.children.each_with_index.map { |child,index|
+        roff = String.new(encoding: Encoding::UTF_8)
+
+        li.children.each_with_index do |child,index|
           if child.type == :p
-            content = convert_children(child.children)
+            contents = convert_children_of(child)
 
-            if index == 0 then ".IP \\(bu 2\n#{content}"
-            else               ".IP \\( 2\n#{content}"
-            end
+            roff << if index == 0
+                      <<~ROFF
+                        .IP \\(bu 2
+                        #{contents.chomp}
+                      ROFF
+                    else
+                      <<~ROFF
+                       .IP \\( 2
+                       #{contents.chomp}
+                      ROFF
+                    end
           end
-        }.compact.join("\n")
+        end
+
+        return roff
       end
 
       #
@@ -591,10 +619,18 @@ module Kramdown
       def convert_ol(ol)
         @ol_index += 1
 
-        header  = ".nr step#{@ol_index} 0 1"
-        content = ol.children.map { |li| convert_ol_li(li) }.join("\n")
+        contents = String.new(encoding: Encoding::UTF_8)
+
+        ol.children.each do |li|
+          contents << convert_ol_li(li)
+        end
 
-        return "#{header}\n.RS\n#{content}\n.RE"
+        return <<~ROFF
+          .nr step#{@ol_index} 0 1
+          .RS
+          #{contents.chomp}
+          .RE
+        ROFF
       end
 
       #
@@ -607,15 +643,133 @@ module Kramdown
       #   The roff output.
       #
       def convert_ol_li(li)
-        li.children.each_with_index.map { |child,index|
+        roff = String.new(encoding: Encoding::UTF_8)
+
+        li.children.each_with_index do |child,index|
           if child.type == :p
-            content = convert_children(child.children)
+            contents = convert_children_of(child)
+
+            roff << if index == 0
+                      <<~ROFF
+                        .IP \\n+[step#{@ol_index}]
+                        #{contents.chomp}
+                      ROFF
+                    else
+                      <<~ROFF
+                        .IP \\n
+                        #{contents.chomp}
+                      ROFF
+                    end
+          end
+        end
 
-            if index == 0 then ".IP \\n+[step#{@ol_index}]\n#{content}"
-            else               ".IP \\n\n#{content}"
+        return roff
+      end
+
+      #
+      # Converts a `kd:dl` element.
+      #
+      # @param [Kramdown::Element] dl
+      #   A `kd:dl` element.
+      #
+      # @return [String]
+      #   The roff output.
+      #
+      def convert_dl(dl)
+        roff = String.new(encoding: Encoding::UTF_8)
+
+        dt_index = 0
+        dd_index = 0
+
+        dl.children.each do |element|
+          case element.type
+          when :dt
+            roff << convert_dt(element, index: dt_index)
+
+            dt_index += 1 # increment the dt count
+            dd_index  = 0 # reset the dd count
+          when :dd
+            roff << convert_dd(element, index: dd_index)
+
+            dd_index += 1 # increment the dd count
+            dt_index  = 0 # reset the dt count
+          else
+            roff << convert(element)
+
+            # reset both the dt_index and dd_index counters
+            dt_index = 0
+            dd_index = 0
+          end
+        end
+
+        return roff
+      end
+
+      #
+      # Converts a `kd:dt` element within a `kd:dl`.
+      #
+      # @param [Kramdown::Element] dt
+      #   A `kd:dt` element.
+      #
+      # @param [Integer] index
+      #   The index of the `kd:dt` element. Used to indicate whether this is the
+      #   first `kd:dt` element or additional `kd:dt` elements.
+      #
+      # @return [String]
+      #   The roff output.
+      #
+      def convert_dt(dt, index: 0)
+        text = convert_text_elements(dt.children)
+
+        if index == 0
+          <<~ROFF
+            .TP
+            #{text}
+          ROFF
+        else
+          <<~ROFF
+            .TQ
+            #{text}
+          ROFF
+        end
+      end
+
+      #
+      # Converts a `kd:dd` element within a `kd:dd`.
+      #
+      # @param [Kramdown::Element] dd
+      #   A `kd:dd` element.
+      #
+      # @param [Integer] index
+      #   The index of the `kd:dd` element. Used to indicate whether this is the
+      #   first `kd:dd` element following a `kd;dt` element or additional
+      #   `kd:dt` elements.
+      #
+      # @return [String]
+      #   The roff output.
+      #
+      def convert_dd(dd, index: 0)
+        roff = String.new(encoding: Encoding::UTF_8)
+
+        dd.children.each_with_index do |child,child_index|
+          if index == 0 && child_index == 0 && child.type == :p
+            contents = convert_children_of(child)
+
+            # omit the .PP macro for the first paragraph
+            roff << "#{contents.chomp}\n"
+          else
+            if (contents = convert_element(child))
+              # indent all other following paragraphs or other elements
+              roff << <<~ROFF
+                        .RS
+                        #{contents.chomp}
+                        .RE
+                      ROFF
             end
           end
-        }.compact.join("\n")
+        end
+
+        return roff
       end
 
       #
@@ -641,14 +795,13 @@ module Kramdown
       #   The roff output.
       #
       def convert_blockquote(blockquote)
-        content = blockquote.children.map { |child|
-          case child.type
-          when :p then convert_children(child.children)
-          else         convert_element(child)
-          end
-        }.join("\n")
+        contents = convert_children_of(blockquote)
 
-        return ".PP\n.RS\n#{content}\n.RE"
+        return <<~ROFF
+          .RS
+          #{contents.chomp}
+          .RE
+        ROFF
       end
 
       #
@@ -661,7 +814,16 @@ module Kramdown
       #   The roff output.
       #
       def convert_codeblock(codeblock)
-        ".nf\n#{escape(codeblock.value).rstrip}\n.fi"
+        contents = escape(codeblock.value)
+
+        return <<~ROFF
+          .PP
+          .RS 4
+          .EX
+          #{contents.chomp}
+          .EE
+          .RE
+        ROFF
       end
 
       #
@@ -674,9 +836,15 @@ module Kramdown
       #   The roff output.
       #
       def convert_comment(comment)
-        comment.value.lines.map { |line|
-          ".\\\" #{line}"
-        }.join("\n")
+        roff = String.new(encoding: Encoding::UTF_8)
+
+        comment.value.lines.each do |line|
+          roff << <<~ROFF
+                    .\\" #{line}
+                  ROFF
+        end
+
+        return roff
       end
 
       #
@@ -689,26 +857,12 @@ module Kramdown
       #   The roff output.
       #
       def convert_p(p)
-        children = p.children
-
-        if ((children.length >= 2) && (children.first.type == :codespan ||
-                                       children.first.type == :em       ||
-                                       children.first.type == :strong))
-          newline = children.find_index { |el|
-            el.type == :text && el.value.start_with?("\n")
-          }
+        contents = convert_text_elements(p.children)
 
-          if newline
-            first_line = convert_children(children[0...newline])
-            rest       = convert_children(children[newline..-1]).strip
-
-            ".TP\n#{first_line}\n#{rest}"
-          else
-            ".PP\n#{convert_children(children)}"
-          end
-        else
-          ".PP\n#{convert_children(children)}"
-        end
+        return <<~ROFF
+          .PP
+          #{contents.chomp}
+        ROFF
       end
 
       #
@@ -721,7 +875,7 @@ module Kramdown
       #   The roff output.
       #
       def convert_em(em)
-        "\\fI#{convert_children(em.children)}\\fP"
+        "\\fI#{convert_text_elements(em.children)}\\fP"
       end
 
       #
@@ -734,7 +888,7 @@ module Kramdown
       #   The roff output.
       #
       def convert_strong(strong)
-        "\\fB#{convert_children(strong.children)}\\fP"
+        "\\fB#{convert_text_elements(strong.children)}\\fP"
       end
 
       #
@@ -760,45 +914,122 @@ module Kramdown
       #   The roff output.
       #
       def convert_a(a)
-        href = escape(a.attr['href'])
+        href = a.attr['href']
         scheme, path = href.split(':',2)
 
-        text = convert_children(a.children)
+        text = convert_text_elements(a.children)
 
         case scheme
         when 'mailto'
-          email = path
+          email = escape(path)
 
           unless text == email
-            "#{text}\n.MT #{email}\n.ME"
+            <<~ROFF
+              #{text.chomp}
+              .MT #{email}
+              .ME
+            ROFF
           else
-            "\n.MT #{email}\n.ME"
+            <<~ROFF
+              .MT #{email}
+              .ME
+            ROFF
           end
         when 'man'
-          if (match = path.match(/\A(?<page>[A-Za-z0-9_-]+)(?:\((?<section>\d[a-z]?)\)|\\\.(?<section>\d[a-z]?))\z/))
-            page    = match[:page]
-            section = match[:section]
+          if (match = path.match(/\A(?<page>[A-Za-z0-9_-]+)(?:\((?<section>\d[a-z]?)\)|\.(?<section>\d[a-z]?))\z/))
+            man_page_link(match[:page],match[:section])
+          else
+            page = escape(path)
 
-            "\n.BR #{page} (#{section})"
+            <<~ROFF
+              .BR #{page}
+            ROFF
+          end
+        else
+          if (match = href.match(/(?<page>[A-Za-z0-9_-]+)\.(?<section>\d[a-z]?)\.md\z/))
+            man_page_link(match[:page],match[:section])
           else
-            "\n.BR #{path}"
+            <<~ROFF
+              #{text.chomp}
+              .UR #{escape(href)}
+              .UE
+            ROFF
           end
+        end
+      end
+
+      #
+      # Outputs a man page link.
+      #
+      # @param [String] page
+      #   The man page name.
+      #
+      # @param [String, nil] section
+      #   The optional section of the man page.
+      #
+      # @return [String]
+      #   The roff output.
+      #
+      def man_page_link(page,section=nil)
+        if section
+          <<~ROFF
+            .BR #{escape(page)} (#{escape(section)})
+          ROFF
         else
-          "#{text}\n.UR #{href}\n.UE"
+          <<~ROFF
+            .BR #{escape(page)}
+          ROFF
+        end
+      end
+
+      #
+      # Converts the children of an element.
+      #
+      # @param [Array<Kramdown::Element>] element
+      #   The elements to convert.
+      #
+      # @return [String]
+      #   The combined roff output.
+      #
+      def convert_children_of(element)
+        roff = String.new(encoding: Encoding::UTF_8)
+
+        element.children.each do |child|
+          if (contents = convert_element(child))
+            roff << contents
+          end
         end
+
+        return roff
       end
 
       #
       # Converts the children of an element.
       #
-      # @param [Array<Kramdown::Element>] children
-      #   The children of an element.
+      # @param [Array<Kramdown::Element>] elements
+      #   The text elements to convert.
       #
       # @return [String]
       #   The roff output.
       #
-      def convert_children(children)
-        children.map { |child| convert_element(child) }.join.strip
+      def convert_text_elements(elements)
+        roff = String.new(encoding: Encoding::UTF_8)
+
+        elements.each do |element|
+          if (contents = convert_element(element))
+            if contents.start_with?('.') && !roff.empty? && !roff.end_with?("\n")
+              # roff macross must exist on their own line
+              roff << "\n#{contents}"
+            elsif contents.start_with?(' ') && roff.end_with?("\n")
+              # remove leadning whitespace following a newline
+              roff << contents.lstrip
+            else
+              roff << contents
+            end
+          end
+        end
+
+        return roff
       end
 
       #
@@ -811,7 +1042,7 @@ module Kramdown
       #   The escaped text.
       #
       def escape(text)
-        text.gsub(GLYPH_REGEXP) { |char| GLYPHS[char] }
+        text.gsub(GLYPH_REGEXP,GLYPHS)
       end
 
     end

data/lib/kramdown/man/task.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require 'kramdown'
-require_relative '../converter/man'
+require 'kramdown/man'
 
 require 'rake/tasklib'
 

data/lib/kramdown/man/version.rb

@@ -3,6 +3,6 @@
 module Kramdown
   module Man
     # kramdown-man version
-    VERSION = "0.1.9"
+    VERSION = "1.0.0"
   end
 end

data/lib/kramdown/man.rb

@@ -2,6 +2,29 @@
 
 require 'kramdown'
 
-# HACK: load our version of kramdown/converter/man.rb and not kramdown's
-require_relative './converter/man'
-require_relative './man/version'
+require 'kramdown/man/version'
+require 'kramdown/man/converter'
+
+module Kramdown
+  class Document
+    #
+    # Converts the parsed markdown document to a man page.
+    #
+    # @param [Hash] options
+    #   Additional options.
+    #
+    # @return [String]
+    #   The converted man page contents.
+    #
+    # @since 1.0.0
+    #
+    # @api public
+    #
+    def to_man(options={})
+      output, warnings = Kramdown::Man::Converter.convert(@root,options)
+
+      @warnings.concat(warnings)
+      return output
+    end
+  end
+end