kramdown-rfc2629 0.13.8 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 85f3831fa795af115769891c0063cd4327dfd3c2
-  data.tar.gz: 476d34c05e181779d6e0fae47c674be4bd1b6c17
+  metadata.gz: 6c680de5d2853a1c04df22f6a2e6d4104b1cd3bd
+  data.tar.gz: 8a701c320ac5848dd70273f2e1fb388881e82a72
 SHA512:
-  metadata.gz: 4c4928975a756f03fa52d8e6418d9bfadcde7340f1bcae56628a168c66cde6e14e4c16fc9a27e82dea4d0f6af4180280da02a0009179d7ae2871013fb78c4019
-  data.tar.gz: 393d35765dba2023773e7333b0e732943c7eb1f862f93d50f15ff05d9d67989b9ebca2ab8221e50adb36d508b7957f5a5f0203e0cb6d4f6529109543946f9fe4
+  metadata.gz: 3f4c78b68de442b178aaeefd99b2b1f601f90d37c21d302c21023df5c06afb51fdba4db8d52855f6d4e78bee5a882a9079e86c96d783b09a302aebf6c5f6b256
+  data.tar.gz: de7f426083a7db0573ee4d3353fa44a5f1b56f14721096905e1108928de12b173b93b79405315880167b52b77ebf3f42deec4eca5ea0da6025678a9e99822eb3

data/README.md

@@ -4,8 +4,8 @@
 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).
