kramdown-rfc2629 1.0.21 → 1.0.22

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f32cbcb11be24b119c6c8ddefdb887d49e440166
-  data.tar.gz: 6eb1f023b152cf6f087c8cdca8ff770904eb8b72
+  metadata.gz: f88f8eb021656a068385c1a1a8b787c118311ce1
+  data.tar.gz: 678962ddf03478ae2d357489e53a5edcd940161c
 SHA512:
-  metadata.gz: 1097366915fcaee6a1bad951752fb6cd35cf087a0733e61dab0b60f0598a2ceef39e93018e72dfaf7f3b258728b8dcd12b427aa38b3d7be492fb5152ca6804da
-  data.tar.gz: 3f5061dc8d0d4049b5e9b70edc7945a07000b328154ad5e3bf0390aee4a130f861863cf2a2d8af881c66e74e069e43a5cd5096fc730260886a998e1ec7e37fd4
+  metadata.gz: 60d4fe36fe9524b4ffd1ee036a63a6d5751d54fb0aa30214fc98d2700035bad413ea54d3196326e39d7591104568ee1e899ee4ff090b353e2dce32035168a3dd
+  data.tar.gz: f4b4c59aa1551921d9b4eb375af87f847ad3b21eefdefda350223fd859fdf10e7dfec7326313c046aea807a0072deaeece1dd344f5770b3492d927eca8c7429b

data/README.md

@@ -61,7 +61,7 @@ collaborating with XML-only co-authors).  See the `bibxml` metadata.
 # The YAML header
 
 Please consult the examples for the structure of the YAML header, this should be mostly
-obvious.  The `standalone` attribute controls whether the RFC/I-D
+obvious.  The `stand_alone` attribute controls whether the RFC/I-D
 references are inserted into the document (yes) or entity-referenced
 (no), the latter leads to increased build time, but may be more
 palatable for a final XML conversion.
@@ -206,15 +206,135 @@ Then you can simply reference `{{ASN.1}}` and
 `{{ECMA262}}` in the text.  (Make sure the reference keys are valid XML
 names, though.)
 
+# Experimental features
+
+Most of the [kramdown syntax][kdsyntax] is supported and does
+something useful; with the exception of the math syntax (math has no
+special support in XML2RFC), and HTML syntax of course.
+
+A number of more esoteric features have recently been added.  
+(The minimum required version for each full feature is indicated.)
+
+(1.0.22:)
+Index entries can be created with `(((item)))` or
+`(((item, subitem)))`; use quotes for weird entries: `(((",", comma)))`.
+If the index entry is to be marked "primary", prefix an (unquoted) `!`
+as in `(((!item)))`.
+
+In addition, auto-indexing is supported by hijacking the kramdown
+"abbrev" syntax:
+
+    *[IANA]:
+    *[MUST]: BCP14
+    *[CBOR]: (((Object Representation, Concise Binary))) (((CBOR)))
+
+The word in square brackets (which must match case-insensitively) is
+entered into the index automatically for each place where it occurs.
+If no title is given, just the word is entered (first example).  If
+one is given, that becomes the main item (the auto-indexed word
+becomes the subitem, second example).  If full control is desired
+(e.g., for multiple entries per occurrence), just write down the full
+index entries instead (third example).
+
+(1.0.20:)
+As an alternative referencing syntax for references with text,
+`{{ref}}` can be expressed as `[text](#ref)`.  As a special case, a
+simple `[ref]` is interpreted as `[](#ref)`.  This syntax does not
+allow for automatic entry of items as normative/informative.
+
+(1.0.16:) Markdown footnotes are converted into `cref`s (XML2RFC formal
+comments; note that these are only visible if the pi "comments" is set to yes).
+The anchor is taken from the markdown footnote name. The source, if
+needed, can be supplied by an IAD, as in (first example with
+ALD):
+
+```markdown
+{:cabo: source="cabo"}
+
+(This section to be removed by the RFC editor.)[^1]{:cabo}
+
+[^1]: here is my editorial comment
+
+Another questionable paragraph.[^2]{: source="observer"}
+
+[^2]: so why not delete it
+```
+
+Note that XML2RFC v2 doesn't allow structure in crefs. If you put any,
+you get the escaped verbatim XML...
+
+(1.0.11:) Allow overriding "style" attribute (via IAL =
+[inline attribute list][kdsyntax-ial]) in lists and spans
+as in:
+
+```markdown
+{:req: counter="bar" style="format R(%d)"}
+
+{: req}
+* Foo
+* Bar
+* Bax
+
+Text outside the list, so a new IAL is needed.
+
+* Foof
+* Barf
+* Barx
+{: req}
+```
+
+(1.0.5:) An IAL attribute "cols" can be added to tables to override
+the column layout.  For example, `cols="* 20 30c r"` sets the width attributes to
+20 and 30 for the middle columns and sets the right two columns to
+center and right alignment, respectively.  The alignment from `cols`
+overrides that from the kramdown table, if present.
+
+(1.0.2:) An IAL attribute "vspace" can be added to a definition list
+to break after the definition term:
+
+```markdown
+{: vspace="0"}
+word:
+: definition
+
+anotherword:
+: another definition
+```
+
+(0.x:) Files can be included with the syntax `{::include fn}` (needs
+to be in column 1 since 1.0.22; can be suppressed for use in servers
+by setting environment variable KRAMDOWN_SAFE since 1.0.22).  A
+typical example from a recent RFC, where the contents of a figure was
+machine-generated:
+
+```markdown
+~~~~~~~~~~
+{::include ../ghc/packets-new/p4.out}
+~~~~~~~~~~
+{: #example2 title="A longer RPL example"}
+```
+
+(0.x:) A page break can be forced by adding a horizontal rule (`----`,
+note that this creates ugly blank space in some HTML converters).
+
 # Risks and Side-Effects
 
