kramdown-rfc2629 1.0.42 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 75ac2b119d2630278f0db1cb169ca40a25dc8f55
-  data.tar.gz: 013e491c8bcd6bb1d0b694919dd87813b958df2f
+  metadata.gz: eccebf9e2835616858b24412132d8ef16799526f
+  data.tar.gz: ca13164f41dc311f2ef333c21dfa11489057bf07
 SHA512:
-  metadata.gz: 8f229ee5ceeed8ae1d926ffbe72fefa90a7d37902aad0b78220db53653e5d95ad4721c79a4a7a22edd87608746dbf7a2428175b1ab2d21744081e67dd313fbbd
-  data.tar.gz: b8bfa1df8e6d4679992bae4297940a789bca034553d55e52f2fcec07f6c25f06d6bb117e737ef8b4128064562714c70f4980f67e7f276377809262a28a78e483
+  metadata.gz: b6aec8582e3b6a5ca6e3ebd32eacde950f89246a1595eaa8fd13dd9fe8d1d7fe7e04affe118751d2a6781910b051419cf9d9fdb3e0e1491f21191a1de50772d5
+  data.tar.gz: 034c56c7f6baa6aaac94fd94ad43dc7240dd12fe39e67b09e5b3ca43127c75759d9d6f5bf4e2c2c9bc454fd92104a4c50a2cc3e38544e8a8cc9acbdc313c0989

data/README.md

@@ -14,7 +14,8 @@ their work in markdown.
 # Usage
 
 Start by installing the kramdown-rfc2629 gem (this automatically
-installs kramdown version 1.6.x as well):
+installs appropriate versions of referenced gems such as kramdown as
+well):
 
     gem install kramdown-rfc2629
 
@@ -33,6 +34,10 @@ To use kramdown-rfc2629, you'll need a Ruby 1.9 or 2.x, and maybe
     kramdown-rfc2629 mydraft.mkd >mydraft.xml
     xml2rfc mydraft.xml
 
+(The most popular file name extension that IETF people have for
+markdown is .md -- for those who tend to think about GNU machine
+descriptions here, any extension such as .mkd will do, too.)
+
 # Examples
 
 For historical interest
@@ -149,8 +154,36 @@ and then just write `{{RFC2119}}` or `{{RFC1925}}`.  (Yes, there is a
 colon in the YAML, because this is a hash that could provide other
 information.)
 
