kramdown-rfc2629 1.6.1 → 1.6.2
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/README.md +38 -33
- data/kramdown-rfc2629.gemspec +3 -3
- data/lib/kramdown-rfc2629.rb +1 -1
- metadata +4 -4
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: a0cbc05053ff35b95300e9fcbb48ee48499434af71e7689c36e7cf5ab2385d57
|
4
|
+
data.tar.gz: 3d1d2665bee5c8e833b07861eb81bd5b1e7a09ad0a2647af23c55dcff2c10446
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 0f94ba68e6dfc8ee2026a8bc42182fdabb2016a062b25ec5109334eddda2383515ee1962449815f26a54097f0560f8a7c4aeb7441674ff0c3095e8dfabc8e943
|
7
|
+
data.tar.gz: d1898de3f1a8f73b5f126bf1d833ce61eff37d65f10acf7219dc0e89e7b94b7b5a37ac95ac5773251abf712256368a02f480de99ecbbbbb4e4c68939c76382bb
|
data/README.md
CHANGED
@@ -1,11 +1,12 @@
|
|
1
|
-
# kramdown-
|
1
|
+
# kramdown-rfc
|
2
2
|
|
3
3
|
[kramdown][] is a [markdown][] parser by Thomas Leitner, which has a
|
4
4
|
number of backends for generating HTML, Latex, and markdown again.
|
5
5
|
|
6
|
-
**kramdown-
|
6
|
+
**kramdown-rfc** is an additional backend to that: It allows the
|
7
7
|
generation of [XML2RFC][] XML markup (originally known as [RFC 2629][]
|
8
|
-
compliant markup,
|
8
|
+
compliant markup, with a newer version documented in [RFC 7749][];
|
9
|
+
version 3 now documented in [RFC 7991][] etc. and [v3][]).
|
9
10
|
|
10
11
|
Who would care? Anybody who is writing Internet-Drafts and RFCs in
|
11
12
|
the [IETF][] and prefers (or has co-authors who prefer) to do part of
|
@@ -13,33 +14,33 @@ their work in markdown.
|
|
13
14
|
|
14
15
|
# Usage
|
15
16
|
|
16
|
-
Start by installing the kramdown-
|
17
|
+
Start by installing the kramdown-rfc gem (this automatically
|
17
18
|
installs appropriate versions of referenced gems such as kramdown as
|
18
19
|
well):
|
19
20
|
|
20
|
-
gem install kramdown-
|
21
|
+
gem install kramdown-rfc
|
21
22
|
|
22
23
|
(Add a `sudo` and a space in front of that command if you don't have
|
23
24
|
all the permissions needed.)
|
24
25
|
|
25
|
-
The guts of kramdown-
|
26
|
+
The guts of kramdown-rfc are in one Ruby file,
|
26
27
|
`lib/kramdown-rfc2629.rb` --- this melds nicely into the extension
|
27
|
-
structure provided by kramdown. `bin/kramdown-
|
28
|
+
structure provided by kramdown. `bin/kramdown-rfc` started out as
|
28
29
|
a simple command-line program showing how to use this, but can now do
|
29
30
|
much more (see below).
|
30
31
|
|
31
|
-
To use kramdown-
|
32
|
+
To use kramdown-rfc, you'll need Ruby (at least version 2.3, but
|
32
33
|
preferably a current version), and maybe
|
33
34
|
[XML2RFC][] if you want to see the fruits of your work.
|
34
35
|
|
35
|
-
kramdown-
|
36
|
+
kramdown-rfc mydraft.mkd >mydraft.xml
|
36
37
|
xml2rfc mydraft.xml
|
37
38
|
|
38
39
|
(The most popular file name extension that IETF people have for
|
39
40
|
markdown is .md -- for those who tend to think about GNU machine
|
40
41
|
descriptions here, any extension such as .mkd will do, too.)
|
41
42
|
|
42
|
-
A more brief interface for both calling kramdown-
|
43
|
+
A more brief interface for both calling kramdown-rfc and XML2RFC
|
43
44
|
is provided by `kdrfc`:
|
44
45
|
|
45
46
|
kdrfc mydraft.mkd
|
@@ -52,29 +53,31 @@ is provided by `kdrfc`:
|
|
52
53
|
|
53
54
|
Since RFC 8650, RFCs are using an updated grammar as defined in RFC
|
54
55
|
7991 to 7998 and further updated informally since, colloquially called "[v3][]".
|
55
|
-
As RFC 2629 is no longer the governing standard, kramdown-rfc2629 is
|
56
|
+
As RFC 2629 is no longer the governing standard, what was called kramdown-rfc2629 is
|
56
57
|
now called kramdown-rfc. The latter command defaults to v3 processing
|
57
|
-
rules; from 2022-02-22T22:02:22 on, kramdown-rfc2629 does as well (1.6.1).
|
58
|
+
rules; from 2022-02-22T22:02:22 on, the old kramdown-rfc2629 driver program does as well (1.6.1).
|
58
59
|
(-3/--v3 and -2/--v2 select v3 and v2 explicitly; the latter should
|
59
60
|
only be needed if there is a reason to to make a document look
|
60
61
|
like it's 2016.)
|
61
62
|
|
62
|
-
[v3]
|
63
|
+
See also [v3 announcement mail][].
|
64
|
+
|
65
|
+
[v3 announcement mail]: https://mailarchive.ietf.org/arch/msg/rfc-markdown/JC__LDDGuUbSFqyaEntF9r4kwKw
|
63
66
|
|
64
67
|
# Examples
|
65
68
|
|
66
69
|
For historical interest
|
67
70
|
`stupid.mkd` was an early markdown version of an actual Internet-Draft
|
68
71
|
(for a protocol called [STuPiD][] \[sic!]). This demonstrated some,
|
69
|
-
but not all features of kramdown-
|
70
|
-
does not cater for all the structure of an RFC
|
72
|
+
but not all features of kramdown-rfc. Since markdown/kramdown
|
73
|
+
does not cater for all the structure of an RFC 7991 style document,
|
71
74
|
some of the markup is in XML, and the example switches between XML and
|
72
75
|
markdown using kramdown's `{::nomarkdown}` and `{:/nomarkdown}` (this
|
73
76
|
is ugly, but works well enough). `stupid.xml` and `stupid.txt` show
|
74
|
-
what kramdown-
|
77
|
+
what kramdown-rfc and xml2rfc make out of this.
|
75
78
|
|
76
79
|
`stupid-s.mkd` is the same document in the new sectionized format
|
77
|
-
supported by kramdown-
|
80
|
+
supported by kramdown-rfc. The document metadata are in a short
|
78
81
|
piece of YAML at the start, and from there, `abstract`, `middle`,
|
79
82
|
references (`normative` and `informative`) and `back` are sections
|
80
83
|
delimited in the markdown file. See the example for how this works.
|
@@ -82,7 +85,7 @@ The sections `normative` and `informative` can be populated right from
|
|
82
85
|
the metadata, so there is never a need to write XML any more.
|
83
86
|
Much less scary, and no `{:/nomarkdown}` etc. is needed any more.
|
84
87
|
Similarly, `stupid-s.xml` and `stupid-s.txt` show what
|
85
|
-
kramdown-
|
88
|
+
kramdown-rfc and xml2rfc make out of this.
|
86
89
|
|
87
90
|
`draft-ietf-core-block-xx.mkd` is a real-world example of a current
|
88
91
|
Internet-Draft done this way. For RFC and Internet-Draft references,
|
@@ -147,7 +150,7 @@ or
|
|
147
150
|
email: pthubert@cisco.com
|
148
151
|
|
149
152
|
(the hash keys are the XML GIs from RFC 7749, with a flattened
|
150
|
-
structure. As RFC 7749
|
153
|
+
structure. As RFC 7749 requiresd giving both the full name and
|
151
154
|
surname/initials, we use `ins` as an abbreviation for
|
152
155
|
"initials/surname". Yes, the toolchain is Unicode-capable, even if
|
153
156
|
the final RFC output is still in ASCII.)
|
@@ -161,7 +164,7 @@ might otherwise be interpreted as a number, losing the + sign).
|
|
161
164
|
|
162
165
|
The references section is built from the references listed in the YAML
|
163
166
|
header and from references made inline to RFCs and I-Ds in the
|
164
|
-
markdown text. Since kramdown-
|
167
|
+
markdown text. Since kramdown-rfc cannot know whether a reference
|
165
168
|
is normative or informative, no entry is generated by default in the
|
166
169
|
references section. By indicating a normative reference as in
|
167
170
|
`{{!RFC2119}}` or an informative one as in `{{?RFC1925}}`, you can
|
@@ -333,7 +336,7 @@ not have the tools installed in its docker instance.
|
|
333
336
|
|
334
337
|
More details have been collected on the [wiki][svg].
|
335
338
|
|
336
|
-
[svg]: https://github.com/cabo/kramdown-
|
339
|
+
[svg]: https://github.com/cabo/kramdown-rfc/wiki/SVG
|
337
340
|
|
338
341
|
(1.2.9:)
|
339
342
|
The YAML header now allows specifying [kramdown_options][].
|
@@ -549,7 +552,7 @@ note that this creates ugly blank space in some HTML converters).
|
|
549
552
|
|
550
553
|
The code is not very polished, but now quite stable; it has been successfully used for a
|
551
554
|
number of non-trivial Internet-Drafts and RFCs. You probably still need to
|
552
|
-
skim [
|
555
|
+
skim [v3][] if you want to write an Internet-Draft, but you
|
553
556
|
don't really need to understand XML very much. Knowing the basics of
|
554
557
|
YAML helps with the metadata (but you'll understand it from the
|
555
558
|
examples).
|
@@ -579,7 +582,7 @@ of the work. Please [contact the
|
|
579
582
|
author](mailto:cabo@tzi.org?subject=Markdown%20for%20RFCXML) if you want
|
580
583
|
to try it.
|
581
584
|
|
582
|
-
Actually, if the XML was generated by kramdown-
|
585
|
+
Actually, if the XML was generated by kramdown-rfc, you can simply
|
583
586
|
extract the input markdown from that XML file (but will of course lose
|
584
587
|
any edits that have been made to the XML file after generation):
|
585
588
|
|
@@ -589,21 +592,21 @@ any edits that have been made to the XML file after generation):
|
|
589
592
|
# Tools
|
590
593
|
|
591
594
|
Joe Hildebrand has a
|
592
|
-
[grunt][] plugin for kramdown-
|
595
|
+
[grunt][] plugin for kramdown-rfc at:
|
593
596
|
https://github.com/hildjj/grunt-kramdown-rfc2629
|
594
597
|
.
|
595
598
|
Get started with it at:
|
596
599
|
https://github.com/hildjj/grunt-init-rfc
|
597
600
|
.
|
598
601
|
This provides a self-refreshing web page with the
|
599
|
-
kramdown-
|
602
|
+
kramdown-rfc/xml2rfc rendition of the draft you are editing.
|
600
603
|
|
601
604
|
[grunt]: http://gruntjs.com
|
602
605
|
|
603
606
|
Martin Thomson has an [I-D Template][] for github repositories that enable
|
604
607
|
collaboration on draft development.
|
605
|
-
This supports kramdown-
|
606
|
-
box. Just name your draft like `draft-ietf-unicorn-protocol
|
608
|
+
This supports kramdown-rfc out of the
|
609
|
+
box. Just name your draft like `draft-ietf-unicorn-protocol.md` and
|
607
610
|
follow the installation instructions.
|
608
611
|
|
609
612
|
[I-D Template]: https://github.com/martinthomson/i-d-template
|
@@ -615,12 +618,12 @@ no-brainer, so I'm not the only one who has written code for this.
|
|
615
618
|
|
616
619
|
[Miek Gieben][] has done a [similar thing][pandoc2rfc] employing
|
617
620
|
pandoc, now documented in [RFC 7328][]. He uses multiple input files instead of
|
618
|
-
kramdown-
|
621
|
+
kramdown-rfc's sectionized input format. He keeps the metadata in
|
619
622
|
a separate XML file, similar to the way the previous version of
|
620
|
-
kramdown-
|
623
|
+
kramdown-rfc stored (and still can store) the metadata in XML in
|
621
624
|
the markdown document. He also uses a slightly different referencing
|
622
625
|
syntax, which is closer to what markdown does elsewhere but more
|
623
|
-
verbose (this syntax is now also supported in kramdown-
|
626
|
+
verbose (this syntax is now also supported in kramdown-rfc).
|
624
627
|
(Miek now also has a new thing going on with mostly different syntax,
|
625
628
|
see [mmark][] and its [github repository][mmark-git].)
|
626
629
|
|
@@ -632,14 +635,16 @@ Other human-oriented markup input languages that are being used for authoring RF
|
|
632
635
|
# License
|
633
636
|
|
634
637
|
Since kramdown version 1.0, kramdown itself is MIT licensed, which
|
635
|
-
made it possible to license kramdown-
|
638
|
+
made it possible to license kramdown-rfc under the same license.
|
636
639
|
|
637
640
|
[kramdown]: https://kramdown.gettalong.org
|
638
641
|
[kdsyntax]: http://kramdown.gettalong.org/syntax.html
|
639
642
|
[kdsyntax-ial]: http://kramdown.gettalong.org/syntax.html#inline-attribute-lists
|
640
643
|
[stupid]: http://tools.ietf.org/id/draft-hartke-xmpp-stupid-00
|
641
|
-
[RFC 2629]:
|
642
|
-
[RFC 7749]:
|
644
|
+
[RFC 2629]: https://www.rfc-editor.org/rfc/rfc2629.html
|
645
|
+
[RFC 7749]: https://www.rfc-editor.org/rfc/rfc7749.html
|
646
|
+
[RFC 7991]: https://www.rfc-editor.org/rfc/rfc7991.html
|
647
|
+
[v3]: https://xml2rfc.tools.ietf.org/xml2rfc-doc.html
|
643
648
|
[markdown]: http://en.wikipedia.org/wiki/Markdown
|
644
649
|
[IETF]: http://www.ietf.org
|
645
650
|
[Miek Gieben]: http://www.miek.nl/
|
data/kramdown-rfc2629.gemspec
CHANGED
@@ -1,8 +1,8 @@
|
|
1
1
|
spec = Gem::Specification.new do |s|
|
2
2
|
s.name = 'kramdown-rfc2629'
|
3
|
-
s.version = '1.6.
|
4
|
-
s.summary = "Kramdown extension for generating RFC
|
5
|
-
s.description = %{An
|
3
|
+
s.version = '1.6.2'
|
4
|
+
s.summary = "Kramdown extension for generating RFCXML (RFC 799x)."
|
5
|
+
s.description = %{An RFCXML (RFC 799x) generating backend for Thomas Leitner's
|
6
6
|
"kramdown" markdown parser. Mostly useful for RFC writers.}
|
7
7
|
s.add_dependency('kramdown', '~> 2.3.0')
|
8
8
|
s.add_dependency('kramdown-parser-gfm', '~> 1.1')
|
data/lib/kramdown-rfc2629.rb
CHANGED
@@ -808,7 +808,7 @@ COLORS
|
|
808
808
|
out ="#{' '*indent}<dd><t/></dd>\n" # you can't make this one up
|
809
809
|
end
|
810
810
|
opts[:haddt] = true
|
811
|
-
out << "#{' '*indent}<dt#{el_html_attributes(el)}
|
811
|
+
out << "#{' '*indent}<dt#{el_html_attributes(el)}>#{inner(el, indent, opts)}</dt>\n"
|
812
812
|
else
|
813
813
|
close = "#{' '*indent}</t>\n" * @in_dt
|
814
814
|
@in_dt = 1
|
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.6.
|
4
|
+
version: 1.6.2
|
5
5
|
platform: ruby
|
6
6
|
authors:
|
7
7
|
- Carsten Bormann
|
8
8
|
autorequire:
|
9
9
|
bindir: bin
|
10
10
|
cert_chain: []
|
11
|
-
date: 2022-02-
|
11
|
+
date: 2022-02-24 00:00:00.000000000 Z
|
12
12
|
dependencies:
|
13
13
|
- !ruby/object:Gem::Dependency
|
14
14
|
name: kramdown
|
@@ -67,7 +67,7 @@ dependencies:
|
|
67
67
|
- !ruby/object:Gem::Version
|
68
68
|
version: '2.0'
|
69
69
|
description: |-
|
70
|
-
An
|
70
|
+
An RFCXML (RFC 799x) generating backend for Thomas Leitner's
|
71
71
|
"kramdown" markdown parser. Mostly useful for RFC writers.
|
72
72
|
email: cabo@tzi.org
|
73
73
|
executables:
|
@@ -126,5 +126,5 @@ requirements: []
|
|
126
126
|
rubygems_version: 3.3.3
|
127
127
|
signing_key:
|
128
128
|
specification_version: 4
|
129
|
-
summary: Kramdown extension for generating RFC
|
129
|
+
summary: Kramdown extension for generating RFCXML (RFC 799x).
|
130
130
|
test_files: []
|