+generation of [XML2RFC][] XML markup (also known as [RFC 2629][]
+compliant 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
@@ -13,8 +13,8 @@ their work in markdown.
 
 # Usage
 
-Start by installing the kramdown-rfc2629 gem (this requires kramdown
-version 0.13.x, but has also been tested with version 0.11.0 and 0.12.0):
+Start by installing the kramdown-rfc2629 gem (this automatically
+installs kramdown version 1.0.x as well):
 
     sudo gem install kramdown-rfc2629
 
@@ -24,24 +24,23 @@ 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.
+To use kramdown-rfc2629, you'll need a Ruby 1.9 or 2.0, 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
 
 # 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).  `stupid.xml` and `stupid.txt` show what
-kramdown-rfc2629 and xml2rfc make out of this.
+`stupid.mkd` was an early markdown version of an actual Internet-Draft
+(for a protocol called [STuPiD][] \[sic!]).  This demonstrated 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).  `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
@@ -57,8 +56,133 @@ 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.
+the XML (i.e., not standalone mode, this is easier to handle when
+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
+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.
+The author entry can be a single hash or a list, as in:
+
+    author:
+      ins: C. Bormann
+      name: Carsten Bormann
+      org: Universität Bremen TZI
+      abbrev: TZI
+      street: Bibliothekstr. 1
+      city: Bremen
+      code: D-28359
+      country: Germany
+      phone: +49-421-218-63921
+      email: cabo@tzi.org
+
+or
+
+    author:
+      -
+        ins: C. Bormann
+        name: Carsten Bormann
+        org: Universität Bremen TZI
+        email: cabo@tzi.org
+      -
+        ins: Z. Shelby
+        name: Zach Shelby
+        org: Sensinode
+        role: editor
+        street: Kidekuja 2
+        city: Vuokatti
+        code: 88600
+        country: Finland
+        phone: "+358407796297"
+        email: zach@sensinode.com
+
+(the hash keys are the XML GIs from RFC 2629, with a flattened
+structure.  As RFC 2629 requires giving both the name and
+surname/initials, we use `ins` as an abbreviation for
+"initials/surname".  Yes, the toolchain is Unicode-capable, even if
+the final RFC output is still in ASCII.)
+
+
+## References
+
+The references section is built from the references listed in the YAML
+header and from references made inline to RFCs and I-Ds in the
+markdown text.  Since kramdown-rfc2629 cannot know whether a reference
+is normative or informative, no entry is generated by default in the
+references section.  By indicating a normative reference as in
+`{{!RFC2119}}` or an informative one as in `{{?RFC1925}}`, you can
+completely automate the referencing, without the need to write
+anything in the header.  Alternatively, you can write something like:
+
+    informative:
+      RFC1925:
+    normative:
+      RFC2119:
+
+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:
+
+    informative:
+      RFC1925:
+      WEI:
+        title: "6LoWPAN: the Wireless Embedded Internet"
+        author:
+          -
+            ins: Z. Shelby
+            name: Zach Shelby
+          -
+            ins: C. Bormann
+            name: Carsten Bormann
+        date: 2009
+        seriesinfo:
+          ISBN: 9780470747995
+        ann: This is a really good reference on 6LoWPAN.
+      ASN.1:
+        title: >
+          Information Technology — ASN.1 encoding rules:
+          Specification of Basic Encoding Rules (BER), Canonical Encoding
+          Rules (CER) and Distinguished Encoding Rules (DER)
+        author:
+          org: International Telecommunications Union
+        date: 1994
+        seriesinfo:
+          ITU-T: Recommendation X.690
+      REST:
+        target: http://www.ics.uci.edu/~fielding/pubs/dissertation/fielding_dissertation.pdf
+        title: Architectural Styles and the Design of Network-based Software Architectures
+        author:
+          ins: R. Fielding
+          name: Roy Thomas Fielding
+          org: University of California, Irvine
+        date: 2000
+        seriesinfo:
+          "Ph.D.": "Dissertation, University of California, Irvine"
+        format:
+          PDF: http://www.ics.uci.edu/~fielding/pubs/dissertation/fielding_dissertation.pdf
+    normative:
+      ECMA262:
+        author:
+          org: European Computer Manufacturers Association
+        title: ECMAScript Language Specification 5.1 Edition
+        date: 2011-06
+        target: http://www.ecma-international.org/publications/files/ecma-st/ECMA-262.pdf
+        seriesinfo:
+          ECMA: Standard ECMA-262
+      RFC2119:
+      RFC6690:
+
+(as in the author list, `ins` is an abbreviation for
+"initials/surname".) Then you can simply reference `{{ASN.1}}` and
+`{{ECMA262}}` in the text.  (Make sure the reference keys are valid XML
+names, though.)
 
 # Risks and Side-Effects
 
@@ -67,7 +191,7 @@ 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.)
+examples).
 
 # Related Work
 
@@ -85,16 +209,15 @@ verbose.
 
 # 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.)
+With kramdown version 1.0, kramdown itself now is MIT licensed, so it
+is finally possible to license kramdown-rfc2629 under the same
+license.
 
 [kramdown]: http://kramdown.rubyforge.org/
 [stupid]: http://tools.ietf.org/id/draft-hartke-xmpp-stupid-00
-[RFC 2629]: http://xml.resource.org
+[RFC 2629]: http://xml.resource.org/public/rfc/html/rfc2629.html
 [markdown]: http://en.wikipedia.org/wiki/Markdown
 [IETF]: http://www.ietf.org
 [Miek Gieben]: http://www.miek.nl/
 [pandoc2rfc]: https://github.com/miekg/pandoc2rfc/
+[XML2RFC]: http://xml.resource.org

data/kramdown-rfc2629.gemspec

@@ -1,10 +1,10 @@
 spec = Gem::Specification.new do |s|
   s.name = 'kramdown-rfc2629'
-  s.version = '0.13.8'
+  s.version = '1.0.0'
   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.add_dependency('kramdown', '~> 1.0.0')
   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']
@@ -15,4 +15,5 @@ spec = Gem::Specification.new do |s|
   s.author = "Carsten Bormann"
   s.email = "cabo@tzi.org"
   s.homepage = "http://github.com/cabo/kramdown-rfc2629"
+  s.license = 'MIT'
 end

data/lib/kramdown-rfc2629.rb

@@ -12,8 +12,8 @@
 
 raise "sorry, 1.8 was last decade" unless RUBY_VERSION >= '1.9'
 
-# this version is adapted to kramdown 0.12.0 or 0.13.1
-gem 'kramdown', '~> 0.13'
+# this version also works with kramdown 0.12, 0.13, 0.14, but 1.0 has the right license
+gem 'kramdown', '~> 1.0.0'
 require 'kramdown'
 
 require 'rexml/parsers/baseparser'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kramdown-rfc2629
 version: !ruby/object:Gem::Version
-  version: 0.13.8
+  version: 1.0.0
 platform: ruby
 authors:
 - Carsten Bormann
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '0.13'
+        version: 1.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '0.13'
+        version: 1.0.0
 description: |-
   An RFC2629 (XML2RFC) generating backend for Thomas Leitner's
   "kramdown" markdown parser.  Mostly useful for RFC writers.
@@ -39,7 +39,8 @@ files:
 - bin/kramdown-rfc2629
 - data/kramdown-rfc2629.erb
 homepage: http://github.com/cabo/kramdown-rfc2629
-licenses: []
+licenses:
+- MIT
 metadata: {}
 post_install_message: 
 rdoc_options: []