-If your references are not in the [XML2RFC][] databases, you need to
-spell it out like this:
+Since version 1.1, references imported from the [XML2RFC][] databases
+can be supplied with a replacement label (anchor name).  E.g., RFC 793
+could be referenced as `{{!TCP=RFC0793}}, further references then just
+can say `{{TCP}}`; both will get `[TCP]` as the label.  In the
+YAML, the same replacement can be expressed as in the first example:
+
+     normative:
+       TCP: RFC0793
+     informative:
+       SST: DOI.10.1145/1282427.1282421
+
+Notes about this feature:
+
+* At the time of writing, the DOI and IANA repositories are
+  slightly unstable.
+* Thank you, Martin Thomson, for supplying an implementation and
+  insisting this be done.
+* While this feature is now available, you are not forced to use it
+  for everything: readers of documents often benefit from not having
+  to look up references, so continuing to use the draft names and RFC
+  numbers as labels may be the preferrable style in many cases.
+* As a final caveat, renaming anchors does not work in the
+  `stand_alone: no` mode (except for IANA and DOI), as there is no
+  such mechanism in XML entity referencing; exporting to XML while
+  maintaining live references then may require some manual editing to
+  get rid of the custom anchors.
+
+If your references are not in the [XML2RFC][] databases and do not
+have a DOI (that also happens to have correct data) either, you need
+to spell it out like in the examples below:
 
     informative:
       RFC1925:

data/bin/kramdown-rfc2629

@@ -52,18 +52,25 @@ def xml_from_sections(input)
   end
 
   ref_replacements = { }
+  anchor_to_bibref = { }
 
   [:ref, :normative, :informative].each do |sn|
     if refs = ps.has(sn)
       warn "*** bad section #{sn}: #{refs.inspect}" unless refs.respond_to? :each
       refs.each do |k, v|
         if v.respond_to? :to_str
+          if bibtagsys(v)       # enable "foo: RFC4711" as a custom anchor definition
+            anchor_to_bibref[k] = v.to_str
+          end
           ref_replacements[v.to_str] = k
         end
-        if v.respond_to? :[]
+        if Hash === v
           if aliasname = v.delete("-")
             ref_replacements[aliasname] = k
           end
+          if bibref = v.delete("=")
+            anchor_to_bibref[k] = bibref
+          end
         end
       end
     end
@@ -76,18 +83,29 @@ def xml_from_sections(input)
   # collect normative/informative tagging {{!RFC2119}} {{?RFC4711}}
   sechash.each do |k, v|
     next if k == "fluff"
-    v.gsub!(/{{(?:([?!])(-)?|(-))([\w.\-]+)}}/) do |match|
+    v.gsub!(/{{(?:([?!])(-)?|(-))([\w._\-]+)(?:=([\w.\/_\-]+))?}}/) do |match|
       norminform = $1
       replacing = $2 || $3
       word = $4
+      bibref = $5
       if replacing
         if new = ref_replacements[word]
           word = new
         else
-          warn "*** no alias replacement for {{-#{word}}}" 
+          warn "*** no alias replacement for {{-#{word}}}"
           word = "-#{word}"
         end
+      end       # now, word is the anchor
+      if bibref
+        if old = anchor_to_bibref[word]
+          if bibref != old
+            warn "*** conflicting definitions for xref #{anchor}: #{old} != #{bibref}"
+          end
+        else
+          anchor_to_bibref[word] = bibref
+        end
       end
+
       # things can be normative in one place and informative in another -> normative
       # collect norm/inform above and assign it by priority here
       if norminform
@@ -126,19 +144,24 @@ def xml_from_sections(input)
       refs.each do |k, v|
         href = k.gsub(/\A[0-9]/) { "_#{$&}" } # can't start an IDREF with a number
         link_defs[k] = ["##{href}", nil]            # allow [RFC2119] in addition to {{RFC2119}}
-        if bts = bibtagsys(k)
-          if v
+
+        bibref = anchor_to_bibref[k] || k
+        bts, url = bibtagsys(bibref, k, stand_alone)
+        if bts
+          if v && v != {}
             warn "*** redundant in #{k}: #{v.inspect}" unless v.respond_to? :to_str
           end
           if stand_alone
-            sechash[sn.to_s] << %{\n#{NMDTAGS[0]}\n![:include:](#{bts[0]})\n#{NMDTAGS[1]}\n}
+            a = %{{: anchor="#{k}"}}
+            sechash[sn.to_s] << %{\n#{NMDTAGS[0]}\n![:include:](#{bts})#{a}\n#{NMDTAGS[1]}\n}
           else
-            (ps.rest["bibxml"] ||= []) << k
-            sechash[sn.to_s] << %{&#{bts[0]};\n}
+            bts.gsub!('/', '_')
+            (ps.rest["bibxml"] ||= []) << [bts, url]
+            sechash[sn.to_s] << %{&#{bts};\n} # ???
           end
         else
           unless v && Hash === v
-            warn "*** don't know how to expand ref #{k}" 
+            warn "*** don't know how to expand ref #{k}"
             next
           end
           sechash[sn.to_s] << KramdownRFC::ref_to_xml(k, v)
@@ -163,23 +186,34 @@ end
 
 XML_RESOURCE_ORG_PREFIX = Kramdown::Converter::Rfc2629::XML_RESOURCE_ORG_PREFIX
 
-def bibtagsys(bib)
+# return XML entity name, url, rewrite_anchor flag
+def bibtagsys(bib, anchor=nil, stand_alone=true)
   if bib =~ /\Arfc(\d+)/i
     rfc4d = "%04d" % $1.to_i
     [bib.upcase,
      "#{XML_RESOURCE_ORG_PREFIX}/bibxml/reference.RFC.#{rfc4d}.xml"]
   elsif bib =~ /\A([-A-Z0-9]+)\./ &&
-        dir = Kramdown::Converter::Rfc2629::XML_RESOURCE_ORG_MAP[$1]
+        (dir, _ttl, rewrite_anchor = Kramdown::Converter::Rfc2629::XML_RESOURCE_ORG_MAP[$1])
     bib1 = bib.gsub(/\A[0-9]/) { "_#{$&}" } # can't start an ID with a number
+    if anchor && bib1 != anchor
+      if rewrite_anchor
+        a = %{?anchor=#{anchor}}
+      else
+        if !stand_alone
+          warn "*** selecting a custom anchor '#{anchor}' for '#{bib1}' requires stand_alone mode"
+          warn "    the output will need manual editing to correct this"
+        end
+      end
+    end
     [bib1,
-     "#{XML_RESOURCE_ORG_PREFIX}/#{dir}/reference.#{bib}.xml"]
+     "#{XML_RESOURCE_ORG_PREFIX}/#{dir}/reference.#{bib}.xml#{a}"]
   end
 end
 
 def read_encodings
   encfilename = File.expand_path '../../data/encoding-fallbacks.txt', __FILE__
   encfile = File.read(encfilename, coding: "UTF-8")
-  Hash[encfile.lines.map{|l| 
+  Hash[encfile.lines.map{|l|
          l.chomp!;
          x, s = l.split(" ", 2)
          [x.hex.chr(Encoding::UTF_8), s || " "]}]

data/data/kramdown-rfc2629.erb

@@ -4,8 +4,7 @@
     Gem.loaded_specs["kramdown-rfc2629"].version rescue nil %> -->
 
 <!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
-<% ps.arr("bibxml") do |bib|
-   tag, sys = bibtagsys(bib) -%>
+<% ps.arr("bibxml") do |tag, sys| -%>
 <!ENTITY <%= tag %> SYSTEM "<%= sys %>">
 <% end -%>
 <% ps.arr("entity", false) do |en, ev| -%>

data/kramdown-rfc2629.gemspec

@@ -1,6 +1,6 @@
 spec = Gem::Specification.new do |s|
   s.name = 'kramdown-rfc2629'
-  s.version = '1.0.42'
+  s.version = '1.1.0'
   s.summary = "Kramdown extension for generating RFC 7749 XML."
   s.description = %{An RFC7749 (XML2RFC) generating backend for Thomas Leitner's
 "kramdown" markdown parser.  Mostly useful for RFC writers.}

data/lib/kramdown-rfc/refxml.rb

@@ -1,9 +1,15 @@
 module KramdownRFC
 
+  extend Kramdown::Utils::Html
+
+  def self.escattr(str)
+    escape_html(str.to_s, :attribute)
+  end
+
   def self.ref_to_xml(k, v)
     vps = KramdownRFC::ParameterSet.new(v)
     erb = ERB.new <<-REFERB, nil, '-'
-<reference anchor="<%= k %>" <%= vps.attr("target") %>>
+<reference anchor="<%= escattr(k) %>" <%= vps.attr("target") %>>
   <front>
     <%= vps.ele("title") -%>
 
@@ -18,10 +24,10 @@ module KramdownRFC
     <date <%= dateattrs(vps[:date]) %>/>
   </front>
 <% vps.arr("seriesinfo", false) do |k, v| -%>
-  <seriesInfo name="<%=k%>" value="<%=v%>"/>
+  <seriesInfo name="<%=escattr(k)%>" value="<%=escattr(v)%>"/>
 <% end -%>
 <% vps.arr("format", false) do |k, v| -%>
-  <format type="<%=k%>" target="<%=v%>"/>
+  <format type="<%=escattr(k)%>" target="<%=escattr(v)%>"/>
 <% end -%>
 <%= vps.ele("annotation=ann") -%>
 </reference>

data/lib/kramdown-rfc2629.rb

@@ -412,9 +412,10 @@ module Kramdown
       KRAMDOWN_OFFLINE = ENV["KRAMDOWN_OFFLINE"]
       KRAMDOWN_REFCACHE_REFETCH = ENV["KRAMDOWN_REFCACHE_REFETCH"]
 
-      def get_and_cache_resource(url, tvalid = 7200, tn = Time.now)
+      # this is now slightly dangerous as multiple urls could map to the same cachefile
+      def get_and_cache_resource(url, cachefile, tvalid = 7200, tn = Time.now)
+        fn = "#{REFCACHEDIR}/#{cachefile}"
         Dir.mkdir(REFCACHEDIR) unless Dir.exists?(REFCACHEDIR)
-        fn = "#{REFCACHEDIR}/#{File.basename(url)}"
         f = File.stat(fn) rescue nil unless KRAMDOWN_REFCACHE_REFETCH
         if !KRAMDOWN_OFFLINE && (!f || tn - f.ctime >= tvalid)
           if f
@@ -457,7 +458,11 @@ module Kramdown
             end
           end
         end
-        File.read(fn) # this blows up if no cache available after fetch attempt
+        begin
+          File.read(fn) # this blows up if no cache available after fetch attempt
+        rescue Errno::ENOENT => e
+          warn "*** #{e} for ${fn}"
+        end
       end
 
       XML_RESOURCE_ORG_MAP = {
@@ -475,8 +480,8 @@ module Kramdown
         "NIST" => "bibxml2",
         "OASIS" => "bibxml2",
         "PKCS" => "bibxml2",
-        "DOI" => ["bibxml7", 86400], # 24 h cache at source anyway
-        "IANA" => ["bibxml8", 86400], # ditto
+        "DOI" => ["bibxml7", 86400, true], # 24 h cache at source anyway
+        "IANA" => ["bibxml8", 86400, true], # ditto
       }
 
       # XML_RESOURCE_ORG_HOST = ENV["XML_RESOURCE_ORG_HOST"] || "xml.resource.org"
@@ -490,23 +495,36 @@ module Kramdown
         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
+          if src = a.delete('src')
+            a['target'] = src
           end
         end
         if alt == ":include:"   # Really bad misuse of tag...
+          anchor = el.attr.delete('anchor') || (
+            # not yet
+            warn "*** missing anchor for '#{src}'"
+            src
+          )
+          anchor.sub!(/\A[0-9]/) { "_#{$&}" } # can't start an ID with a number
+          anchor.gsub!('/', '_')              # should take out all illegals
           to_insert = ""
-          anchor.scan(/(W3C|3GPP|[A-Z-]+)[.]?([A-Za-z0-9.-]+)/) do |t, n|
+          src.scan(/(W3C|3GPP|[A-Z-]+)[.]?([A-Za-z_0-9.\/\+-]+)/) do |t, n|
             fn = "reference.#{t}.#{n}.xml"
             sub, ttl = XML_RESOURCE_ORG_MAP[t]
             ttl ||= KRAMDOWN_REFCACHETTL  # everything but RFCs might change a lot
             puts "Huh: ${fn}" unless sub
             url = "#{XML_RESOURCE_ORG_PREFIX}/#{sub}/#{fn}"
-            to_insert = get_and_cache_resource(url, ttl)
+            to_insert = get_and_cache_resource(url, fn.gsub('/', '_'), ttl)
             to_insert.scrub! rescue nil # only do this for Ruby >= 2.1
+            # this may be a bit controversial: Don't break the build if reference is broken
+            if KRAMDOWN_OFFLINE
+              to_insert ||= "<reference anchor='#{anchor}'> <front> <title>*** BROKEN REFERENCE ***</title> <author> <organization/> </author> <date/> </front> </reference>"
+            else
+              exit 66 unless to_insert # EX_NOINPUT
+            end
           end
-          to_insert.gsub(/<\?xml version=["']1.0["'] encoding=["']UTF-8["']\?>/, '').
-            gsub(/(anchor=["'])([0-9])/) { "#{$1}_#{$2}"} # can't start an ID with a number
+          to_insert.sub(/<\?xml version=["']1.0["'] encoding=["']UTF-8["']\?>/, '')
+            .sub(/\banchor=(?:"[^"]+"|'[^']+')/, "anchor=\"#{anchor}\"")
         else
           "<xref#{el_html_attributes(el)}>#{alt}</xref>"
         end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kramdown-rfc2629
 version: !ruby/object:Gem::Version
-  version: 1.0.42
+  version: 1.1.0
 platform: ruby
 authors:
 - Carsten Bormann
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-03-15 00:00:00.000000000 Z
+date: 2017-03-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: kramdown