idnits 2.17.1 draft-brownlee-svg-rfc-04.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 152 has weird spacing: '...he list below...' == Line 153 has weird spacing: '...eft,and their...' == Line 156 has weird spacing: '...bset of the S...' -- The document date (April 30, 2014) is 3642 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: November 1, 2014 6 April 30, 2014 8 SVG Drawings for RFCs: SVG 1.2 RFC 9 draft-brownlee-svg-rfc-04 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 November 1, 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 2.1. Elements and attributes allowed in SVG 1.2 RFC . . . . . 4 54 3. How to create SVG drawings . . . . . . . . . . . . . . . . . 6 55 4. Meta-language for diagrams common in RFCs . . . . . . . . . . 6 56 4.1. Packet Layout Diagrams . . . . . . . . . . . . . . . . . 7 57 4.2. Sequence Diagrams (1) . . . . . . . . . . . . . . . . . . 7 58 4.3. Sequence Diagrams (2) . . . . . . . . . . . . . . . . . . 9 59 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 60 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 12 61 7. Revision History [RFC Editor please delete] . . . . . . . . . 12 62 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 12 63 8.1. Normative References . . . . . . . . . . . . . . . . . . 12 64 8.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. This is a requirement documented in 132 [RFC6949]. 134 14 Linking 135 SVG Tiny 1.2 allows internationalized IRIs in references. In 136 SVG 1.2 RFC such links must be ASCII only. That should not 137 cause problems, since one can just use the URI form of any IRI. 138 Authors should try to use links only to URIs that are long-term 139 stable. 141 17 Fonts 142 SVG 1.2 RFC only allows 'serif', 'sans-serif' and 'monospace' 143 generic font families from the WebFonts facility, described in 144 CSS 2.1, [W3C.REC-CSS2-20110607], section 15, Fonts. In 145 particular, the SVG 'font' element is not allowed. 147 2.1. Elements and attributes allowed in SVG 1.2 RFC 149 Elements, properties and attributes selected for SVG 1.2 RFC from 150 [W3C.REC-SVGTiny12-20081222]. 152 In the list below, elements and properties are listed on the 153 left,and their allowed values are given in parentheses on the 154 right. 155 , the list of allowed colours, is a black-and-white 156 subset of the SVG colour names. 158 Elements: 160 svg (version, baseProfile=tiny, width, viewBox, 161 preserveAspectRatio, snapshotTime) 162 g 163 defs 164 title 165 desc 166 use (x, y, xlink:href) 168 rect (x, y, width, height, rx, ry) 169 circle (cx, cy, r) 170 ellipse (cx, cy, rx, ry) 171 line (x1, y1, x2, y2) 172 polyline (points) 173 polygon (points) 175 text (x, y, rotate) 176 tspan 177 textArea (x, y, width, height, auto) 178 tbreak 180 solidcolor 181 linearGradient (gradientUnits, x1, y1, x2, y2) 182 radialGradient (gradientUnits, cx, cy, r) 183 stop (offset) 185 Properties: (most allow inherit as a value) 187 stroke 188 stroke-width 189 stroke-linecap (butt, round, square) 190 stroke-linejoin (miter, round, bevel) 191 stroke-mitrelimit 192 stroke-dasharray 193 stroke-dashoffset 194 stroke-opacity 195 vector-effect (non-scaling-stroke, none) 196 viewport-fill (none, currentColor) 197 viewport-fill-opacity 199 display (inline, block, list-item, run-in, compact, 200 marker, table, inline-table, table-row-group, 201 table-header-group, table-footer-group, 202 table-row, table-column-group, 203 table-column, table-cell, table-caption, 204 none) 205 visibility (visible, hidden, collapse) 206 color-rendering (auto, optimizeSpeed, optimizeQuality) 207 shape-rendering (auto, optimizeSpeed, crispEdges, 208 geometricPrecision) 209 text-rendering (auto, optimizeSpeed, optimizeLegibility, 210 geometricPrecision) 211 buffered-rendering (auto, dynamic, static) 213 (black, grey, darkgrey, dimgrey, lightgrey, 214 gray, darkgray, dimgray, lightgray, white) 215 opacity 216 solid-opacity 217 solid-color (currentColor, ) 218 color (currentColor, ) 220 stop-color (currentColor, ) 221 stop-opacity 223 line-increment (auto) 224 text-align (start,end, center) 225 display-align (auto, before, center, after) 227 font-size 228 font-family (serif, sans-serif, monospace) 229 font-weight (normal, bold, bolder, lighter) 230 font-style (normal, italic, oblique) 231 font-variant (normal, small-caps) 232 direction (ltr, rtl) 233 unicode-bidi (normal, embed, bidi-override) 234 text-anchor (start, middle, end) 235 fill (none, black or grey) 236 fill-rule (nonzero, evenodd) 237 fill-opacity 239 3. How to create SVG drawings 241 Many drawing packages can be used to create SVG drawings, for example 242 Open Source packages Inkscape and Dia. Be aware that such packages 243 may use SVG elements or attributes that are not allowed in SVG 1.2 244 RFC. For example, the 'marker' attribute is often used to place 245 symbols such as arrowheads on lines, but 'marker' is not allowed in 246 SVG 1.2 Tiny or SVG 1.2 RFC. In such cases one has to draw the 247 arrowhead in another, simpler way. 249 We will need to provide a tool to check that a diagram only uses 250 elements and attributes that are allowed in SVG 1.2 RFC. These are 251 listed in the Appendix below. 253 Diagrams produced with these packages may produce large SVG files 254 that are hard to read or understand directly. We should provide a 255 tool to strip out unnecessary attributes; authors could run that tool 256 over their drawings, and see whether such stripping causes any 257 visible changes. If such changes occur, authors may find it 258 difficult to work out how to fix any such changes. The tool should 259 produce a list of non-allowed keywords and the context in which they 260 were found. 262 Another way to create SVG drawings is to write programs to draw them. 263 For example, using python and its svgwrite module is a pleasant 264 environment (for those who like writing code). 266 4. Meta-language for diagrams common in RFCs 268 One of the long-term goals for RFCs is to make them more accessible, 269 e.g. to sight-impaired readers. For diagrams, it would be useful for 270 authors to provide alternative forms of the diagram, so that voice- 271 reading software could be used to 'talk through' the diagram. Simply 272 reading the SVG code for a complex diagram seems unlikely to work. 274 This section presents a few examples of possible meta-languages which 275 could be used to create the kinds of diagrams that are most common in 276 RFCs. Note that they are merely examples, they do not imply that 277 these particular experimental languages might be more widely 278 implemented or used. Instead, they seem to show that designing meta- 279 anguages simple enough to serve as audible representations of complex 280 diagrams is difficult indeed! 282 The SVG diagrams produced from the following examples can be seen at 283 https://www.cs.auckland.ac.nz/~nevil/SVG_RFC_1.2/ 284 along with an html version of this draft that includes the svg 285 diagrams. 287 4.1. Packet Layout Diagrams 289 Example: Figure 3 from RFC 793. 291 In these examples the first line specifies the generated SVG 292 filename. The scale factor determines the size of the SVG drawing; 293 it needs to be set so that the drawing fits nicely into the final 294 document. 296 'packet;' starts the packet description; it's followed by a 297 description of the fields in each row. 299 info; 300 output "tcp-header.svg", scale 0.65; 302 packet; 303 row 0; 304 field "Source Port", 0 to 15; 305 field "Destination Port", 16 to 31; 306 row 1; 307 field "Sequence Number", 0 to 31; 308 row 2; 309 field "Acknowledgement Number", 0 to 31; 310 row 3; 311 field "Data Offset", 0 to 3; 312 field "Reserved", 4 to 9; 313 field "Urg", 10 to 10, fsize 14; # 14 px font so the flags fit 314 field "Ack", 11 to 11, fsize 14; 315 field "Psh", 12 to 12, fsize 14; 316 field "Rst", 13 to 13, fsize 14; 317 field "Syn", 14 to 14, fsize 14; 318 field "Fin", 15 to 15, fsize 14; 319 field "Window", 16 to 31; 320 row 4; 321 field "Checksum", 0 to 15; 322 field "Urgent Pointer", 16 to 31; 323 row 5; 324 field "Options", 0 to 23; 325 field "Padding", 24 to 31; 326 row 6; 327 field "Data", 0 to 31; 329 4.2. Sequence Diagrams (1) 331 Example: Figure 6 from draft-loreto-httpbis-trusted-proxy20-00. 333 In this example, columns are vertical lines with a text header above 334 them. There are three columns, and columns 1 and 2 are spaced 250 335 pixels apart. 337 The rest of the file describes objects to be drawn; most of them are 338 plines (polylines) from one column to another, but object 3 only 339 extends across to 0.3 of the distance between columns 1 and 2. 341 info; 342 output "httpbis-proxy20-fig6.svg", scale 0.9; 344 #Thu, 30 Jan 14 (NZDT) 346 #Figure 6 of draft-loreto-httpbis-trusted-proxy20-00.txt 348 column 1 width 250; # columns have vertical line to bottom 349 text above "user-agent"; 351 column 2 width 250; 352 text "Proxy"; 354 column 3; # Last col 355 text "Server"; 357 object 1; # Only need polylines 358 pline 1 to 2, arrowhead at end; 359 text above "(1) TLS ClientHello"; 360 text below "(ALPN ProtocolName: http)"; 362 object 2; 363 pline 1 to 2, arrowhead at start; 364 text above "(2) TLS Error"; 365 text below "(Proxy Cert)"; 367 object 3; 368 pline 1 to 1.3, down, back to 1, arrowhead at end; 369 text seg 2 centre "(inform user of the SecureProxy)"; 371 object 4; 372 pline 1 to 2, arrowhead at end; 373 text above "(3) TLS ClientHello"; 375 object 5; 376 pline 1 to 2, arrowhead at start; 377 text above "(4) ServerHello"; 379 object 6; 380 blank 1 to 2; 382 object 7; 383 block 1 to 2, objects 8 to 15, colour "grey"; 384 text above "HTTP2.0"; 386 object 8; 387 pline 1 to 2, arrowhead at end; 388 text seg 1 centre "(5) stream(X) GET"; 390 object 9; 391 pline 2 to 3, arrowhead at end; 392 text seg 1 above "(6) TLS ClientHello"; 394 object 10; 395 pline 2 to 3, arrowhead at start; 396 text seg 1 above "TLS ServerHello"; 398 object 11; 399 blank 2 to 3; 401 object 12; 402 block 2 to 3, objects 13 to 15, colour "grey"; 403 text seg 1 above "HTTP2.0"; 405 object 13; 406 pline 2 to 3, arrowhead at end; 407 text seg 1 centre "(7) stream(Z) GET"; 409 object 14; 410 pline 2 to 3, arrowhead at start; 411 text seg 1 centre "(8) stream(Z) 200 OK"; 413 object 15; 414 pline 1 to 2, arrowhead at start; 415 text seg 1 centre "(9) stream(X) 200 OK"; 417 4.3. Sequence Diagrams (2) 419 Example: Figure 3 from RFC 4321 421 This example uses (x,y) coordinates to specify points in in plines. 422 For these, the x units are columns and the y units are lines 423 (positive means 'down the diagram'). 425 both x and y may be absolute, e.g. 4.3, or relative, e.g. +1.5). 426 For the first point of a pline, relative means 'relative to the 427 starting point of the previous pline,' for other points in a pline it 428 means 'relative to the last point.' 429 Note that column 1 is drawn in white, i.e. nothing is drawn for it. 430 It's simply used to make a blank area where objects 8 and 9 can place 431 text. For both those objects a pline is used to specify the text's 432 position. 434 Last, the metalanguage allows simple macros, introduced by 'define 435 foo = '. These make it easier to re-use definitions, for example of 436 line types. 438 info; 439 output "rfc4321-fig3.svg", scale 0.9; 441 # Sat, 5 Apr 14 (NZDT) 443 #Figure 3 of RFC 4321 445 define hw = width 110; # Hop width 447 column 1 width 130, colour "white"; # No heading or vertical line 449 column 2 hw; text above "UAC"; 451 column 3 hw; text "P1"; 453 column 4 hw; text "P2"; 455 column 5 hw; text "P3"; 457 column 6 hw; text "UAS"; 459 define tgrey = colour "lightgrey" width 5; # Thick grey 460 define ahe = arrowhead at end; 462 object 1; 463 pline 1.8 464 to 2.3 tgrey, to (2.4,+0), to (2.6,+1.5), to (2.7,+0) ahe, 465 to 3.3 tgrey, to (3.4,+0), to (3.6,+1.5), to (3.7,+0) ahe, 466 to 4.3 tgrey, to (4.4,+0), to (4.6,+1.5), to (4.7,+0) ahe, 467 to 5.3 tgrey, to (5.4,+0), to (5.6,+1.5), to (5.7,+0) ahe, 468 to 6.3 tgrey; 470 object 2; 471 pline (1.8,+10) to 2.3 tgrey; 473 object 3; 474 pline (3.3,+2) 475 to 2.85 tgrey, to (2.7,+0) tgrey, 476 to (2.5,+0), to (2.25,+1.5), to (2.0,+0) ahe; 478 text seg 2 centre "408"; 480 object 4; 481 pline (4.3,+1.5) 482 to 3.9 tgrey, to (3.7,+0) tgrey, 483 to (3.5,+0), to (3.3,+1.5), to (3.1,+0) ahe, 484 to 2.9 tgrey, to (2.7,+0) tgrey, 485 to (2.5,+0), to (2.25,+1.5), to (2.0,+0) ahe; 486 text seg 2 centre "408"; 487 text seg 7 centre "408"; 489 object 5; 490 pline (5.3,+1.5) 491 to 4.9 tgrey, to (4.7,+0) tgrey, 492 to (4.5,+0), to (4.3,+1.5), to (4.1,+0) ahe, 493 to 3.9 tgrey, to (3.7,+0) tgrey, 494 to (3.5,+0), to (3.3,+1.5), to (3.1,+0) ahe, 495 to 2.9 tgrey, to (2.7,+0) tgrey, 496 to (2.5,+0), to (2.25,+1.5), to (2.0,+0) ahe; 497 text seg 2 centre "408"; 498 text seg 7 centre "408"; 499 text seg 12 centre "408"; 501 object 6; 502 pline (6.3,+1.5) 503 to 5.9 tgrey, to (5.7,+0) tgrey, 504 to (5.5,+0), to (5.3,+1.5), to (5.1,+0) ahe; 505 to 4.9 tgrey, to (4.7,+0) tgrey, 506 to (4.5,+0), to (4.3,+1.5), to (4.1,+0) ahe; 507 to 3.9 tgrey, to (3.7,+0) tgrey, 508 to (3.5,+0), to (3.3,+1.5), to (3.1,+0) ahe; 509 to 2.9 tgrey, to (2.7,+0) tgrey, 510 to (2.5,+0), to (2.25,+1.5), to (2.0,+0) ahe; 511 text seg 2 centre "408"; 512 text seg 7 centre "408"; 513 text seg 12 centre "408"; 514 text seg 17 centre "408"; 516 object 7: 517 pline (1.63,4.1) to (1.73,+0); 519 object 8; 520 pline (1.68,4.1) to (+0,14) arrowhead at end; 521 text centre "64*T1"; 523 object 9; 524 pline (1.2,13.1) to (1.5,+0) colour "white"; 525 text centre "(timeout)"; 527 5. IANA Considerations 529 This document does not create a new registry nor does it register any 530 values in existing registries; no IANA action is required. 532 6. Acknowledgements 534 Thanks to the Design Team members for their helpful comments and 535 suggestions for SVG 1.2 RFC. 537 7. Revision History [RFC Editor please delete] 539 version -04, 30 Apr 14: 540 Fixed typos, used full references for two of the w3c refs - each 541 had an author name using UTF8 characters. 542 Moved the Elements and Attributes appendix up earlier to make it 543 sub-section 2.1. 544 Disclaimer added to the Meta-languages section. 546 version -03, 14 Apr 14: 547 Added two more example diagrams; a simple packet layout, and a 548 diagram that uses lots of diagonal lines. 550 version -02, 12 Feb 14: 551 Added metalanguage example to make time-sequence drawings. 553 version -01, 11 Feb 14: 554 Allow links to 'long-term stable URIs' 555 Link URIs must be ASCII only 556 Need for tools to check SVG 1.2 RFC compatibility and to strip 557 'unnecessary' attributes explicitly stated. 558 Statement that drawings can't be normative removed; Postscript- 559 only RFCs already exist. 560 Added most attributes and elements to the Appendix. 562 version -00, 29 Jan 14: 563 Initial version, using content from Nevil's 564 emails to the Design Team. 566 8. References 568 8.1. Normative References 570 [RFC6949] Flanagan, H. and N. Brownlee, "RFC Series Format 571 Requirements and Future Development", RFC 6949, May 2013. 573 [W3C.REC-SVGTiny12-20081222] 574 Andersson, O., Berjon, R., Dahlstrom, E., Emmons, A., 575 Ferraiolo, J., Grasso, A., Hardy, V., Hayman, S., Jackson, 576 D., Lilley, C., McCormack, C., Neumann, A., Northway, C., 577 Quint, A., Ramani, N., Schepers, D., and A. Shellshear, 578 "Scalable Vector Graphics (SVG) Tiny 1.2 Specification", 579 World Wide Web Consortium Recommendation REC- 580 SVGTiny12-20081222, December 2008, 581 . 583 [W3C.REC-CSS2-20110607] 584 Bos, B., Celik, T., Hickson, I., and H. Lie, "Cascading 585 Style Sheets Level 2 Revision 1 (CSS 2.1) Specification", 586 World Wide Web Consortium Recommendation REC- 587 CSS2-20110607, June 2011, 588 . 590 8.2. Informative References 592 [W3C.REC-SVG11-20110816] 593 Dahlstrom, E., Dengler, P., Grasso, A., Lilley, C., 594 McCormack, C., Schepers, D., Watt, J., Ferraiolo, J., 595 Fujisawa, J., and D. Jackson, "Scalable Vector Graphics 596 (SVG) 1.1 (Second Edition)", World Wide Web Consortium 597 Recommendation REC-SVG11-20110816, August 2011, 598 . 600 Authors' Addresses 602 Nevil Brownlee 603 The University of Auckland 605 Email: n.brownlee@auckland.ac.nz 607 Internet Architecture Board 609 Email: iab@iab.org