-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
+The code is not very polished, but now quite stable; it has been successfully used for a
+number of non-trivial Internet-Drafts and RFCs.  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).
 
+# Upconversion
+
+If you have an old RFC and want to convert it to markdown, try just
+using that RFC, it is 80 % there.  It may be possible to automate the
+remaining 20 % some more, but that hasn't been done.
+
+If you have XML, there is an experimental upconverter that does 99 %
+of the work.  Please contact the author if you want to try it.
+
 # Related Work
 
 Moving from XML to Markdown for RFC writing apparently is a
@@ -228,6 +348,8 @@ 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 (this syntax is now also supported in kramdown-rfc2629).
+(Miek now also has a new thing going on with mostly different syntax,
+see [mmark][].)
 
 # License
 
@@ -235,6 +357,8 @@ Since kramdown version 1.0, kramdown itself is MIT licensed, which
 made it possible to license kramdown-rfc2629 under the same license.
 
 [kramdown]: http://kramdown.rubyforge.org/
+[kdsyntax]: http://kramdown.gettalong.org/syntax.html
+[kdsyntax-ial]: http://kramdown.gettalong.org/syntax.html#inline-attribute-lists
 [stupid]: http://tools.ietf.org/id/draft-hartke-xmpp-stupid-00
 [RFC 2629]: http://xml.resource.org/public/rfc/html/rfc2629.html
 [markdown]: http://en.wikipedia.org/wiki/Markdown
@@ -243,3 +367,5 @@ made it possible to license kramdown-rfc2629 under the same license.
 [pandoc2rfc]: https://github.com/miekg/pandoc2rfc/
 [XML2RFC]: http://xml.resource.org
 [RFC 7328]: http://tools.ietf.org/html/rfc7328
+[mmark]: https://github.com/miekg/mmark
+[YAML]: http://www.yaml.org/spec/1.2/spec.html

data/bin/kramdown-rfc2629

@@ -266,9 +266,10 @@ def dateattrs(date)
 end
 
 coding_override = :as_char
-input = ARGF.read.gsub(/\{::include\s+(.*?)\}/) {
+input = ARGF.read
+input.gsub!(/^\{::include\s+(.*?)\}/) {
   File.read($1).chomp
-}
+} unless ENV["KRAMDOWN_SAFE"]
 link_defs = {}
 if input =~ /\A---/        # this is a sectionized file
   input, coding_override, link_defs = xml_from_sections(input)

data/kramdown-rfc2629.gemspec

@@ -1,10 +1,10 @@
 spec = Gem::Specification.new do |s|
   s.name = 'kramdown-rfc2629'
-  s.version = '1.0.21'
+  s.version = '1.0.22'
   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', '~> 1.4.0')
+  s.add_dependency('kramdown', '~> 1.5.0')
   s.files = Dir['lib/**/*.rb'] + %w(README.md LICENSE kramdown-rfc2629.gemspec bin/kramdown-rfc2629 data/kramdown-rfc2629.erb)
   s.require_path = 'lib'
   s.executables = ['kramdown-rfc2629']

data/lib/kramdown-rfc2629.rb

@@ -11,8 +11,7 @@
 
 raise "sorry, 1.8 was last decade" unless RUBY_VERSION >= '1.9'
 
-# this version also works with kramdown 0.12, 0.13, 0.14, but 1.x has the right license
-gem 'kramdown', '~> 1.4.0'
+gem 'kramdown', '~> 1.5.0'
 require 'kramdown'
 
 require 'rexml/parsers/baseparser'
@@ -31,6 +30,7 @@ module Kramdown
       def initialize(*doc)
         super
         @span_parsers.unshift(:xref)
+        @span_parsers.unshift(:iref)
       end
 
       XREF_START = /\{\{(.*?)\}\}/u
@@ -47,6 +47,17 @@ module Kramdown
       end
       define_parser(:xref, XREF_START, '{{')
 
