kramdown-rfc2629 1.0.29 → 1.0.30
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/README.md +46 -8
- data/bin/kramdown-rfc2629 +7 -0
- data/kramdown-rfc2629.gemspec +4 -4
- data/lib/kramdown-rfc2629.rb +24 -7
- metadata +6 -6
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA1:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: a7bc8abb77836597a85d3759acc1b9c967ab08b9
|
4
|
+
data.tar.gz: 0f0936ec35dcaa2f17fcad200b8078a5280d4f6d
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: d4ff0aa08e50fa874c90c83eaaacc8239ee3d313f1862d6f0f40d4aced3761bc727e52f4f2fc48aab71354a5b0d1fa377d4f5ac4266c4036f2325d707988d788
|
7
|
+
data.tar.gz: 76ca0282a1f3aa15ab0b72c61bd17b1865ec703cc54820e1926dc1d8c1516c59d9103ffccb2bfd099ba68a2a759f607c1fe6cd9d13d8867dfbf0f54bc35822f2
|
data/README.md
CHANGED
@@ -4,8 +4,8 @@
|
|
4
4
|
number of backends for generating HTML, Latex, and markdown again.
|
5
5
|
|
6
6
|
**kramdown-rfc2629** is an additional backend to that: It allows the
|
7
|
-
generation of [XML2RFC][] XML markup (
|
8
|
-
compliant markup).
|
7
|
+
generation of [XML2RFC][] XML markup (originally known as [RFC 2629][]
|
8
|
+
compliant markup, now documented in [RFC 7749][]).
|
9
9
|
|
10
10
|
Who would care? Anybody who is writing Internet-Drafts and RFCs in
|
11
11
|
the [IETF][] and prefers (or has co-authors who prefer) to do part of
|
@@ -35,10 +35,11 @@ To use kramdown-rfc2629, you'll need a Ruby 1.9 or 2.x, and maybe
|
|
35
35
|
|
36
36
|
# Examples
|
37
37
|
|
38
|
+
For historical interest
|
38
39
|
`stupid.mkd` was an early markdown version of an actual Internet-Draft
|
39
40
|
(for a protocol called [STuPiD][] \[sic!]). This demonstrated some,
|
40
41
|
but not all features of kramdown-rfc2629. Since markdown/kramdown
|
41
|
-
does not cater for all the structure of an RFC
|
42
|
+
does not cater for all the structure of an RFC 7749 style document,
|
42
43
|
some of the markup is in XML, and the example switches between XML and
|
43
44
|
markdown using kramdown's `{::nomarkdown}` and `{:/nomarkdown}` (this
|
44
45
|
is ugly, but works well enough). `stupid.xml` and `stupid.txt` show
|
@@ -117,8 +118,8 @@ or
|
|
117
118
|
phone: "+33 4 97 23 26 34"
|
118
119
|
email: pthubert@cisco.com
|
119
120
|
|
120
|
-
(the hash keys are the XML GIs from RFC
|
121
|
-
structure. As RFC
|
121
|
+
(the hash keys are the XML GIs from RFC 7749, with a flattened
|
122
|
+
structure. As RFC 7749 requires giving both the full name and
|
122
123
|
surname/initials, we use `ins` as an abbreviation for
|
123
124
|
"initials/surname". Yes, the toolchain is Unicode-capable, even if
|
124
125
|
the final RFC output is still in ASCII.)
|
@@ -233,6 +234,22 @@ special support in XML2RFC), and HTML syntax of course.
|
|
233
234
|
A number of more esoteric features have recently been added.
|
234
235
|
(The minimum required version for each full feature is indicated.)
|
235
236
|
|
237
|
+
(1.0.30:)
|
238
|
+
kramdown-rfc now uses kramdown 1.10, which leads to two notable updates:
|
239
|
+
|
240
|
+
* Support for empty link texts in the standard markdown
|
241
|
+
reference syntax, as in `[](#RFC7744)`.
|
242
|
+
* Language names in fenced code blocks now support all characters
|
243
|
+
except whitespace, so you can go wild with `asn.1` and `C#`.
|
244
|
+
|
245
|
+
A heuristic generates missing initials/surname from the `name` entry
|
246
|
+
in author information. This should save a lot of redundant typing.
|
247
|
+
You'll need to continue using the `ins` entry as well if that
|
248
|
+
heuristic fails (e.g., for Spanish names).
|
249
|
+
|
250
|
+
Also, there is some rather experimental support for markdown display
|
251
|
+
math (blocks between `$$` pairs) if the `tex2mail` tool is available.
|
252
|
+
|
236
253
|
(1.0.23:)
|
237
254
|
Move up to kramdown 1.6.0. This inherits a number of fixes and one
|
238
255
|
nice feature:
|
@@ -373,13 +390,11 @@ note that this creates ugly blank space in some HTML converters).
|
|
373
390
|
|
374
391
|
The code is not very polished, but now quite stable; it has been successfully used for a
|
375
392
|
number of non-trivial Internet-Drafts and RFCs. You probably still need to
|
376
|
-
skim [RFC
|
393
|
+
skim [RFC 7749][] if you want to write an Internet-Draft, but you
|
377
394
|
don't really need to understand XML very much. Knowing the basics of
|
378
395
|
YAML helps with the metadata (but you'll understand it from the
|
379
396
|
examples).
|
380
397
|
|
381
|
-
[IAB-RFCXMLv2]: https://tools.ietf.org/html/draft-iab-xml2rfcv2-00
|
382
|
-
|
383
398
|
# Upconversion
|
384
399
|
|
385
400
|
If you have an old RFC and want to convert it to markdown, try just
|
@@ -389,6 +404,28 @@ remaining 20 % some more, but that hasn't been done.
|
|
389
404
|
If you have XML, there is an experimental upconverter that does 99 %
|
390
405
|
of the work. Please contact the author if you want to try it.
|
391
406
|
|
407
|
+
# Tools
|
408
|
+
|
409
|
+
Joe Hildebrand has a
|
410
|
+
[grunt][] plugin for kramdown-rfc2629 at:
|
411
|
+
https://github.com/hildjj/grunt-kramdown-rfc2629
|
412
|
+
.
|
413
|
+
Get started with it at:
|
414
|
+
https://github.com/hildjj/grunt-init-rfc
|
415
|
+
.
|
416
|
+
This provides a self-refreshing web page with the
|
417
|
+
kramdown-rfc2629/xml2rfc rendition of the draft you are editing.
|
418
|
+
|
419
|
+
[grunt]: http://gruntjs.com
|
420
|
+
|
421
|
+
Martin Thomson has an [I-D Template][] for github repositories that enable
|
422
|
+
collaboration on draft development.
|
423
|
+
This supports kramdown-rfc2629 out of the
|
424
|
+
box. Just name your draft like `draft-ietf-unicorn-protocol-latest.md` and
|
425
|
+
follow the installation instructions.
|
426
|
+
|
427
|
+
[I-D Template]: https://github.com/martinthomson/i-d-template
|
428
|
+
|
392
429
|
# Related Work
|
393
430
|
|
394
431
|
Moving from XML to Markdown for RFC writing apparently is a
|
@@ -415,6 +452,7 @@ made it possible to license kramdown-rfc2629 under the same license.
|
|
415
452
|
[kdsyntax-ial]: http://kramdown.gettalong.org/syntax.html#inline-attribute-lists
|
416
453
|
[stupid]: http://tools.ietf.org/id/draft-hartke-xmpp-stupid-00
|
417
454
|
[RFC 2629]: http://xml.resource.org/public/rfc/html/rfc2629.html
|
455
|
+
[RFC 7749]: http://tools.ietf.org/html/rfc7749
|
418
456
|
[markdown]: http://en.wikipedia.org/wiki/Markdown
|
419
457
|
[IETF]: http://www.ietf.org
|
420
458
|
[Miek Gieben]: http://www.miek.nl/
|
data/bin/kramdown-rfc2629
CHANGED
@@ -247,6 +247,13 @@ def authorps_from_hash(au)
|
|
247
247
|
aups.rest["initials"] = parts[0..-2].join('.') << '.'
|
248
248
|
aups.rest["surname"] = parts[-1]
|
249
249
|
end
|
250
|
+
# hack ("heuristic for") initials and surname from name
|
251
|
+
# -- only works for people with exactly one last name and uncomplicated first names
|
252
|
+
if n = aups.rest["name"]
|
253
|
+
n = n.split
|
254
|
+
aups.rest["initials"] ||= n[0..-2].map(&:chr).join('.') << '.'
|
255
|
+
aups.rest["surname"] ||= n[-1]
|
256
|
+
end
|
250
257
|
aups
|
251
258
|
end
|
252
259
|
|
data/kramdown-rfc2629.gemspec
CHANGED
@@ -1,10 +1,10 @@
|
|
1
1
|
spec = Gem::Specification.new do |s|
|
2
2
|
s.name = 'kramdown-rfc2629'
|
3
|
-
s.version = '1.0.
|
4
|
-
s.summary = "Kramdown extension for generating RFC
|
5
|
-
s.description = %{An
|
3
|
+
s.version = '1.0.30'
|
4
|
+
s.summary = "Kramdown extension for generating RFC 7749 XML."
|
5
|
+
s.description = %{An RFC7749 (XML2RFC) generating backend for Thomas Leitner's
|
6
6
|
"kramdown" markdown parser. Mostly useful for RFC writers.}
|
7
|
-
s.add_dependency('kramdown', '~> 1.
|
7
|
+
s.add_dependency('kramdown', '~> 1.10.0')
|
8
8
|
s.files = Dir['lib/**/*.rb'] + %w(README.md LICENSE kramdown-rfc2629.gemspec bin/kramdown-rfc2629 data/kramdown-rfc2629.erb)
|
9
9
|
s.require_path = 'lib'
|
10
10
|
s.executables = ['kramdown-rfc2629']
|
data/lib/kramdown-rfc2629.rb
CHANGED
@@ -11,12 +11,13 @@
|
|
11
11
|
|
12
12
|
raise "sorry, 1.8 was last decade" unless RUBY_VERSION >= '1.9'
|
13
13
|
|
14
|
-
gem 'kramdown', '~> 1.
|
14
|
+
gem 'kramdown', '~> 1.10.0'
|
15
15
|
require 'kramdown'
|
16
16
|
my_span_elements = %w{list figure xref eref iref cref spanx vspace}
|
17
17
|
Kramdown::Parser::Html::Constants::HTML_SPAN_ELEMENTS.concat my_span_elements
|
18
18
|
|
19
19
|
require 'rexml/parsers/baseparser'
|
20
|
+
require 'open3' # for math
|
20
21
|
|
21
22
|
class Object
|
22
23
|
def deep_clone
|
@@ -290,7 +291,8 @@ module Kramdown
|
|
290
291
|
@in_dt = 1
|
291
292
|
vspace = opts[:vspace]
|
292
293
|
vspaceel = "<vspace blankLines='#{vspace}'/>" if vspace
|
293
|
-
|
294
|
+
ht = escape_html(inner(el, indent, opts), :attribute) # XXX this may leave gunk
|
295
|
+
"#{close}#{' '*indent}<t#{el_html_attributes(el)} hangText='#{ht}'>#{vspaceel}\n"
|
294
296
|
end
|
295
297
|
|
296
298
|
HTML_TAGS_WITH_BODY=['div', 'script']
|
@@ -552,11 +554,26 @@ module Kramdown
|
|
552
554
|
|
553
555
|
def convert_math(el, indent, opts) # XXX: This is wrong
|
554
556
|
el = el.deep_clone
|
555
|
-
el.
|
556
|
-
|
557
|
-
|
558
|
-
|
559
|
-
|
557
|
+
if el.options[:category] == :block
|
558
|
+
el.attr['artwork-type'] ||= ''
|
559
|
+
el.attr['artwork-type'] += (el.attr['artwork-type'].empty? ? '' : ' ') + 'math'
|
560
|
+
artwork_attr = {}
|
561
|
+
el.attr.each do |k, v|
|
562
|
+
if md = k.match(/\Aartwork-(.*)/)
|
563
|
+
el.attr.delete(k)
|
564
|
+
artwork_attr[md[1]] = v
|
565
|
+
end
|
566
|
+
end
|
567
|
+
result, _s = Open3.capture2("tex2mail -noindent -ragged -by_par -linelength=69", stdin_data: el.value);
|
568
|
+
# warn "*** tex2mail not in path?" unless s.success? -- doesn't have useful status
|
569
|
+
"#{' '*indent}<figure#{el_html_attributes(el)}><artwork#{html_attributes(artwork_attr)}><![CDATA[#{result}#{result =~ /\n\Z/ ? '' : "\n"}]]></artwork></figure>\n"
|
570
|
+
|
571
|
+
else
|
572
|
+
warn "*** no support for inline math in XML2RFCv2"
|
573
|
+
type = 'spanx'
|
574
|
+
attrstring = el_html_attributes_with(el, {"style" => 'verb'})
|
575
|
+
"<#{type}#{attrstring}>#{escape_html(el.value, :text)}</#{type}>"
|
576
|
+
end
|
560
577
|
end
|
561
578
|
|
562
579
|
ITEM_RE = '\s*(?:"([^"]*)"|([^,]*?))\s*'
|
metadata
CHANGED
@@ -1,14 +1,14 @@
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
2
2
|
name: kramdown-rfc2629
|
3
3
|
version: !ruby/object:Gem::Version
|
4
|
-
version: 1.0.
|
4
|
+
version: 1.0.30
|
5
5
|
platform: ruby
|
6
6
|
authors:
|
7
7
|
- Carsten Bormann
|
8
8
|
autorequire:
|
9
9
|
bindir: bin
|
10
10
|
cert_chain: []
|
11
|
-
date: 2016-02
|
11
|
+
date: 2016-03-02 00:00:00.000000000 Z
|
12
12
|
dependencies:
|
13
13
|
- !ruby/object:Gem::Dependency
|
14
14
|
name: kramdown
|
@@ -16,16 +16,16 @@ dependencies:
|
|
16
16
|
requirements:
|
17
17
|
- - "~>"
|
18
18
|
- !ruby/object:Gem::Version
|
19
|
-
version: 1.
|
19
|
+
version: 1.10.0
|
20
20
|
type: :runtime
|
21
21
|
prerelease: false
|
22
22
|
version_requirements: !ruby/object:Gem::Requirement
|
23
23
|
requirements:
|
24
24
|
- - "~>"
|
25
25
|
- !ruby/object:Gem::Version
|
26
|
-
version: 1.
|
26
|
+
version: 1.10.0
|
27
27
|
description: |-
|
28
|
-
An
|
28
|
+
An RFC7749 (XML2RFC) generating backend for Thomas Leitner's
|
29
29
|
"kramdown" markdown parser. Mostly useful for RFC writers.
|
30
30
|
email: cabo@tzi.org
|
31
31
|
executables:
|
@@ -62,6 +62,6 @@ rubyforge_project:
|
|
62
62
|
rubygems_version: 2.4.8
|
63
63
|
signing_key:
|
64
64
|
specification_version: 4
|
65
|
-
summary: Kramdown extension for generating RFC
|
65
|
+
summary: Kramdown extension for generating RFC 7749 XML.
|
66
66
|
test_files: []
|
67
67
|
has_rdoc:
|