kramdown-rfc2629 0.13.1 → 0.13.2

data/README.md

@@ -14,16 +14,20 @@ their work in markdown.
 # Usage
 
 Start by installing the kramdown-rfc2629 gem (this requires kramdown
-version 0.13.1, but has also been tested with version 0.11.0 and 0.12.0):
+version 0.13.x, but has also 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", the command
-"wget", and maybe XML2RFC if you want to see the fruits of your work.
+structure provided by kramdown.  `bin/kramdown-rfc2629` started out as
+a simple command-line program showing how to use this, but can now do
+much more (see below).
+
+To use kramdown-rfc2629, you'll need a Ruby 1.9 that can be found
+under the name "ruby1.9", the command "wget" (if you want to use the
+offline feature), and maybe XML2RFC if you want to see the fruits of
+your work.
 
     kramdown-rfc2629 mydraft.mkd >mydraft.xml
     xml2rfc mydraft.xml
@@ -36,13 +40,46 @@ 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).
+but works well enough).  `stupid.xml` and `stupid.txt` show what
+kramdown-rfc2629 and xml2rfc make out of this.
+
+`stupid-s.mkd` is the same document in the new sectionized format
+supported by kramdown-rfc2629.  The document metadata are in a short
+piece of YAML at the start, and from there, `abstract`, `middle`,
+references (`normative` and `informative`) and `back` are sections
+delimited in the markdown file.  See the example for how this works.
+Much less scary, and no `{:/nomarkdown}` etc. is needed any more.
+Similarly, `stupid-s.xml` and `stupid-s.txt` show what
+kramdown-rfc2629 and xml2rfc make out of this.
+
+`draft-ietf-core-block-xx.mkd` is a real-world example of a current
+Internet-Draft done this way.  For RFC and Internet-Draft references,
+it uses document prolog entities instead of caching the references in
+the XML (this is easier to handle when collaborating with XML-only
+co-authors).  See the `bibxml` metadata.
 
 # 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.
+The code is not very polished, but it has been successfully used for a
+number of non-trivial Internet-Drafts.  You probably still need to
+skim [RFC 2629][] if you want to write an Internet-Draft, but you
+don't really need to understand XML very much.  Knowing the basics of
+YAML helps with the metadata (but you'll understand it from the
+examples.)
+
+# Related Work
+
+Moving from XML to Markdown for RFC writing apparently is a
+no-brainer, so I'm not the only one who has written code for this.
+
+[Miek Gieben][] has done a [similar thing][pandoc2rfc] employing
+pandoc/asciidoc.  He uses multiple input files instead of
+kramdown-rfc2629's sectionized input format.  He keeps the metadata in
+a separate XML file, similar to the way the previous version of
+kramdown-rfc2629 stored (and still can store) the metadata in XML in
+the markdown document.  He also uses a slightly different referencing
+syntax, which is closer to what markdown does elsewhere but more
+verbose.
 
 # License
 
@@ -57,3 +94,5 @@ it's probably not going to kill any RFC author.)
 [RFC 2629]: http://xml.resource.org
 [markdown]: http://en.wikipedia.org/wiki/Markdown
 [IETF]: http://www.ietf.org
+[Miek Gieben]: http://www.miek.nl/
+[pandoc2rfc]: https://github.com/miekg/pandoc2rfc/

data/bin/kramdown-rfc2629

@@ -1,16 +1,119 @@
 #!/usr/bin/env ruby1.9
+# -*- coding: utf-8 -*-
 require 'kramdown-rfc2629'
 require 'yaml'
+require 'pp'
+require 'erb'
+require 'ostruct'
+require 'date'
 
 Encoding.default_external = "UTF-8" # wake up, smell the coffee
 
