Skip to content
Permalink
Browse files

1.1.0: Replaceable anchors (reference labels)

Notable bug fixes in 1.1.0:

* Don't break offline build if reference is broken
* Properly escape attributes in reference XML
  • Loading branch information...
cabo committed Mar 22, 2017
1 parent f54c54c commit ca62a2ddacfe0da550064ff9f55d210a59f98293
Showing with 32 additions and 4 deletions.
  1. +30 −2 README.md
  2. +1 −1 bin/kramdown-rfc2629
  3. +1 −1 kramdown-rfc2629.gemspec
@@ -154,8 +154,36 @@ 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:
Since version 1.1, references imported from the [XML2RFC][] databases
can be supplied with a replacement label (anchor name). E.g., RFC 793
could be referenced as `{{!TCP=RFC0793}}, further references then just
can say `{{TCP}}`; both will get `[TCP]` as the label. In the
YAML, the same replacement can be expressed as in the first example:
normative:
TCP: RFC0793
informative:
SST: DOI.10.1145/1282427.1282421
Notes about this feature:
* At the time of writing, the DOI and IANA repositories are
slightly unstable.
* Thank you, Martin Thomson, for supplying an implementation and
insisting this be done.
* While this feature is now available, you are not forced to use it
for everything: readers of documents often benefit from not having
to look up references, so continuing to use the draft names and RFC
numbers as labels may be the preferrable style in many cases.
* As a final caveat, renaming anchors does not work in the
`stand_alone: no` mode (except for IANA and DOI), as there is no
such mechanism in XML entity referencing; exporting to XML while
maintaining live references then may require some manual editing to
get rid of the custom anchors.
If your references are not in the [XML2RFC][] databases and do not
have a DOI (that also happens to have correct data) either, you need
to spell it out like in the examples below:
informative:
RFC1925:
@@ -64,7 +64,7 @@ def xml_from_sections(input)
end
ref_replacements[v.to_str] = k
end
if v.respond_to? :[]
if Hash === v
if aliasname = v.delete("-")
ref_replacements[aliasname] = k
end
@@ -1,6 +1,6 @@
spec = Gem::Specification.new do |s|
s.name = 'kramdown-rfc2629'
s.version = '1.0.42'
s.version = '1.1.0'
s.summary = "Kramdown extension for generating RFC 7749 XML."
s.description = %{An RFC7749 (XML2RFC) generating backend for Thomas Leitner's
"kramdown" markdown parser. Mostly useful for RFC writers.}

0 comments on commit ca62a2d

Please sign in to comment.
You can’t perform that action at this time.