kramdown-rfc2629 0.12.1

data/README.md

@@ -0,0 +1,59 @@
+# kramdown-rfc2629
+
+[kramdown][] is a [markdown][] parser by Thomas Leitner, which has a
+number of backends for generating HTML, Latex, and markdown again.
+
+**kramdown-rfc2629** is an additional backend to that: It allows the
+generation of [RFC 2629][] compliant XML markup (also known as XML2RFC
+markup).
+
+Who would care?  Anybody who is writing Internet-Drafts and RFCs in
+the [IETF][] and prefers (or has co-authors who prefer) to do part of
+their work in markdown.
+
+# Usage
+
+Start by installing the kramdown-rfc2629 gem (this requires kramdown
+version 0.12.0, but has been tested with version 0.11.0 and 0.12.0):
+
+    sudo gem install kramdown-rfc2629
+
+The guts of kramdown-rfc2629 are in one Ruby file,
+`lib/kramdown-rfc2629.rb` --- this melds nicely into the extension
+structure provided by kramdown.  `bin/kramdown-rfc2629` is a simple
+command-line program showing how to use this.  For this, you'll need a
+Ruby 1.9 that can be found under the name "ruby1.9", and maybe XML2RFC
+if you want to see the fruits of your work.
+
+    kramdown-rfc2629 mydraft.mkd >mydraft.xml
+    xml2rfc mydraft.xml
+
+# Examples
+
+`stupid.mkd` is a markdown version of an actual Internet-Draft (for a
+protocol called [STuPiD][] \[sic!]).  This demonstrates some, but not
+all features of kramdown-rfc2629.  Since markdown/kramdown does not
+cater for all the structure of an RFC 2629 style document, some of the
+markup is in XML, and the example switches between XML and markdown
+using kramdown's `{::nomarkdown}` and `{:/nomarkdown}` (this is ugly,
+but works well enough).
+
+# Risks and Side-Effects
+
+The code is not very polished (in particular, the code for tables is a
+joke), and you probably still need to understand [RFC 2629][] if you
+want to write an Internet-Draft.
+
+# License
+
+(kramdown itself appears to be licensed GPLv3.)  As kramdown-rfc2629
+is in part derived from kramdown source, there is little choice: It is
+also licensed under GPLv3, which you can google yourself.  (Being
+stuck at GPLv3 does not make me happy, but it is just for this tool so
+it's probably not going to kill any RFC author.)
+
+[kramdown]: http://kramdown.rubyforge.org/
+[stupid]: http://tools.ietf.org/id/draft-hartke-xmpp-stupid-00
+[RFC 2629]: http://xml.resource.org
+[markdown]: http://en.wikipedia.org/wiki/Markdown
+[IETF]: http://www.ietf.org

data/bin/kramdown-rfc2629

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby1.9
+require 'kramdown-rfc2629'
+require 'yaml'
+
+Encoding.default_external = "UTF-8" # wake up, smell the coffee
+
+options = {input: 'RFC2629Kramdown'}
+input = ARGF.read.gsub(/\{::include\s+(.*?)\}/) {
+  File.read($1).chomp
+}
+if input =~ /\A<\?xml/          # if this is a whole XML file, protect it
+  input = "{::nomarkdown}\n#{input}\n{:/nomarkdown}\n"
+end
+doc = Kramdown::Document.new(input, options)
+$stderr.puts doc.warnings.to_yaml unless doc.warnings.empty?
+puts doc.to_rfc2629

data/kramdown-rfc2629.gemspec

@@ -0,0 +1,18 @@
+spec = Gem::Specification.new do |s|
+  s.name = 'kramdown-rfc2629'
+  s.version = '0.12.1'
+  s.summary = "Kramdown extension for generating RFC 2629 XML."
+  s.description = %{An RFC2629 (XML2RFC) generating backend for Thomas Leitner's
+"kramdown" markdown parser.  Mostly useful for RFC writers.}
+  s.add_dependency('kramdown', '~> 0.12')
+  s.files = Dir['lib/**/*.rb'] + %w(README.md kramdown-rfc2629.gemspec bin/kramdown-rfc2629)
+  s.require_path = 'lib'
+  s.executables = ['kramdown-rfc2629']
+  s.default_executable = 'kramdown-rfc2629'
+  s.required_ruby_version = '>= 1.9.2'
+  s.requirements = 'wget'
+  #  s.has_rdoc = true
+  s.author = "Carsten Bormann"
+  s.email = "cabo@tzi.org"
+  s.homepage = "http://github.com/cabo/kramdown-rfc2629"
+end

data/lib/kramdown-rfc2629.rb

@@ -0,0 +1,420 @@
+# -*- coding: utf-8 -*-
+#
+#--
+# Copyright (C) 2010 Carsten Bormann <cabo@tzi.org>
+#
+# This file is designed to work with kramdown.
+# License: GPLv3, unfortunately (look it up).
+# Any code that I haven't stolen from kramdown is also licensed under
+# the 2-clause BSD license (look it up).
+#++
+#
+
+raise "sorry, 1.8 was last decade" unless RUBY_VERSION >= '1.9'
+
+# this version is adapted to kramdown 0.12.0
+gem 'kramdown', '= 0.12.0'
+require 'kramdown'
+
+require 'rexml/parsers/baseparser'
+
+class Object
+  def deep_clone
+    Marshal.load(Marshal.dump(self))
+  end
+end
+
+module Kramdown
+
+  module Parser
+    class RFC2629Kramdown < Kramdown
+
+      def initialize(*doc)
+        super
+        @span_parsers.unshift(:xref)
+      end
+
+      XREF_START = /\{\{(.*?)\}\}/u
+
+      # Introduce new {{target}} syntax for empty xrefs, which would
+      # otherwise be an ugly ![!](target) or ![ ](target)
+      # (I'd rather use [[target]], but that somehow clashes with links.)
+      def parse_xref
+        @src.pos += @src.matched_size
+        href = @src[1]
+        el = Element.new(:xref, nil, {'target' => href})
+        @tree.children << el
+      end
+      define_parser(:xref, XREF_START, '{{')
+
+    end
+  end
+
+  class Element
+    def rfc2629_fix
+      if a = attr
+        if anchor = a.delete('id')
+          a['anchor'] = anchor
+        end
+        if anchor = a.delete('href')
+          a['target'] = anchor
+        end
+      end
+    end
+  end
+
+  module Converter
+
+    # Converts a Kramdown::Document to HTML.
+    class Rfc2629 < Base
+
+      # we use these to do XML stuff, too (XXX: 0.11 vs. 0.12)
+      include ::Kramdown::Utils::HTML      rescue   include ::Kramdown::Utils::Html
+
+      def el_html_attributes(el)
+        html_attributes(el) rescue html_attributes(el.attr) # XXX 0.11 vs. 0.12
+      end
+
+      # :stopdoc:
+
+      # Defines the amount of indentation used when nesting XML tags.
+      INDENTATION = 2
+
+      # Initialize the XML converter with the given Kramdown document +doc+.
+      def initialize(*doc)
+        super
+        @sec_level = 1
+        @in_dt = 0
+      end
+
+      def convert(el, indent = -INDENTATION, opts = {})
+        if el.children[-1].type == :raw
+          raw = convert1(el.children.pop, indent, opts)
+        end
+        "#{convert1(el, indent, opts)}#{end_sections(1, indent)}#{raw}"
+      end
+
+      def convert1(el, indent, opts = {})
+        el.rfc2629_fix
+        send("convert_#{el.type}", el, indent, opts)
+      end
+
+      def inner_a(el, indent, opts)
+        indent += INDENTATION
+        el.children.map do |inner_el|
+          inner_el.rfc2629_fix
+          send("convert_#{inner_el.type}", inner_el, indent, opts)
+        end
+      end
+
+      def inner(el, indent, opts)
+        inner_a(el, indent, opts).join('')
+      end
+
+      def convert_blank(el, indent, opts)
+        "\n"
+      end
+
+      def convert_text(el, indent, opts)
+        escape_html(el.value, :text)
+      end
+
+      def convert_p(el, indent, opts)
+        if (el.children.size == 1 && el.children[0].type == :img) || opts[:unpacked]
+          inner(el, indent, opts) # Part of the bad reference hack
+        else
+          "#{' '*indent}<t#{el_html_attributes(el)}>#{inner(el, indent, opts)}</t>\n"
+        end
+      end
+
+      def saner_generate_id(value)
+        generate_id(value).gsub(/-+/, '-')
+      end
+
+      def convert_codeblock(el, indent, opts)
+        el.attr['anchor'] ||= saner_generate_id(el.value)
+        result = el.value
+        # compensate for XML2RFC idiosyncracy by insisting on a blank line
+        unless el.attr.delete('tight')
+          result[0,0] = "\n" unless result[0,1] == "\n"
+        end
+        "#{' '*indent}<figure#{el_html_attributes(el)}><artwork><![CDATA[#{result}#{result =~ /\n\Z/ ? '' : "\n"}]]></artwork></figure>\n"
+      end
+
+      def convert_blockquote(el, indent, opts)
+        "#{' '*indent}<t><list style='empty'#{el_html_attributes(el)}>\n#{inner(el, indent, opts)}#{' '*indent}</list></t>\n"
+      end
+
+      def end_sections(to_level, indent)
+        if indent < 0
+          indent = 0
+        end
+        if @sec_level >= to_level
+          delta = (@sec_level - to_level)
+          @sec_level = to_level
+          "#{' '*indent}</section>\n" * delta
+        else
+          $stderr.puts "Incorrect section nesting: Need to start with 1"
+        end
+      end
+
+      def convert_header(el, indent, opts)
+        # todo: handle appendix tags
+        el = el.deep_clone
+        options = @doc ? @doc.options : @options # XXX: 0.11 vs. 0.12
+        if options[:auto_ids] && !el.attr['anchor']
+          el.attr['anchor'] = saner_generate_id(el.options[:raw_text])
+        end
+        el.attr['title'] = inner(el, indent, opts)
+        "#{end_sections(el.options[:level], indent)}#{' '*indent}<section#{@sec_level += 1; el_html_attributes(el)}>\n"
+      end
+
+      def convert_hr(el, indent, opts) # misuse for page break
+        "#{' '*indent}<t><vspace blankLines='999' /></t>\n"
+      end
+
+      STYLES = {ul: 'symbols', ol: 'numbers', dl: 'hanging'}
+
+      def convert_ul(el, indent, opts)
+        style = STYLES[el.type]
+        "#{' '*indent}<t><list style='#{style}'#{el_html_attributes(el)}>\n#{inner(el, indent, opts)}#{' '*indent}</list></t>\n"
+      end
+      alias :convert_ol :convert_ul
+      alias :convert_dl :convert_ul
+
+      def convert_li(el, indent, opts)
+        res_a = inner_a(el, indent, opts)
+        if el.children.empty? || el.children.first.options[:category] == :span
+          res = res_a.join('')
+        else                    # merge multiple <t> elements
+          res = res_a.select { |x|
+            x.strip != ''
+          }.map { |x|
+            x.sub(/\A\s*<t>(.*)<\/t>\s*\Z/m) { $1}
+          }.join("#{' '*indent}<vspace blankLines='1'/>\n").gsub(%r{(</list>)\s*<vspace blankLines='1'/>}) { $1 }.gsub(%r{<vspace blankLines='1'/>\s*(<list)}) { $1 }
+        end
+        "#{' '*indent}<t#{el_html_attributes(el)}>#{res}#{(res =~ /\n\Z/ ? ' '*indent : '')}</t>\n"
+      end
+      def convert_dd(el, indent, opts)
+        output = ' '*indent
+        if @in_dt == 1
+          @in_dt = 0
+        else
+          output << "<t#{el_html_attributes(el)}>"
+        end
+        res = inner(el, indent+INDENTATION, opts.merge(unpacked: true))
+#        if el.children.empty? || el.children.first.options[:category] != :block
+          output << res << (res =~ /\n\Z/ ? ' '*indent : '')
+#        else                    FIXME: The latter case is needed for more complex cases
+#          output << "\n" << res << ' '*indent
+#        end
+        output << "</t>\n"
+      end
+
+      def convert_dt(el, indent, opts) # SERIOUSLY BAD HACK:
+        close = "#{' '*indent}</t>\n" * @in_dt
+        @in_dt = 1
+        "#{close}#{' '*indent}<t#{el_html_attributes(el)} hangText='#{inner(el, indent, opts)}'>\n"
+      end
+
+      HTML_TAGS_WITH_BODY=['div', 'script']
+
+      def convert_html_element(el, indent, opts)
+        res = inner(el, indent, opts)
+        if el.options[:category] == :span
+          "<#{el.value}#{el_html_attributes(el)}" << (!res.empty? ? ">#{res}</#{el.value}>" : " />")
+        else
+          output = ''
+          output << ' '*indent if !el.options[:parent_is_raw]
+          output << "<#{el.value}#{el_html_attributes(el)}"
+          if !res.empty? && el.options[:parse_type] != :block
+            output << ">#{res}</#{el.value}>"
+          elsif !res.empty?
+            output << ">\n#{res}"  << ' '*indent << "</#{el.value}>"
+          elsif HTML_TAGS_WITH_BODY.include?(el.value)
+            output << "></#{el.value}>"
+          else
+            output << " />"
+          end
+          output << "\n" if el.options[:outer_element] || !el.options[:parent_is_raw]
+          output
+        end
+      end
+
+      def convert_xml_comment(el, indent, opts)
+        if el.options[:category] == :block && !el.options[:parent_is_raw]
+          ' '*indent + el.value + "\n"
+        else
+          el.value
+        end
+      end
+      alias :convert_xml_pi :convert_xml_comment
+      alias :convert_html_doctype :convert_xml_comment
+
+      ALIGNMENTS = { default: :left, left: :left, right: :right, center: :center}
+
+      def convert_table(el, indent, opts) # This only works for tables with headers
+        alignment = el.options[:alignment].map { |al| ALIGNMENTS[al]}
+        "#{' '*indent}<texttable#{el_html_attributes(el)}>\n#{inner(el, indent, opts.merge(table_alignment: alignment))}#{' '*indent}</texttable>\n"
+      end
+
+      def convert_thead(el, indent, opts)
+        inner(el, indent, opts)
+      end
+      alias :convert_tbody :convert_thead
+      alias :convert_tfoot :convert_thead
+      alias :convert_tr  :convert_thead
+
+      def convert_td(el, indent, opts)
+        if alignment = opts[:table_alignment]
+          alignment = alignment.shift
+        end
+        res = inner(el, indent, opts)
+        if alignment
+          "#{' '*indent}<ttcol align='#{alignment}'#{el_html_attributes(el)}>#{res.empty? ? "&#160;" : res}</ttcol>\n"
+          else
+          "#{' '*indent}<c#{el_html_attributes(el)}>#{res.empty? ? "&#160;" : res}</c>\n"
+        end
+      end
+      alias :convert_th :convert_td
+
+      def convert_comment(el, indent, opts)
+## Don't actually output all those comments into the XML:
+#        if el.options[:category] == :block
+#          "#{' '*indent}<!-- #{el.value} -->\n"
+#        else
+#          "<!-- #{el.value} -->"
+#        end
+      end
+
+      def convert_br(el, indent, opts)
+        "<br />"
+      end
+
+      def convert_a(el, indent, opts)
+        do_obfuscation = el.attr['href'] =~ /^mailto:/
+        if do_obfuscation
+          el = el.deep_clone
+          href = obfuscate(el.attr['href'].sub(/^mailto:/, ''))
+          mailto = obfuscate('mailto')
+          el.attr['href'] = "#{mailto}:#{href}"
+        end
+        res = inner(el, indent, opts)
+        res = obfuscate(res) if do_obfuscation
+        "<eref#{el_html_attributes(el)}>#{res}</eref>"
+      end
+
+      def convert_xref(el, indent, opts)
+        "<xref#{el_html_attributes(el)}/>"
+      end
+
+      REFCACHEDIR = ".refcache"
+      def get_and_cache_resource(url, tn = Time.now, tvalid = 7200)
+        Dir.mkdir(REFCACHEDIR) unless Dir.exists?(REFCACHEDIR)
+        fn = "#{REFCACHEDIR}/#{File.basename(url)}"
+        f = File.stat(fn) rescue nil
+        if !f || tn - f.ctime >= tvalid
+          $stderr.puts "#{fn}: #{f && tn-f.ctime}"
+          `cd #{REFCACHEDIR}; wget -Nnv "#{url}"` # ignore errors if offline (hack)
+          File.utime nil, nil, fn
+        end
+        File.read(fn)
+      end
+
+      def convert_img(el, indent, opts) # misuse the tag!
+        if a = el.attr
+          alt = a.delete('alt').strip
+          alt = '' if alt == '!' # work around re-wrap uglyness
+          if anchor = a.delete('src')
+            a['target'] = anchor
+          end
+        end
+        if alt == ":include:"   # Really bad misuse of tag...
+          to_insert = ""
+          anchor.scan(/([A-Z-]+)[.]?([a-z0-9-]+)/) do |t, n|
+            fn = "reference.#{t}.#{n}.xml"
+            sub = { "RFC" => "bibxml", "I-D" => "bibxml3" }[t]
+            puts "Huh: ${fn}" unless sub
+            url = "http://xml.resource.org/public/rfc/#{sub}/#{fn}"
+            to_insert = get_and_cache_resource(url)
+          end
+          to_insert.gsub(/<\?xml version='1.0' encoding='UTF-8'\?>/, '')
+        else
+          "<xref#{el_html_attributes(el)}>#{alt}</xref>"
+        end
+      end
+
+      def convert_codespan(el, indent, opts)
+        "<spanx style='verb'#{el_html_attributes(el)}>#{escape_html(el.value)}</spanx>"
+      end
+
+      def convert_footnote(el, indent, opts) # XXX: This is wrong.
+        "<xref target='#{escape_html(el.value)}'#{el_html_attributes(el)}/>"
+      end
+
+      def convert_raw(el, indent, opts)
+        end_sections(1, indent) +
+        el.value + (el.options[:category] == :block ? "\n" : '')
+      end
+
+      EMPH = { em: "emph", strong: "strong"}
+
+      def convert_em(el, indent, opts)
+        "<spanx style='#{EMPH[el.type]}'#{el_html_attributes(el)}>#{inner(el, indent, opts)}</spanx>"
+      end
+      alias :convert_strong :convert_em
+
+      def convert_entity(el, indent, opts)
+        entity_to_str(el.value)
+      end
+
+      TYPOGRAPHIC_SYMS = {
+        :mdash => [::Kramdown::Utils::Entities.entity('mdash')],
+        :ndash => [::Kramdown::Utils::Entities.entity('ndash')],
+        :hellip => [::Kramdown::Utils::Entities.entity('hellip')],
+        :laquo_space => [::Kramdown::Utils::Entities.entity('laquo'), ::Kramdown::Utils::Entities.entity('nbsp')],
+        :raquo_space => [::Kramdown::Utils::Entities.entity('nbsp'), ::Kramdown::Utils::Entities.entity('raquo')],
+        :laquo => [::Kramdown::Utils::Entities.entity('laquo')],
+        :raquo => [::Kramdown::Utils::Entities.entity('raquo')]
+      }
+      def convert_typographic_sym(el, indent, opts)
+        TYPOGRAPHIC_SYMS[el.value].map {|e| entity_to_str(e)}.join('')
+      end
+
+      def convert_smart_quote(el, indent, opts)
+        entity_to_str(::Kramdown::Utils::Entities.entity(el.value.to_s))
+      end
+
+      def convert_math(el, indent, opts) # XXX: This is wrong
+        el = el.deep_clone
+        el.attr['class'] ||= ''
+        el.attr['class'] += (el.attr['class'].empty? ? '' : ' ') + 'math'
+        type = 'span'
+        type = 'div' if el.options[:category] == :block
+        "<#{type}#{el_html_attributes(el)}>#{escape_html(el.value, :text)}</#{type}>#{type == 'div' ? "\n" : ''}"
+      end
+
+      def convert_abbreviation(el, indent, opts) # XXX: This is wrong
+        title = @doc.parse_infos[:abbrev_defs][el.value]
+        title = nil if title.empty?
+        "<abbr#{title ? " title=\"#{title}\"" : ''}>#{el.value}</abbr>"
+      end
+
+      def convert_root(el, indent, opts)
+        result = inner(el, indent, opts)
+      end
+
+      # Helper method for obfuscating the +text+ by using XML entities.
+      def obfuscate(text)
+        result = ""
+        text.each_byte do |b|
+          result += (b > 128 ? b.chr : "&#%03d;" % b)
+        end
+        result.force_encoding(text.encoding) if RUBY_VERSION >= '1.9'
+        result
+      end
+
+    end
+
+  end
+end

metadata

@@ -0,0 +1,84 @@
+--- !ruby/object:Gem::Specification 
+name: kramdown-rfc2629
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 12
+  - 1
+  version: 0.12.1
+platform: ruby
+authors: 
+- Carsten Bormann
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-01-04 00:00:00 +01:00
+default_executable: kramdown-rfc2629
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: kramdown
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        - 12
+        version: "0.12"
+  type: :runtime
+  version_requirements: *id001
+description: |-
+  An RFC2629 (XML2RFC) generating backend for Thomas Leitner's
+  "kramdown" markdown parser.  Mostly useful for RFC writers.
+email: cabo@tzi.org
+executables: 
+- kramdown-rfc2629
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/kramdown-rfc2629.rb
+- README.md
+- kramdown-rfc2629.gemspec
+- bin/kramdown-rfc2629
+has_rdoc: true
+homepage: http://github.com/cabo/kramdown-rfc2629
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 1
+      - 9
+      - 2
+      version: 1.9.2
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: 
+- wget
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Kramdown extension for generating RFC 2629 XML.
+test_files: []
+