-options = {input: 'RFC2629Kramdown'}
+RE_NL = /(?:\n|\r|\r\n)/
+RE_SECTION = /---(?:\s+(\w+)(-?))?\s*#{RE_NL}(.*?#{RE_NL})(?=---(?:\s+\w+-?)?\s*#{RE_NL}|\Z)/m
+
+def xml_from_sections(input)
+  sections = input.scan(RE_SECTION) # array of [label, nomarkdown-flag, text]
+
+  ps = ParameterSet.new(YAML.load(sections.shift[2])) # front matter parameters
+  coding_override = (ps.has(:coding) =~ /ascii/i) ? :symbolic : :as_char
+
+  sechash = Hash.new{ |h,k| h[k] = ""}
+  snames = []
+  sections.each do |sname, nmdflag, text|
+    nmdin, nmdout = {
+      "-" => ["", ""],
+      "" => ["{:/nomarkdown}\n\n", "\n{::nomarkdown}\n"],
+    }[nmdflag || ""]
+    if sname
+      snames << sname           # --- label -> push label
+    else
+      snames.pop                # --- -> pop label
+    end
+    sechash[snames.last] << "#{nmdin}#{text}#{nmdout}"
+  end
+
+  mydata = File.read(File.join(File.dirname(__FILE__), '..', 'data', 'kramdown-rfc2629.erb'), coding: "UTF-8")
+  erb = ERB.new(mydata)
+  input = erb.result(binding)
+  ps.warn_if_leftovers
+  sechash.delete("fluff")
+  if !sechash.empty?
+    warn "*** sections left #{sechash.keys.inspect}!"
+  end
+
+  [input.gsub(%r"{::nomarkdown}\s*{:/nomarkdown}"m, ""), coding_override]
+end
+
+class ParameterSet
+  attr_reader :f
+  def initialize(y)
+    @f = y
+  end
+  def [](pn)
+    @f.delete(pn.to_s)
+  end
+  def has(pn)
+    @f[pn.to_s]
+  end
+  def van(pn)                   # pn is a parameter name, possibly with an =alias
+    an, pn = pn.to_s.split("=")
+    pn ||= an
+    [self[pn] || self[an], an]
+  end
+  def attr(pn)
+    val, an = van(pn)
+    %{#{an}="#{val}"}    if val
+  end
+  def attrs(*pns)
+    pns.map{ |pn| attr(pn) }.join(" ")
+  end
+  def ele(pn, attr=nil)
+    val, an = van(pn)
+    if val
+      val = [val] unless val.respond_to? :to_a
+      val.map do |val1|
+        %{<#{[an, attr.to_s].join(" ").strip}>#{val1}</#{an}>}
+      end.join(" ")
+    end
+  end
+  def arr(an, &block)
+    (self[an] || []).each(&block)
+  end
+  def rest
+    @f
+  end
+  def warn_if_leftovers
+    if !@f.empty?
+      warn "*** attributes left #{@f.inspect}!"
+    end
+  end
+end
+
+def bibtagsys(bib)
+  if bib =~ /\Arfc(\d+)/i
+    rfc4d = "%04d" % $1.to_i
+    [bib.upcase,
+     "http://xml.resource.org/public/rfc/bibxml/reference.RFC.#{rfc4d}.xml"]
+  else
+    [bib,
+     "http://xml.resource.org/public/rfc/bibxml3/reference.#{bib}.xml"]
+  end
+end
+
+
+coding_override = :as_char
 input = ARGF.read.gsub(/\{::include\s+(.*?)\}/) {
   File.read($1).chomp
 }
+if input =~ /\A---/        # this is a sectionized file
+  input, coding_override = xml_from_sections(input)
+end
 if input =~ /\A<\?xml/          # if this is a whole XML file, protect it
   input = "{::nomarkdown}\n#{input}\n{:/nomarkdown}\n"
 end
+options = {input: 'RFC2629Kramdown', entity_output: coding_override}
+warn "options: #{options.inspect}"
 doc = Kramdown::Document.new(input, options)
 $stderr.puts doc.warnings.to_yaml unless doc.warnings.empty?
 puts doc.to_rfc2629

data/data/kramdown-rfc2629.erb

@@ -0,0 +1,113 @@
+<?xml version="1.0" encoding="<%=ps[:coding]||"UTF-8"%>"?>
+  <?xml-stylesheet type="text/xsl" href="rfc2629.xslt" ?>
+
+<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
+<% ps.arr("bibxml") do |bib|
+   tag, sys = bibtagsys(bib) %>
+<!ENTITY <%= tag %> SYSTEM "<%= sys %>">
+<% end %>
+<% ps.arr("entity") do |en, ev| %>
+<!ENTITY <%=en%> "<%=ev%>">
+<% end %>
+]>
+
+<rfc <%= ps.attrs("ipr", "docName=docname", "category=cat",
+                  "number", "obsoletes", "updates", "seriesNo=seriesno") %> >
+
+<% ps.arr("pi") do |pi| %>
+<?rfc <%=pi%>="yes"?>
+<% end %>
+
+  <front>
+    <%= ps.ele("title", ps.attr("abbrev=titleabbrev")) %>
+
+<% ps.arr("author") do |au|
+   aups = ParameterSet.new(au)
+   if ins = aups[:ins]
+     parts = ins.split('.').map(&:strip)
+     aups.rest["initials"] = parts[0..-2].join('.') << '.'
+     aups.rest["surname"] = parts[-1]
+   end
+ %>
+
+    <author <%=aups.attrs("initials", "surname", "fullname=name", "role")%>>
+      <%= aups.ele("organization=org", aups.attr("abbrev=orgabbrev")) %>
+      <address>
+        <% if aups.has("street") %>
+        <postal>
+          <%= aups.ele("street") %>
+          <%= aups.ele("city") %>
+          <%= aups.ele("region") %>
+          <%= aups.ele("code") %>
+          <%= aups.ele("country") %>
+        </postal>
+        <% end %>
+        <%= aups.ele("phone") %>
+        <%= aups.ele("facsimile") %>
+        <%= aups.ele("email") %>
+        <%= aups.ele("uri") %>
+      </address>
+    </author>
+
+<%   aups.warn_if_leftovers  %>
+<% end %>
+
+    <date <%= (ps[:date]||Date.today).strftime(%{year="%Y" month="%B" day="%d"}) %> />
+
+    <%= ps.ele("area") %>
+    <%= ps.ele("workgroup=wg") %>
+    <%= ps.ele("keyword=kw") %>
+
+    <abstract>
+
+<%= sechash.delete("abstract") %>
+
+    </abstract>
+
+<% sechash.keys.each do |k| %>
+<%   if k =~ /\Anote_(.*)/ %>
+
+    <note title="<%= $1.gsub("_", " ")%>">
+
+<%= sechash.delete(k) %>
+
+    </note>
+
+<% end %>
+<% end %>
+
+
+  </front>
+
+  <middle>
+
+<%= sechash.delete("middle") %>
+
+  </middle>
+
+<back>
+
+<% if sh = sechash.delete("normative") %>
+
+  <references title='Normative References'>
+
+<%= sh %>
+
+  </references>
+
+<% end %>
+
+<% if sh = sechash.delete("informative") %>
+
+  <references title='Informative References'>
+
+<%= sh %>
+
+  </references>
+
+<% end %>
+
+<%= sechash.delete("back") %>
+
+</back>
+</rfc>

data/kramdown-rfc2629.gemspec

@@ -1,11 +1,11 @@
 spec = Gem::Specification.new do |s|
   s.name = 'kramdown-rfc2629'
-  s.version = '0.13.1'
+  s.version = '0.13.2'
   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.13')
-  s.files = Dir['lib/**/*.rb'] + %w(README.md kramdown-rfc2629.gemspec bin/kramdown-rfc2629)
+  s.files = Dir['lib/**/*.rb'] + %w(README.md kramdown-rfc2629.gemspec bin/kramdown-rfc2629 data/kramdown-rfc2629.erb)
   s.require_path = 'lib'
   s.executables = ['kramdown-rfc2629']
   s.default_executable = 'kramdown-rfc2629'

data/lib/kramdown-rfc2629.rb

@@ -305,7 +305,12 @@ module Kramdown
       end
 
       def convert_xref(el, indent, opts)
-        "<xref#{el_html_attributes(el)}/>"
+        target = el.attr['target']
+        if target[0] == "&"
+          "#{target};"
+        else
+          "<xref#{el_html_attributes(el)}/>"
+        end
       end
 
       REFCACHEDIR = ".refcache"

metadata

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