Internet-Draft SVG Tests March 2020
Fossati Expires 11 September 2020 [Page]
Workgroup:
None
Internet-Draft:
draft-fossati-svg-test-01
Published:
Intended Status:
Experimental
Expires:
Author:
T. Fossati

SVG Tests

Abstract

This memo is for experimenting with SVG in the context of RFC production.

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."

This Internet-Draft will expire on 11 September 2020.

▲

Table of Contents

1. Introduction

This memo is for experimenting with SVG in the context of RFC production.

This document assumes a kramdown-rfc2629 based editing flow.

1.1. Conventions used in this document

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

2. Code Layout

The code is structured as follows:

├── Makefile
├── art
│   ├── cdni-delegation.ascii-art
│   ├── cdni-dns-redirection.ascii-art
│   ├── e2e-flow.ascii-art
│   ├── stir-delegation.ascii-art
│   └── stir-delegation.svg
└── draft-fossati-svg-test.md

In particular, the art directory contains the diagrams in ASCII art.

3. From ASCII art to SVG

The Makefile contains bunch of variables and a pattern rule to deal with automatic generation of SVG from ASCII using a Golang tool called goat. Another tool, svgcheck, is used to make sure xml2rfc will like the SVG.

# The "art" variables:

art_src := $(wildcard $(art_dir)/*.ascii-art)
art_svg := $(art_src:.ascii-art=.svg)


# The pattern rule used to transform each and every ASCII
# art into SVG:

%.svg: %.ascii-art
    @$(goat) $< | $(svgcheck) -r -o $@ 2>/dev/null || true

To install goat and svgcheck, do:

$ go get github.com/blampe/goat
$ pip install svgcheck

4. Building the XML

The Submit tool on the Datatracker wants the submitted XML to be self contained.

To inline the diagrams you need to do the following:

$ kramdown-rfc2629 --v3 \
    draft-fossati-svg-test.md > draft-fossati-svg-test.xml
$ xml2rfc --v3 --preptool draft-fossati-svg-test.xml
$ xml2rfc --v3 --expand draft-fossati-svg-test.prepped.xml
$ mv draft-fossati-svg-test.prepped.exp.xml \
    draft-fossati-svg-test.xml
$ rm -f draft-fossati-svg-test.prepped.xml

The "prepped" and "expanded" draft-fossati-svg-test.xml inlines both the ASCII and the SVG in the artset and is ready for submission.

Of course, from there you can also do the usual TXT / HTML generation:

$ xml2rfc --v3 draft-fossati-svg-test.xml \
    draft-fossati-svg-test.txt
$ xml2rfc --v3 --html draft-fossati-svg-test.xml \
    draft-fossati-svg-test.html

5. Examples

5.1. A Sequence Diagram

kramdown does not support artset natively. So the artset must be inserted using native xml2rfc syntax. The SVG is included in artwork as a local file. The SVG file is created from its ASCII art equivalent as explained in Section 3.

<t>
  <figure anchor="fig-endtoend"
          title="End to end STAR delegation flow">
    <artset>
      <artwork type="ascii-art"
               src="art/e2e-flow.ascii-art" />
      <artwork type="svg"
               src="art/e2e-flow.svg" />
    </artset>
  </figure>
</t>

The result is shown in Figure 1.

d s g a r r . u r v t c n G n r r u n C w t r o i l A t o n S < e n a c g > E t i ~ d ' e t f m i i e e a p N u i G t C g ~ r d ) S t i ~ S i r ~ a n u t i t R r e a i ] o h t a e ~ c e i f r e n < A t t ( v r m ( R r e q i T S r a g n u a n t a R o t ) c e t d g w # n a S ( i i t f c a d o n s G e c i c e A s a f g l d i V c ~ a [ t ~ e 1 d T o T a # ] e h i e u ~ n > e e t c r u f i e i n t . e [ e n - i r i N i t A s n O e r s t R h d s e C e a n S n d e a u l c t a A R R A I i w S i ] u S g i n ~ u e t e A t w C e a n t i T t r e e r s l e e d a e T A C o a > u i A h c C t # e d u e C k s v e a e ~ e . S T f O C c a t i o t r i e n e i e [ S c a i e E 2 e n d ~ c ) y e l r t R t u D i t i ~ k < ~ t t t i ~ n E a C O i u ~ c t a e n u i l S c t a n r z n t S
Figure 1: End to end STAR delegation flow

5.2. Lots of Boxes and Arrows 

<t>
  <figure anchor="fig-cdni-dns-redirection"
          title="DNS Redirection">
    <artset>
      <artwork type="ascii-art"
               src="art/cdni-dns-redirection.ascii-art" />
      <artwork type="svg"
               src="art/cdni-dns-redirection.svg" />
    </artset>
  </figure>
</t>
x d m e A p o i u c 0 c x ? x o N M v ) D d v C . d S C : d N l i n e L v d e ) c . a l 2 e . A d ? v a N ) p d m a m I e v S . d m n p m ? u u M d . p l N S 2 . D o c i d c T m p U C N x c N p v E i e e d ( d ( . c C o . e p x e l . . D A E i 1 S a n . l C e ( . a e e e T o 1 . e o x 9 S p N N e l e e A a D D e . L i . S b d S N a P D n
Figure 2: DNS Redirection

5.3. Even More Boxes and Numbered Arrows 

<t>
  <figure anchor="fig-cdni-flow"
          title="Two levels delegation in CDNI">
    <artset>
      <artwork type="ascii-art"
               src="art/cdni-delegation.ascii-art" />
      <artwork type="svg"
               src="art/cdni-delegation.svg" />
    </artset>
  </figure>
</t>
D P l v C 2 S E S C f C l R C A S C I e T C D w E 4 T e R 6 A 5 T c l i N d l 9 P e s 1 8 N d c T A l R R 7 H T P A N A S H u I 3 D 0 A d T R D 0 N e e T i A r e M T C 1 M d S T d C A
Figure 3: Two levels delegation in CDNI

5.4. And Another One 

<t>
  <figure anchor="fig-stir-flow"
          title="Delegation in STIR">
    <artset>
      <artwork type="ascii-art"
               src="art/stir-delegation.ascii-art" />
      <artwork type="svg"
               src="art/stir-delegation.svg" />
    </artset>
  </figure>
</t>
R H 2 T A A s v E P e e 5 l T c l R d A C P T A T S e l e 4 T T d l l C S 2 d A e r c T 7 S S 1 i P i S P A H T e 1 3 R M 6 R S
Figure 4: Delegation in STIR

6. IANA Considerations

No requests are made to IANA.

7. Security Considerations

There are none.

8. Acknowledgments

Yaron for pointing out the current limitations in the tooling and providing the workaround.

9. Normative References

[RFC2119]
Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, , <https://www.rfc-editor.org/info/rfc2119>.
[RFC8174]
Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, , <https://www.rfc-editor.org/info/rfc8174>.

Author's Address

Thomas Fossati