kramdown-rfc2629 1.0.21 → 1.0.22
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/README.md +129 -3
- data/bin/kramdown-rfc2629 +3 -2
- data/kramdown-rfc2629.gemspec +2 -2
- data/lib/kramdown-rfc2629.rb +64 -19
- metadata +4 -4
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA1:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: f88f8eb021656a068385c1a1a8b787c118311ce1
|
4
|
+
data.tar.gz: 678962ddf03478ae2d357489e53a5edcd940161c
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 60d4fe36fe9524b4ffd1ee036a63a6d5751d54fb0aa30214fc98d2700035bad413ea54d3196326e39d7591104568ee1e899ee4ff090b353e2dce32035168a3dd
|
7
|
+
data.tar.gz: f4b4c59aa1551921d9b4eb375af87f847ad3b21eefdefda350223fd859fdf10e7dfec7326313c046aea807a0072deaeece1dd344f5770b3492d927eca8c7429b
|
data/README.md
CHANGED
@@ -61,7 +61,7 @@ collaborating with XML-only co-authors). See the `bibxml` metadata.
|
|
61
61
|
# The YAML header
|
62
62
|
|
63
63
|
Please consult the examples for the structure of the YAML header, this should be mostly
|
64
|
-
obvious. The `
|
64
|
+
obvious. The `stand_alone` attribute controls whether the RFC/I-D
|
65
65
|
references are inserted into the document (yes) or entity-referenced
|
66
66
|
(no), the latter leads to increased build time, but may be more
|
67
67
|
palatable for a final XML conversion.
|
@@ -206,15 +206,135 @@ Then you can simply reference `{{ASN.1}}` and
|
|
206
206
|
`{{ECMA262}}` in the text. (Make sure the reference keys are valid XML
|
207
207
|
names, though.)
|
208
208
|
|
209
|
+
# Experimental features
|
210
|
+
|
211
|
+
Most of the [kramdown syntax][kdsyntax] is supported and does
|
212
|
+
something useful; with the exception of the math syntax (math has no
|
213
|
+
special support in XML2RFC), and HTML syntax of course.
|
214
|
+
|
215
|
+
A number of more esoteric features have recently been added.
|
216
|
+
(The minimum required version for each full feature is indicated.)
|
217
|
+
|
218
|
+
(1.0.22:)
|
219
|
+
Index entries can be created with `(((item)))` or
|
220
|
+
`(((item, subitem)))`; use quotes for weird entries: `(((",", comma)))`.
|
221
|
+
If the index entry is to be marked "primary", prefix an (unquoted) `!`
|
222
|
+
as in `(((!item)))`.
|
223
|
+
|
224
|
+
In addition, auto-indexing is supported by hijacking the kramdown
|
225
|
+
"abbrev" syntax:
|
226
|
+
|
227
|
+
*[IANA]:
|
228
|
+
*[MUST]: BCP14
|
229
|
+
*[CBOR]: (((Object Representation, Concise Binary))) (((CBOR)))
|
230
|
+
|
231
|
+
The word in square brackets (which must match case-insensitively) is
|
232
|
+
entered into the index automatically for each place where it occurs.
|
233
|
+
If no title is given, just the word is entered (first example). If
|
234
|
+
one is given, that becomes the main item (the auto-indexed word
|
235
|
+
becomes the subitem, second example). If full control is desired
|
236
|
+
(e.g., for multiple entries per occurrence), just write down the full
|
237
|
+
index entries instead (third example).
|
238
|
+
|
239
|
+
(1.0.20:)
|
240
|
+
As an alternative referencing syntax for references with text,
|
241
|
+
`{{ref}}` can be expressed as `[text](#ref)`. As a special case, a
|
242
|
+
simple `[ref]` is interpreted as `[](#ref)`. This syntax does not
|
243
|
+
allow for automatic entry of items as normative/informative.
|
244
|
+
|
245
|
+
(1.0.16:) Markdown footnotes are converted into `cref`s (XML2RFC formal
|
246
|
+
comments; note that these are only visible if the pi "comments" is set to yes).
|
247
|
+
The anchor is taken from the markdown footnote name. The source, if
|
248
|
+
needed, can be supplied by an IAD, as in (first example with
|
249
|
+
ALD):
|
250
|
+
|
251
|
+
```markdown
|
252
|
+
{:cabo: source="cabo"}
|
253
|
+
|
254
|
+
(This section to be removed by the RFC editor.)[^1]{:cabo}
|
255
|
+
|
256
|
+
[^1]: here is my editorial comment
|
257
|
+
|
258
|
+
Another questionable paragraph.[^2]{: source="observer"}
|
259
|
+
|
260
|
+
[^2]: so why not delete it
|
261
|
+
```
|
262
|
+
|
263
|
+
Note that XML2RFC v2 doesn't allow structure in crefs. If you put any,
|
264
|
+
you get the escaped verbatim XML...
|
265
|
+
|
266
|
+
(1.0.11:) Allow overriding "style" attribute (via IAL =
|
267
|
+
[inline attribute list][kdsyntax-ial]) in lists and spans
|
268
|
+
as in:
|
269
|
+
|
270
|
+
```markdown
|
271
|
+
{:req: counter="bar" style="format R(%d)"}
|
272
|
+
|
273
|
+
{: req}
|
274
|
+
* Foo
|
275
|
+
* Bar
|
276
|
+
* Bax
|
277
|
+
|
278
|
+
Text outside the list, so a new IAL is needed.
|
279
|
+
|
280
|
+
* Foof
|
281
|
+
* Barf
|
282
|
+
* Barx
|
283
|
+
{: req}
|
284
|
+
```
|
285
|
+
|
286
|
+
(1.0.5:) An IAL attribute "cols" can be added to tables to override
|
287
|
+
the column layout. For example, `cols="* 20 30c r"` sets the width attributes to
|
288
|
+
20 and 30 for the middle columns and sets the right two columns to
|
289
|
+
center and right alignment, respectively. The alignment from `cols`
|
290
|
+
overrides that from the kramdown table, if present.
|
291
|
+
|
292
|
+
(1.0.2:) An IAL attribute "vspace" can be added to a definition list
|
293
|
+
to break after the definition term:
|
294
|
+
|
295
|
+
```markdown
|
296
|
+
{: vspace="0"}
|
297
|
+
word:
|
298
|
+
: definition
|
299
|
+
|
300
|
+
anotherword:
|
301
|
+
: another definition
|
302
|
+
```
|
303
|
+
|
304
|
+
(0.x:) Files can be included with the syntax `{::include fn}` (needs
|
305
|
+
to be in column 1 since 1.0.22; can be suppressed for use in servers
|
306
|
+
by setting environment variable KRAMDOWN_SAFE since 1.0.22). A
|
307
|
+
typical example from a recent RFC, where the contents of a figure was
|
308
|
+
machine-generated:
|
309
|
+
|
310
|
+
```markdown
|
311
|
+
~~~~~~~~~~
|
312
|
+
{::include ../ghc/packets-new/p4.out}
|
313
|
+
~~~~~~~~~~
|
314
|
+
{: #example2 title="A longer RPL example"}
|
315
|
+
```
|
316
|
+
|
317
|
+
(0.x:) A page break can be forced by adding a horizontal rule (`----`,
|
318
|
+
note that this creates ugly blank space in some HTML converters).
|
319
|
+
|
209
320
|
# Risks and Side-Effects
|
210
321
|
|
211
|
-
The code is not very polished, but it has been successfully used for a
|
212
|
-
number of non-trivial Internet-Drafts. You probably still need to
|
322
|
+
The code is not very polished, but now quite stable; it has been successfully used for a
|
323
|
+
number of non-trivial Internet-Drafts and RFCs. You probably still need to
|
213
324
|
skim [RFC 2629][] if you want to write an Internet-Draft, but you
|
214
325
|
don't really need to understand XML very much. Knowing the basics of
|
215
326
|
YAML helps with the metadata (but you'll understand it from the
|
216
327
|
examples).
|
217
328
|
|
329
|
+
# Upconversion
|
330
|
+
|
331
|
+
If you have an old RFC and want to convert it to markdown, try just
|
332
|
+
using that RFC, it is 80 % there. It may be possible to automate the
|
333
|
+
remaining 20 % some more, but that hasn't been done.
|
334
|
+
|
335
|
+
If you have XML, there is an experimental upconverter that does 99 %
|
336
|
+
of the work. Please contact the author if you want to try it.
|
337
|
+
|
218
338
|
# Related Work
|
219
339
|
|
220
340
|
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
|
|
228
348
|
the markdown document. He also uses a slightly different referencing
|
229
349
|
syntax, which is closer to what markdown does elsewhere but more
|
230
350
|
verbose (this syntax is now also supported in kramdown-rfc2629).
|
351
|
+
(Miek now also has a new thing going on with mostly different syntax,
|
352
|
+
see [mmark][].)
|
231
353
|
|
232
354
|
# License
|
233
355
|
|
@@ -235,6 +357,8 @@ Since kramdown version 1.0, kramdown itself is MIT licensed, which
|
|
235
357
|
made it possible to license kramdown-rfc2629 under the same license.
|
236
358
|
|
237
359
|
[kramdown]: http://kramdown.rubyforge.org/
|
360
|
+
[kdsyntax]: http://kramdown.gettalong.org/syntax.html
|
361
|
+
[kdsyntax-ial]: http://kramdown.gettalong.org/syntax.html#inline-attribute-lists
|
238
362
|
[stupid]: http://tools.ietf.org/id/draft-hartke-xmpp-stupid-00
|
239
363
|
[RFC 2629]: http://xml.resource.org/public/rfc/html/rfc2629.html
|
240
364
|
[markdown]: http://en.wikipedia.org/wiki/Markdown
|
@@ -243,3 +367,5 @@ made it possible to license kramdown-rfc2629 under the same license.
|
|
243
367
|
[pandoc2rfc]: https://github.com/miekg/pandoc2rfc/
|
244
368
|
[XML2RFC]: http://xml.resource.org
|
245
369
|
[RFC 7328]: http://tools.ietf.org/html/rfc7328
|
370
|
+
[mmark]: https://github.com/miekg/mmark
|
371
|
+
[YAML]: http://www.yaml.org/spec/1.2/spec.html
|
data/bin/kramdown-rfc2629
CHANGED
@@ -266,9 +266,10 @@ def dateattrs(date)
|
|
266
266
|
end
|
267
267
|
|
268
268
|
coding_override = :as_char
|
269
|
-
input = ARGF.read
|
269
|
+
input = ARGF.read
|
270
|
+
input.gsub!(/^\{::include\s+(.*?)\}/) {
|
270
271
|
File.read($1).chomp
|
271
|
-
}
|
272
|
+
} unless ENV["KRAMDOWN_SAFE"]
|
272
273
|
link_defs = {}
|
273
274
|
if input =~ /\A---/ # this is a sectionized file
|
274
275
|
input, coding_override, link_defs = xml_from_sections(input)
|
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.
|
3
|
+
s.version = '1.0.22'
|
4
4
|
s.summary = "Kramdown extension for generating RFC 2629 XML."
|
5
5
|
s.description = %{An RFC2629 (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.5.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,8 +11,7 @@
|
|
11
11
|
|
12
12
|
raise "sorry, 1.8 was last decade" unless RUBY_VERSION >= '1.9'
|
13
13
|
|
14
|
-
|
15
|
-
gem 'kramdown', '~> 1.4.0'
|
14
|
+
gem 'kramdown', '~> 1.5.0'
|
16
15
|
require 'kramdown'
|
17
16
|
|
18
17
|
require 'rexml/parsers/baseparser'
|
@@ -31,6 +30,7 @@ module Kramdown
|
|
31
30
|
def initialize(*doc)
|
32
31
|
super
|
33
32
|
@span_parsers.unshift(:xref)
|
33
|
+
@span_parsers.unshift(:iref)
|
34
34
|
end
|
35
35
|
|
36
36
|
XREF_START = /\{\{(.*?)\}\}/u
|
@@ -47,6 +47,17 @@ module Kramdown
|
|
47
47
|
end
|
48
48
|
define_parser(:xref, XREF_START, '{{')
|
49
49
|
|
50
|
+
IREF_START = /\(\(\((.*?)\)\)\)/u
|
51
|
+
|
52
|
+
# Introduce new (((target))) syntax for irefs
|
53
|
+
def parse_iref
|
54
|
+
@src.pos += @src.matched_size
|
55
|
+
href = @src[1]
|
56
|
+
el = Element.new(:iref, nil, {'target' => href}) # XXX
|
57
|
+
@tree.children << el
|
58
|
+
end
|
59
|
+
define_parser(:iref, IREF_START, '\(\(\(')
|
60
|
+
|
50
61
|
end
|
51
62
|
end
|
52
63
|
|
@@ -183,6 +194,18 @@ module Kramdown
|
|
183
194
|
end
|
184
195
|
end
|
185
196
|
|
197
|
+
def clean_pcdata(parts) # hack, will become unnecessary with XML2RFCv3
|
198
|
+
clean = ''
|
199
|
+
irefs = ''
|
200
|
+
# warn "clean_parts: #{parts.inspect}"
|
201
|
+
parts.each do |p|
|
202
|
+
md = p.match(%r{([^<]*)(.*)})
|
203
|
+
clean << md[1]
|
204
|
+
irefs << md[2] # breaks for spanx... don't emphasize in headings!
|
205
|
+
end
|
206
|
+
[clean, irefs]
|
207
|
+
end
|
208
|
+
|
186
209
|
def convert_header(el, indent, opts)
|
187
210
|
# todo: handle appendix tags
|
188
211
|
el = el.deep_clone
|
@@ -190,8 +213,9 @@ module Kramdown
|
|
190
213
|
if options[:auto_ids] && !el.attr['anchor']
|
191
214
|
el.attr['anchor'] = saner_generate_id(el.options[:raw_text])
|
192
215
|
end
|
193
|
-
|
194
|
-
|
216
|
+
clean, irefs = clean_pcdata(inner_a(el, indent, opts))
|
217
|
+
el.attr['title'] = clean
|
218
|
+
"#{end_sections(el.options[:level], indent)}#{' '*indent}<section#{@sec_level += 1; el_html_attributes(el)}>#{irefs}\n"
|
195
219
|
end
|
196
220
|
|
197
221
|
def convert_hr(el, indent, opts) # misuse for page break
|
@@ -312,10 +336,12 @@ module Kramdown
|
|
312
336
|
alignment = COLS_ALIGN[md[3]] || :left
|
313
337
|
end
|
314
338
|
end
|
315
|
-
res = inner(el, indent, opts)
|
316
339
|
if alignment
|
317
|
-
|
318
|
-
|
340
|
+
res, irefs = clean_pcdata(inner_a(el, indent, opts))
|
341
|
+
warn "*** lost markup #{irefs} in table heading" unless irefs.empty?
|
342
|
+
"#{' '*indent}<ttcol #{widthopt}align='#{alignment}'#{el_html_attributes(el)}>#{res.empty? ? " " : res}</ttcol>\n" # XXX need clean_pcdata
|
343
|
+
else
|
344
|
+
res = inner(el, indent, opts)
|
319
345
|
"#{' '*indent}<c#{el_html_attributes(el)}>#{res.empty? ? " " : res}</c>\n"
|
320
346
|
end
|
321
347
|
end
|
@@ -460,7 +486,8 @@ module Kramdown
|
|
460
486
|
|
461
487
|
def convert_em(el, indent, opts)
|
462
488
|
attrstring = el_html_attributes_with(el, {"style" => EMPH[el.type]})
|
463
|
-
|
489
|
+
span, irefs = clean_pcdata(inner_a(el, indent, opts))
|
490
|
+
"<spanx#{attrstring}>#{span}</spanx>#{irefs}"
|
464
491
|
end
|
465
492
|
alias :convert_strong :convert_em
|
466
493
|
|
@@ -494,27 +521,45 @@ module Kramdown
|
|
494
521
|
"<#{type}#{el_html_attributes(el)}>#{escape_html(el.value, :text)}</#{type}>#{type == 'div' ? "\n" : ''}"
|
495
522
|
end
|
496
523
|
|
524
|
+
ITEM_RE = '\s*(?:"([^"]*)"|([^,]*?))\s*'
|
525
|
+
IREF_RE = %r{\A(!\s*)?#{ITEM_RE}(?:,#{ITEM_RE})?\z}
|
526
|
+
|
527
|
+
def iref_attr(s)
|
528
|
+
md = s.match(IREF_RE)
|
529
|
+
attr = {
|
530
|
+
item: md[2] || md[3],
|
531
|
+
subitem: md[4] || md[5],
|
532
|
+
primary: md[1] && 'true',
|
533
|
+
}
|
534
|
+
"<iref#{html_attributes(attr)}/>"
|
535
|
+
end
|
536
|
+
|
537
|
+
def convert_iref(el, indent, opts)
|
538
|
+
iref_attr(el.attr['target'])
|
539
|
+
end
|
540
|
+
|
497
541
|
def convert_abbreviation(el, indent, opts) # XXX: This is wrong
|
498
542
|
title = @root.options[:abbrev_defs][el.value]
|
499
543
|
title = nil if title.empty?
|
500
544
|
value = el.value
|
501
|
-
|
545
|
+
if item = title
|
546
|
+
m = title.scan(Parser::RFC2629Kramdown::IREF_START)
|
547
|
+
if m.empty?
|
548
|
+
subitem = value
|
549
|
+
else
|
550
|
+
iref = m.map{|a,| iref_attr(a)}.join('')
|
551
|
+
end
|
552
|
+
else
|
553
|
+
item = value
|
554
|
+
end
|
555
|
+
iref ||= "<iref#{html_attributes(item: item, subitem: subitem)}/>"
|
556
|
+
"#{el.value}#{iref}"
|
502
557
|
end
|
503
558
|
|
504
559
|
def convert_root(el, indent, opts)
|
505
560
|
result = inner(el, indent, opts)
|
506
561
|
end
|
507
562
|
|
508
|
-
# Helper method for obfuscating the +text+ by using XML entities.
|
509
|
-
def obfuscate(text)
|
510
|
-
result = ""
|
511
|
-
text.each_byte do |b|
|
512
|
-
result += (b > 128 ? b.chr : "&#%03d;" % b)
|
513
|
-
end
|
514
|
-
result.force_encoding(text.encoding) if RUBY_VERSION >= '1.9'
|
515
|
-
result
|
516
|
-
end
|
517
|
-
|
518
563
|
end
|
519
564
|
|
520
565
|
end
|
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.22
|
5
5
|
platform: ruby
|
6
6
|
authors:
|
7
7
|
- Carsten Bormann
|
8
8
|
autorequire:
|
9
9
|
bindir: bin
|
10
10
|
cert_chain: []
|
11
|
-
date: 2014-
|
11
|
+
date: 2014-12-06 00:00:00.000000000 Z
|
12
12
|
dependencies:
|
13
13
|
- !ruby/object:Gem::Dependency
|
14
14
|
name: kramdown
|
@@ -16,14 +16,14 @@ dependencies:
|
|
16
16
|
requirements:
|
17
17
|
- - "~>"
|
18
18
|
- !ruby/object:Gem::Version
|
19
|
-
version: 1.
|
19
|
+
version: 1.5.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.5.0
|
27
27
|
description: |-
|
28
28
|
An RFC2629 (XML2RFC) generating backend for Thomas Leitner's
|
29
29
|
"kramdown" markdown parser. Mostly useful for RFC writers.
|