+      IREF_START = /\(\(\((.*?)\)\)\)/u
+
+      # Introduce new (((target))) syntax for irefs
+      def parse_iref
+        @src.pos += @src.matched_size
+        href = @src[1]
+        el = Element.new(:iref, nil, {'target' => href}) # XXX
+        @tree.children << el
+      end
+      define_parser(:iref, IREF_START, '\(\(\(')
+
     end
   end
 
@@ -183,6 +194,18 @@ module Kramdown
         end
       end
 
+      def clean_pcdata(parts)    # hack, will become unnecessary with XML2RFCv3
+        clean = ''
+        irefs = ''
+        # warn "clean_parts: #{parts.inspect}"
+        parts.each do |p|
+          md = p.match(%r{([^<]*)(.*)})
+          clean << md[1]
+          irefs << md[2]        # breaks for spanx... don't emphasize in headings!
+        end
+        [clean, irefs]
+      end
+
       def convert_header(el, indent, opts)
         # todo: handle appendix tags
         el = el.deep_clone
@@ -190,8 +213,9 @@ module Kramdown
         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"
+        clean, irefs = clean_pcdata(inner_a(el, indent, opts))
+        el.attr['title'] = clean
+        "#{end_sections(el.options[:level], indent)}#{' '*indent}<section#{@sec_level += 1; el_html_attributes(el)}>#{irefs}\n"
       end
 
       def convert_hr(el, indent, opts) # misuse for page break
@@ -312,10 +336,12 @@ module Kramdown
             alignment = COLS_ALIGN[md[3]] || :left
           end
         end
-        res = inner(el, indent, opts)
         if alignment
-          "#{' '*indent}<ttcol #{widthopt}align='#{alignment}'#{el_html_attributes(el)}>#{res.empty? ? "&#160;" : res}</ttcol>\n"
-          else
+          res, irefs = clean_pcdata(inner_a(el, indent, opts))
+          warn "*** lost markup #{irefs} in table heading" unless irefs.empty?
+          "#{' '*indent}<ttcol #{widthopt}align='#{alignment}'#{el_html_attributes(el)}>#{res.empty? ? "&#160;" : res}</ttcol>\n" # XXX need clean_pcdata
+        else
+          res = inner(el, indent, opts)
           "#{' '*indent}<c#{el_html_attributes(el)}>#{res.empty? ? "&#160;" : res}</c>\n"
         end
       end
@@ -460,7 +486,8 @@ module Kramdown
 
       def convert_em(el, indent, opts)
         attrstring = el_html_attributes_with(el, {"style" => EMPH[el.type]})
-        "<spanx#{attrstring}>#{inner(el, indent, opts)}</spanx>"
+        span, irefs = clean_pcdata(inner_a(el, indent, opts))
+        "<spanx#{attrstring}>#{span}</spanx>#{irefs}"
       end
       alias :convert_strong :convert_em
 
@@ -494,27 +521,45 @@ module Kramdown
         "<#{type}#{el_html_attributes(el)}>#{escape_html(el.value, :text)}</#{type}>#{type == 'div' ? "\n" : ''}"
       end
 
+      ITEM_RE = '\s*(?:"([^"]*)"|([^,]*?))\s*'
+      IREF_RE = %r{\A(!\s*)?#{ITEM_RE}(?:,#{ITEM_RE})?\z}
+
+      def iref_attr(s)
+        md = s.match(IREF_RE)
+        attr = {
+          item: md[2] || md[3],
+          subitem: md[4] || md[5],
+          primary: md[1] && 'true',
+        }
+        "<iref#{html_attributes(attr)}/>"
+      end
+
+      def convert_iref(el, indent, opts)
+        iref_attr(el.attr['target'])
+      end
+
       def convert_abbreviation(el, indent, opts) # XXX: This is wrong
         title = @root.options[:abbrev_defs][el.value]
         title = nil if title.empty?
         value = el.value
-        "#{el.value}<iref #{title ? "item=\"#{title}\" sub" : ''}item=\"#{value}\"/>"
+        if item = title
+          m = title.scan(Parser::RFC2629Kramdown::IREF_START)
+          if m.empty?
+            subitem = value
+          else
+            iref = m.map{|a,| iref_attr(a)}.join('')
+          end
+        else
+          item = value
+        end
+        iref ||= "<iref#{html_attributes(item: item, subitem: subitem)}/>"
+        "#{el.value}#{iref}"
       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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kramdown-rfc2629
 version: !ruby/object:Gem::Version
-  version: 1.0.21
+  version: 1.0.22
 platform: ruby
 authors:
 - Carsten Bormann
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-11-26 00:00:00.000000000 Z
+date: 2014-12-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: kramdown
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.4.0
+        version: 1.5.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.4.0
+        version: 1.5.0
 description: |-
   An RFC2629 (XML2RFC) generating backend for Thomas Leitner's
   "kramdown" markdown parser.  Mostly useful for RFC writers.