idnits 2.17.1 draft-brownlee-svg-rfc-03.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack a Security Considerations section. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 461 has weird spacing: '...he list below...' == Line 462 has weird spacing: '...eft,and their...' == Line 465 has weird spacing: '...bset of the S...' -- The document date (April 14, 2014) is 3665 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Informational ---------------------------------------------------------------------------- == Missing Reference: 'SVG' is mentioned on line 77, but not defined Summary: 1 error (**), 0 flaws (~~), 5 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group N. Brownlee (Ed.) 3 Internet-Draft The University of Auckland 4 Intended status: Informational IAB 5 Expires: October 16, 2014 6 April 14, 2014 8 SVG Drawings for RFCs: SVG 1.2 RFC 9 draft-brownlee-svg-rfc-03 11 Abstract 13 This document specifies SVG 1.2 RFC - an SVG profile for use in 14 diagrams that may appear in RFCs - and considers some of the issues 15 concerning the creation and use of such diagrams. 17 Status of This Memo 19 This Internet-Draft is submitted in full conformance with the 20 provisions of BCP 78 and BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF). Note that other groups may also distribute 24 working documents as Internet-Drafts. The list of current Internet- 25 Drafts is at http://datatracker.ietf.org/drafts/current/. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 This Internet-Draft will expire on October 16, 2014. 34 Copyright Notice 36 Copyright (c) 2014 IETF Trust and the persons identified as the 37 document authors. All rights reserved. 39 This document is subject to BCP 78 and the IETF Trust's Legal 40 Provisions Relating to IETF Documents 41 (http://trustee.ietf.org/license-info) in effect on the date of 42 publication of this document. Please review these documents 43 carefully, as they describe your rights and restrictions with respect 44 to this document. Code Components extracted from this document must 45 include Simplified BSD License text as described in Section 4.e of 46 the Trust Legal Provisions and are provided without warranty as 47 described in the Simplified BSD License. 49 Table of Contents 51 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 52 2. SVG 1.2 RFC: An SVG profile for RFCs . . . . . . . . . . . . 2 53 3. How to create SVG drawings . . . . . . . . . . . . . . . . . 4 54 4. Meta-language for diagrams common in RFCs . . . . . . . . . . 4 55 4.1. Packet Layout Diagrams . . . . . . . . . . . . . . . . . 4 56 4.2. Sequence Digrgams (1) . . . . . . . . . . . . . . . . . . 5 57 4.3. Sequence Digrgams (2) . . . . . . . . . . . . . . . . . . 7 58 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 59 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 10 60 7. Revision History [RFC Editor please delete] . . . . . . . . . 10 61 8. Appendix: Elements and attributes allowed in SVG 1.2 RFC . . 10 62 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 12 63 9.1. Normative References . . . . . . . . . . . . . . . . . . 12 64 9.2. Informative References . . . . . . . . . . . . . . . . . 13 65 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 13 67 1. Introduction 69 Over the last two years the RFC Editor has worked with the Internet 70 community to develop specifications for changes in the format of 71 RFCs. An outline of the resulting specifications was published as 72 [RFC6949] in May 2013. Since then a Design Team has been working 73 with the RFC Editor to flesh out those specifications. One aspect of 74 the changes is to allow line drawings in RFCs; [RFC6949] says 76 "Graphics may include ASCII art and a more complex form to be 77 defined, such as SVG line art [SVG]. Color and grayscale will not 78 be accepted. RFCs must correctly display in monochromatic black- 79 and-white to allow for monochrome displays, black-and- white 80 printing, and support for visual disabilities." 82 SVG (Scalable Vector Graphics) has been developed by W3C, the World 83 Wide Web Consortium; its current standard is SVG 1.1 Full 84 [W3C.REC-SVG11-20110816]. This document defines SVG 1.2 RFC, an SVG 85 profile (i.e. a subset of SVG) that is suitable for RFC line 86 drawings. 88 Note that in RFCs, the text provides normative descriptions of 89 protocols, systems, etc. Diagrams may be used to help explain 90 concepts more clearly, but they are informative, not normative. 92 2. SVG 1.2 RFC: An SVG profile for RFCs 94 As a starting point for SVG 1.2 RFC, the Design Team decided to use 95 SVG 1.2 Tiny [W3C.REC-SVGTiny12-20081222]. SVG 1.2 Tiny is an SVG 96 subset intended to be implemented on small, mobile devices such as 97 cellphones and smartphones. That should allow RFCs to be rendered 98 well on such devices, especially those that have small screens. 99 However, RFCs are self-contained documents that do not change once 100 they are published. The use of SVG drawings in RFCs is intended to 101 allow authors to create drawings that are simple to produce, and 102 easier to understand than our traditional 'ASCII Art' ones. In 103 short, we are also trying to improve access to the content in RFCs, 104 so SVG drawings need to be kept as simple as possible. 106 SVG can provide a complete User Interface, but within RFCs, all we 107 need are simple diagrams that do not change once the RFC is 108 published. Therefore, SVG RFC does not allow anything from the 109 following sections in SVG Tiny 1.2 [W3C.REC-SVGTiny12-20081222]: 111 12 Multimedia 112 13 Interactivity 113 15 Scripting 114 16 Animation 115 18 Metadata 116 19 Extensibility 118 Note that SVG Tiny 1.2 elements may have many properties or 119 attributes that are needed to support aspects of the above sections. 120 Those are not allowed in SVG 1.2 RFC. 122 Considering the other sections in SVG Tiny 1.2 123 [W3C.REC-SVGTiny12-20081222]: 125 9 Basic Shapes 126 10 Text 127 Everything in these sections is allowed in SVG 1.2 RFC. 129 11 Painting: Filling, Stroking, Colors and Paint Servers 130 Anything relating to 'color' is not allowed in SVG 1.2 RFC, 131 everything else is allowed. 133 14 Linking 134 SVG Tiny 1.2 allows internationalized IRIs in references. In 135 SVG 1.2 RFC such links must be ASCII only. That should not 136 cause problems, since one can just use the URI form of any IRI. 137 Authors should try to use links only to URIs that are long-trem 138 stable. 140 17 Fonts 141 SVG 1.2 RFC only allows 'serif', 'sans-serif' and 'monospace' 142 generic font families from the WebFonts facility, described in 143 CSS 2.1, section 15, Fonts. In particular, the SVG 'font' 144 element is not allowed. 146 3. How to create SVG drawings 148 Many drawing packages can be used to create SVG drawings, for example 149 Open Source packages Inkscape and Dia. Be aware that such packages 150 may use SVG elements or attributes that are not allowed in SVG 1.2 151 RFC. For example, the 'marker' attribute is often used to place 152 symbols such as arrowheads on lines, but 'marker' is not allowed in 153 SVG 1.2 Tiny or SVG 1.2 RFC. In such cases one has to draw the 154 arrowhead in another, simpler way. 156 We will need to provide a tool to check that a diagram only uses 157 elements and attributes that are allowed in SVG 1.2 RFC. These are 158 listed in the Appendix below. 160 Diagrams produced with these packages may produce large SVG files 161 that are hard to read or understand directly. We should provide a 162 tool to strip out unnecccessary attributes; authors could run that 163 tool over their drawings, and see whether such stripping causes any 164 visible changes. If such changes occur, authors may find it 165 difficult to work out how to fix any such changes. The tool should 166 produce a list of non-allowed keywords and the context in which they 167 were found. 169 Another way to create SVG drawings is to write programs to draw them. 170 For example, using python and its svgwrite module is a pleasant 171 environment (for those who like writing code). 173 4. Meta-language for diagrams common in RFCs 175 This section presents a few examples of possible language(s) which 176 could be used to create the kinds of diagrams that are most common in 177 RFCs. 179 The SVG diagrams produced from the following examples can be seen at 180 https://www.cs.auckland.ac.nz/~nevil/SVG_RFC_1.2/ 181 along with an html version of this draft that includes the svg 182 diagrams. 184 4.1. Packet Layout Diagrams 186 Example: Figure 3 from RFC 793. 188 In these examples the first line specifies the generated SVG 189 filename. The scale factor determines the size of the SVG drawing; 190 it needs to be set so that the drawing fits nicely into the final 191 document. 193 'packet;' starts the packet description; it's followed by a 194 description of the fields in each row. 196 info; 197 output "tcp-header.svg", scale 0.65; 199 packet; 200 row 0; 201 field "Source Port", 0 to 15; 202 field "Destination Port", 16 to 31; 203 row 1; 204 field "Sequence Number", 0 to 31; 205 row 2; 206 field "Acknowledgement Number", 0 to 31; 207 row 3; 208 field "Data Offset", 0 to 3; 209 field "Reserved", 4 to 9; 210 field "Urg", 10 to 10, fsize 14; # 14 px font so the flags fit 211 field "Ack", 11 to 11, fsize 14; 212 field "Psh", 12 to 12, fsize 14; 213 field "Rst", 13 to 13, fsize 14; 214 field "Syn", 14 to 14, fsize 14; 215 field "Fin", 15 to 15, fsize 14; 216 field "Window", 16 to 31; 217 row 4; 218 field "Checksum", 0 to 15; 219 field "Urgent Pointer", 16 to 31; 220 row 5; 221 field "Options", 0 to 23; 222 field "Padding", 24 to 31; 223 row 6; 224 field "Data", 0 to 31; 226 4.2. Sequence Digrgams (1) 228 Example: Figure 6 from draft-loreto-httpbis-trusted-proxy20-00. 230 In this example, columns are vertical lines with a text header above 231 them. There are three columns, and columns 1 and 2 are spaced 250 232 pixels apart. 234 The rest of the file describes objects to be drawn; most of them are 235 plines (polylines) from one colun to another, but object 3 only 236 extends across to 0.3 of the distance between columns 1 and 2. 238 info; 239 output "httpbis-proxy20-fig6.svg", scale 0.9; 241 #Thu, 30 Jan 14 (NZDT) 243 #Figure 6 of draft-loreto-httpbis-trusted-proxy20-00.txt 245 column 1 width 250; # columns have vertical line to bottom 246 text above "user-agent"; 248 column 2 width 250; 249 text "Proxy"; 251 column 3; # Last col 252 text "Server"; 254 object 1; # Only need polylines 255 pline 1 to 2, arrowhead at end; 256 text above "(1) TLS ClientHello"; 257 text below "(ALPN ProtocolName: http)"; 259 object 2; 260 pline 1 to 2, arrowhead at start; 261 text above "(2) TLS Error"; 262 text below "(Proxy Cert)"; 264 object 3; 265 pline 1 to 1.3, down, back to 1, arrowhead at end; 266 text seg 2 centre "(inform user of the SecureProxy)"; 268 object 4; 269 pline 1 to 2, arrowhead at end; 270 text above "(3) TLS ClientHello"; 272 object 5; 273 pline 1 to 2, arrowhead at start; 274 text above "(4) ServerHello"; 276 object 6; 277 blank 1 to 2; 279 object 7; 280 block 1 to 2, objects 8 to 15, colour "grey"; 281 text above "HTTP2.0"; 283 object 8; 284 pline 1 to 2, arrowhead at end; 285 text seg 1 centre "(5) stream(X) GET"; 287 object 9; 288 pline 2 to 3, arrowhead at end; 289 text seg 1 above "(6) TLS ClientHello"; 291 object 10; 292 pline 2 to 3, arrowhead at start; 293 text seg 1 above "TLS ServerHello"; 295 object 11; 296 blank 2 to 3; 298 object 12; 299 block 2 to 3, objects 13 to 15, colour "grey"; 300 text seg 1 above "HTTP2.0"; 302 object 13; 303 pline 2 to 3, arrowhead at end; 304 text seg 1 centre "(7) stream(Z) GET"; 306 object 14; 307 pline 2 to 3, arrowhead at start; 308 text seg 1 centre "(8) stream(Z) 200 OK"; 310 object 15; 311 pline 1 to 2, arrowhead at start; 312 text seg 1 centre "(9) stream(X) 200 OK"; 314 4.3. Sequence Digrgams (2) 316 Example: Figure 3 from RFC 4321 318 This example uses (x,y) coordinates to specify points in in plines. 319 For these, the x units are columns and the y units are lines 320 (positive means 'down the diagram'). 322 both x and y may be absolute, e.g. 4.3, or relative, e.g. +1.5). 323 For the first point of a pline, relative means 'relative to the 324 starting point of the previous pline,' for other points in a pline it 325 means 'relative to the last point.' 327 Note that column 1 is drawn in white, i.e. nothing is drawn for it. 328 It's simply used to make a blank area where objects 8 and 9 can place 329 text. For both those objects a pline is used to specify the text's 330 position. 332 Last, the metalanguage allows simple macros, introduced by 'define 333 foo = '. These make it easier to re-use definitions, for example of 334 line types. 336 info; 337 output "rfc4321-fig3.svg", scale 0.9; 339 # Sat, 5 Apr 14 (NZDT) 341 #Figure 3 of RFC 4321 343 define hw = width 110; # Hop width 345 column 1 width 130, colour "white"; # No heading or vertical line 347 column 2 hw; text above "UAC"; 349 column 3 hw; text "P1"; 351 column 4 hw; text "P2"; 353 column 5 hw; text "P3"; 355 column 6 hw; text "UAS"; 357 define tgrey = colour "lightgrey" width 5; # Thick grey 358 define ahe = arrowhead at end; 360 object 1; 361 pline 1.8 362 to 2.3 tgrey, to (2.4,+0), to (2.6,+1.5), to (2.7,+0) ahe, 363 to 3.3 tgrey, to (3.4,+0), to (3.6,+1.5), to (3.7,+0) ahe, 364 to 4.3 tgrey, to (4.4,+0), to (4.6,+1.5), to (4.7,+0) ahe, 365 to 5.3 tgrey, to (5.4,+0), to (5.6,+1.5), to (5.7,+0) ahe, 366 to 6.3 tgrey; 368 object 2; 369 pline (1.8,+10) to 2.3 tgrey; 371 object 3; 372 pline (3.3,+2) 373 to 2.85 tgrey, to (2.7,+0) tgrey, 374 to (2.5,+0), to (2.25,+1.5), to (2.0,+0) ahe; 375 text seg 2 centre "408"; 377 object 4; 378 pline (4.3,+1.5) 379 to 3.9 tgrey, to (3.7,+0) tgrey, 380 to (3.5,+0), to (3.3,+1.5), to (3.1,+0) ahe, 381 to 2.9 tgrey, to (2.7,+0) tgrey, 382 to (2.5,+0), to (2.25,+1.5), to (2.0,+0) ahe; 383 text seg 2 centre "408"; 384 text seg 7 centre "408"; 386 object 5; 387 pline (5.3,+1.5) 388 to 4.9 tgrey, to (4.7,+0) tgrey, 389 to (4.5,+0), to (4.3,+1.5), to (4.1,+0) ahe, 390 to 3.9 tgrey, to (3.7,+0) tgrey, 391 to (3.5,+0), to (3.3,+1.5), to (3.1,+0) ahe, 392 to 2.9 tgrey, to (2.7,+0) tgrey, 393 to (2.5,+0), to (2.25,+1.5), to (2.0,+0) ahe; 394 text seg 2 centre "408"; 395 text seg 7 centre "408"; 396 text seg 12 centre "408"; 398 object 6; 399 pline (6.3,+1.5) 400 to 5.9 tgrey, to (5.7,+0) tgrey, 401 to (5.5,+0), to (5.3,+1.5), to (5.1,+0) ahe; 402 to 4.9 tgrey, to (4.7,+0) tgrey, 403 to (4.5,+0), to (4.3,+1.5), to (4.1,+0) ahe; 404 to 3.9 tgrey, to (3.7,+0) tgrey, 405 to (3.5,+0), to (3.3,+1.5), to (3.1,+0) ahe; 406 to 2.9 tgrey, to (2.7,+0) tgrey, 407 to (2.5,+0), to (2.25,+1.5), to (2.0,+0) ahe; 408 text seg 2 centre "408"; 409 text seg 7 centre "408"; 410 text seg 12 centre "408"; 411 text seg 17 centre "408"; 413 object 7: 414 pline (1.63,4.1) to (1.73,+0); 416 object 8; 417 pline (1.68,4.1) to (+0,14) arrowhead at end; 418 text centre "64*T1"; 420 object 9; 421 pline (1.2,13.1) to (1.5,+0) colour "white"; 422 text centre "(timeout)"; 424 5. IANA Considerations 426 This document does not create a new registry nor does it register any 427 values in existing registries; no IANA action is required. 429 6. Acknowledgements 431 Thanks to the Design Team members for their helpful comments and 432 suggestions for SVG 1.2 RFC. 434 7. Revision History [RFC Editor please delete] 436 version -03, 14 Apr 14: 437 Added two more example diagrams; a simple packet layout, and a 438 diagram that uses lots of diagonal lines. 440 version -02, 12 Feb 14: 441 Added metalanguage example to make time-sequence drawings. 443 version -01, 11 Feb 14: 444 Allow links to 'long-term stable URIs' 445 Link URIs must be ASCII only 446 Need for tools to check SVG 1.2 RFC compatibilty and to strip 447 'unneccessary' attributes explicitly stated. 448 Statement that drawings can't be normative removed; Postscript- 449 only RFCs already exist. 450 Added most attributes and elements to the Appendix. 452 version -00, 29 Jan 14: 453 Initial version, using content from Nevil's 454 emails to the Design Team. 456 8. Appendix: Elements and attributes allowed in SVG 1.2 RFC 458 Elements, properties and attributes selected for SVG 1.2 RFC from 459 [W3C.REC-SVGTiny12-20081222]. 461 In the list below, elements and properties are listed on the 462 left,and their allowed values are given in parentheses on the 463 right. 464 , the list of allowed colours, is a black-and-white 465 subset of the SVG colour names. 467 Elements: 469 svg (version, baseProfile=tiny, width, viewBox, 470 preserveAspectRatio, snapshotTime) 471 g 472 defs 473 title 474 desc 475 use (x, y, xlink:href) 476 rect (x, y, width, height, rx, ry) 477 circle (cx, cy, r) 478 ellipse (cx, cy, rx, ry) 479 line (x1, y1, x2, y2) 480 polyline (points) 481 polygon (points) 483 text (x, y, rotate) 484 tspan 485 textArea (x, y, width, height, auto) 486 tbreak 488 solidcolor 489 linearGradient (gradientUnits, x1, y1, x2, y2) 490 radialGradient (gradientUnits, cx, cy, r) 491 stop (offset) 493 Properties: (most allow inherit as a value) 495 stroke 496 stroke-width 497 stroke-linecap (butt, round, square) 498 stroke-linejoin (miter, round, bevel) 499 stroke-mitrelimit 500 stroke-dasharray 501 stroke-dashoffset 502 stroke-opacity 503 vector-effect (non-scaling-stroke, none) 504 viewport-fill (none, currentColor) 505 viewport-fill-opacity 507 display (inline, block, list-item, run-in, compact, 508 marker, table, inline-table, table-row-group, 509 table-header-group, table-footer-group, 510 table-row, table-column-group, 511 table-column, table-cell, table-caption, 512 none) 513 visibility (visible, hidden, collapse) 514 color-rendering (auto, optimizeSpeed, optimizeQuality) 515 shape-rendering (auto, optimizeSpeed, crispEdges, 516 geometricPrecision) 517 text-rendering (auto, optimizeSpeed, optimizeLegibility, 518 geometricPrecision) 519 buffered-rendering (auto, dynamic, static) 521 (black, grey, darkgrey, dimgrey, lightgrey, 522 gray, darkgray, dimgray, lightgray, white) 523 opacity 524 solid-opacity 525 solid-color (currentColor, ) 526 color (currentColor, ) 528 stop-color (currentColor, ) 529 stop-opacity 531 line-increment (auto) 532 text-align (start,end, center) 533 display-align (auto, before, center, after) 535 font-size 536 font-family (serif, sans-serif, monospace) 537 font-weight (normal, bold, bolder, lighter) 538 font-style (normal, italic, oblique) 539 font-variant (normal, small-caps) 540 direction (ltr, rtl) 541 unicode-bidi (normal, embed, bidi-override) 542 text-anchor (start, middle, end) 543 fill (none, black or grey) 544 fill-rule (nonzero, evenodd) 545 fill-opacity 547 9. References 549 9.1. Normative References 551 [RFC6949] Flanagan, H. and N. Brownlee, "RFC Series Format 552 Requirements and Future Development", RFC 6949, May 2013. 554 [W3C.REC-SVGTiny12-20081222] 555 Andersson, O., Berjon, R., DahlstrAP.m, E., Emmons, A., 556 Ferraiolo, J., Grasso, A., Hardy, V., Hayman, S., Jackson, 557 D., Lilley, C., McCormack, C., Neumann, A., Northway, C., 558 Quint, A., Ramani, N., Schepers, D., and A. Shellshear, 559 "Scalable Vector Graphics (SVG) Tiny 1.2 Specification", 560 World Wide Web Consortium Recommendation REC- 561 SVGTiny12-20081222, December 2008, 562 . 564 [W3C.REC-CSS2-20110607] 565 Bos, B., Celik, T., Hickson, I., and H. Lie, "Cascading 566 Style Sheets Level 2 Revision 1 (CSS 2.1) Specification", 567 World Wide Web Consortium Recommendation REC- 568 CSS2-20110607, June 2011, 569 . 571 9.2. Informative References 573 [W3C.REC-SVG11-20110816] 574 DahlstrAP.m, E., Dengler, P., Grasso, A., Lilley, C., 575 McCormack, C., Schepers, D., Watt, J., Ferraiolo, J., 576 Fujisawa, J., and D. Jackson, "Scalable Vector Graphics 577 (SVG) 1.1 (Second Edition)", World Wide Web Consortium 578 Recommendation REC-SVG11-20110816, August 2011, 579 . 581 Authors' Addresses 583 Nevil Brownlee 584 The University of Auckland 586 Email: n.brownlee@auckland.ac.nz 588 Internet Architecture Board 590 Email: iab@iab.org