idnits 2.17.1 draft-iab-rfc-css-01.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 abstract seems to contain references ([I-D.iab-html-RFC]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 4, 2016) is 2815 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 5741 (Obsoleted by RFC 7841) Summary: 2 errors (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Architecture Board H. Flanagan 3 Internet-Draft RFC Editor 4 Intended status: Informational July 4, 2016 5 Expires: January 5, 2017 7 CSS Requirements for RFCs 8 draft-iab-rfc-css-01 10 Abstract 12 The HTML format for RFCs, described in [I-D.iab-html-rfc] assigns 13 style guidance to an RFC Editor-defined Cascading Style Sheet (CSS). 14 The embedded, default CSS as included by the RFC Editor is expected 15 to take into account accessibility needs and be built along a 16 responsive design model. This document describes the requirements 17 for the default CSS used by the RFC Editor. The class names are 18 based on the classes defined in draft-iab-html-rfc. 20 Discussion of this draft takes place on the rfc-interest mailing list 21 (rfc-interest@rfc-editor.org), which has its home page at 22 https://www.rfc-editor.org/mailman/listinfo/rfc-interest. 24 Status of This Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at http://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on January 5, 2017. 41 Copyright Notice 43 Copyright (c) 2016 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents 48 (http://trustee.ietf.org/license-info) in effect on the date of 49 publication of this document. Please review these documents 50 carefully, as they describe your rights and restrictions with respect 51 to this document. Code Components extracted from this document must 52 include Simplified BSD License text as described in Section 4.e of 53 the Trust Legal Provisions and are provided without warranty as 54 described in the Simplified BSD License. 56 Table of Contents 58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 59 2. Design Goal . . . . . . . . . . . . . . . . . . . . . . . . . 3 60 3. General Requirements . . . . . . . . . . . . . . . . . . . . 4 61 4. Page Layout . . . . . . . . . . . . . . . . . . . . . . . . . 4 62 4.1. Title Page Header . . . . . . . . . . . . . . . . . . . . 4 63 4.2. Body . . . . . . . . . . . . . . . . . . . . . . . . . . 4 64 4.3. Font Choices . . . . . . . . . . . . . . . . . . . . . . 4 65 5. Printing . . . . . . . . . . . . . . . . . . . . . . . . . . 5 66 6. Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 67 7. CSS Classes and Attributes . . . . . . . . . . . . . . . . . 5 68 7.1. .alignCenter . . . . . . . . . . . . . . . . . . . . . . 5 69 7.2. .alignRight . . . . . . . . . . . . . . . . . . . . . . . 5 70 7.3. .artwork . . . . . . . . . . . . . . . . . . . . . . . . 5 71 7.3.1. .art-ascii-art . . . . . . . . . . . . . . . . . . . 6 72 7.3.2. .art-logo . . . . . . . . . . . . . . . . . . . . . . 6 73 7.4. .cref . . . . . . . . . . . . . . . . . . . . . . . . . . 6 74 7.5. .crefAnchor . . . . . . . . . . . . . . . . . . . . . . . 6 75 7.6. .crefSource . . . . . . . . . . . . . . . . . . . . . . . 6 76 7.7. .dlCompact . . . . . . . . . . . . . . . . . . . . . . . 6 77 7.8. .dlHanging . . . . . . . . . . . . . . . . . . . . . . . 6 78 7.9. .dlParallel . . . . . . . . . . . . . . . . . . . . . . . 6 79 7.10. .docInfo . . . . . . . . . . . . . . . . . . . . . . . . 6 80 7.11. .eref . . . . . . . . . . . . . . . . . . . . . . . . . . 7 81 7.12. .finalized . . . . . . . . . . . . . . . . . . . . . . . 7 82 7.13. .note . . . . . . . . . . . . . . . . . . . . . . . . . . 7 83 7.13.1. .rfcEditorRemove . . . . . . . . . . . . . . . . . . 7 84 7.14. .olCompact . . . . . . . . . . . . . . . . . . . . . . . 7 85 7.15. .olPercent . . . . . . . . . . . . . . . . . . . . . . . 7 86 7.16. .pilcrow . . . . . . . . . . . . . . . . . . . . . . . . 7 87 7.17. .relref . . . . . . . . . . . . . . . . . . . . . . . . . 7 88 7.18. .rendered . . . . . . . . . . . . . . . . . . . . . . . . 7 89 7.19. .sourcecode . . . . . . . . . . . . . . . . . . . . . . . 8 90 7.20. .toc . . . . . . . . . . . . . . . . . . . . . . . . . . 8 91 7.21. .type . . . . . . . . . . . . . . . . . . . . . . . . . . 8 92 7.22. .ulCompact . . . . . . . . . . . . . . . . . . . . . . . 8 93 7.23. .ulEmpty . . . . . . . . . . . . . . . . . . . . . . . . 8 94 7.24. .url . . . . . . . . . . . . . . . . . . . . . . . . . . 8 95 7.25. .xref . . . . . . . . . . . . . . . . . . . . . . . . . . 8 96 8. Security Considerations . . . . . . . . . . . . . . . . . . . 8 97 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 98 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 9 99 11. Draft Change Log . . . . . . . . . . . . . . . . . . . . . . 9 100 11.1. Changes from draft-iab-rfc-css-00 to -01 . . . . . . . . 9 101 11.2. Changes from draft-flanagan-rfc-css to draft-iab-rfc-css 9 102 11.3. Changes from -02 to -03 . . . . . . . . . . . . . . . . 9 103 11.4. Changes from -01 to -02 . . . . . . . . . . . . . . . . 9 104 11.5. Changes from -00 to -01 . . . . . . . . . . . . . . . . 9 105 12. Normative References . . . . . . . . . . . . . . . . . . . . 10 106 Appendix A. List of classes . . . . . . . . . . . . . . . . . . 10 107 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 14 109 1. Introduction 111 The HTML format for RFCs, described in [I-D.iab-html-rfc] assigns 112 style guidance to an RFC Editor-defined Cascading Style Sheet (CSS). 113 This CSS will be embedded in the published HTML, and may be 114 overridden by a locally defined CSS as desired. The embedded, 115 default CSS as included by the RFC Editor is expected to take into 116 account accessibility needs and be built along a responsive design 117 model. 119 This document describes the requirements for the default CSS used by 120 the RFC Editor. Unless called out otherwise, any styling provided 121 for these classes must not alter the natural language content in any 122 visible way. Many of these classes are provided to mark the elements 123 semantically: elements using them should simply inherit their 124 surrounding styling. Exceptions are called out below. A class is 125 identified for Internet Drafts, such that certain features found only 126 in I-Ds may be made distinct in some fashion within those drafts. 127 The requirements will only be applied to HTML documents published by 128 the RFC Editor as per [I-D.iab-rfc-framework]. 130 The details described in this document are expected to change based 131 on experience gained in implementing the RFC production center's 132 toolset. Revised documents will be published capturing those changes 133 as the toolset is completed. Other implementers must not expect 134 those changes to remain backwards-compatible with the details 135 described in this document. 137 2. Design Goal 139 RFCs must be adaptable to a wide variety of devices and displays, 140 accessible to assisted readers, and printable. 142 3. General Requirements 144 o Support the display of the semantic HTML described in 145 [I-D.iab-html-rfc]. 147 o Follow best practice for accessibility, as defined by the W3C's 148 "Best Practices for Authoring HTML" [HTMLBP]. 150 o Follow best practice for mobile devices, as defined by the W3C's 151 "Best Practices for Authoring HTML." 153 o Allow for a broad range of internationalized scripts. 155 4. Page Layout 157 4.1. Title Page Header 159 The document header must be at the top of the document and include 160 all information described in the "Style Guide" and "RFC Streams, 161 Headers, and Boilerplates" [RFC7322] [RFC5741] 163 4.2. Body 165 The body of the document must conform to the following: 167 o Examples and code blocks must be in a fixed-width font 169 o ASCII art must be in a fixed-width font 171 o Reflow the text as the screen gets smaller and limit max width 173 o Block quotes must be indented 175 o Tables must allow for distinct header rows 177 o Paragraphs should include a hover-over paragraph identifier 179 All anchor tags and URLs should be clearly distinguished as links, 180 for example through the use of color and/or text decoration, 181 following appropriate accessibility standards. 183 4.3. Font Choices 185 o Default to a sans-serif font family with broad Unicode support for 186 web browser viewing. 188 o Default to a serif font family with broad Unicode support for 189 printing. 191 o A fixed-width font must be used for code and artwork-tagged 192 sections. 194 o All fonts should be publicly licensed and supported by all major 195 web browsers. 197 5. Printing 199 The CSS must include support for a printer-friendly output. The 200 print rules should be a part of the embedded style sheet; consumers 201 of an RFC may develop their own print-specific style sheet as 202 desired. 204 6. Lists 206 Lists should provide ample whitespace between list elements for 207 legibility unless a 'compact' class is specified (e.g., .dlCompact, 208 .ulCompact, .olCompact). 210 7. CSS Classes and Attributes 212 This section describes the CSS classes that result in specific 213 changes to the natural language content of a document. A full list 214 of available classes, not including basic selectors, are included in 215 "Appendix A". 217 7.1. .alignCenter 219 To be used with '.artwork' to indicate the figure should align in the 220 center of the page flow. 222 7.2. .alignRight 224 To be used with '.artwork' to indicate the figure should align on the 225 right of the page flow. 227 7.3. .artwork 229 These classes will mostly be styled as part of .artwork. Specific 230 classes may include '.art-ascii-art' and '.art-svg'. Artwork will be 231 held in its own block of space, centered in the page flow, and will 232 not float. Images should have a max width of 100% so views will 233 scale properly across a variety of screens and devices. 235 7.3.1. .art-ascii-art 237 Must use a mono-spaced font. 239 7.3.2. .art-logo 241 No visible changes to the natural language content; keep in default 242 style. Note that such images are not currently allowed in RFCs. 244 7.4. .cref 246 A comment within an I-D; should be visually distinct. 248 For I-Ds only; not for RFCs. 250 7.5. .crefAnchor 252 A comment within an I-D; should be visually distinct. 254 For I-Ds only; not for RFCs. 256 7.6. .crefSource 258 A comment within an I-D; should be visually distinct. 260 For I-Ds only; not for RFCs. 262 7.7. .dlCompact 264 Use less spacing on a definition list than the default. 266 7.8. .dlHanging 268 Use the standard hanging indent for a definition list; indent terms. 270 7.9. .dlParallel 272 Do not use the standard hanging indent for a definition list; align 273 terms and definitions along left side. 275 7.10. .docInfo 277 Hide from visible content. 279 7.11. .eref 281 Standard link formatting (underlined, change in color). 283 7.12. .finalized 285 Hide from visible content. 287 7.13. .note 289 Notes should be emphasized and distinct from normal paragraph text. 291 7.13.1. .rfcEditorRemove 293 An RFC Editor note may be added after the standard boilerplage. It 294 should be visually distinct to highlight final removal of the note by 295 the RFC Editor. 297 7.14. .olCompact 299 Use less spacing on a numbered list than the default. 301 7.15. .olPercent 303 If the style attribute from the source XML contains a percent sign, a 304 particular style setting will be required to make this setting behave 305 like an HTML ordered list. 307 7.16. .pilcrow 309 Pilcrows, when used as described in draft-iab-html-rfc, should appear 310 at the end of the paragraph, artwork, or sourcecode segment. They 311 should not appear until moused-over. They should not show when 312 printed, and should not be selected when copied with a copy/paste 313 function. 315 7.17. .relref 317 Should be clearly distinguished as links. 319 7.18. .rendered 321 Hide from visible content. 323 7.19. .sourcecode 325 Code examples or components should be in a fixed-width font if the 326 human language used has an available fixed-width font option, and 327 should be visually distinct. If no fixed-width font is available, 328 use the default font for that human language. 330 7.20. .toc 332 The table of contents should be clearly distinguished using an 333 indented, ordered list with the list style set to 'none', allowing 334 for hyperlinked, in-line dotted number notation (e.g., 1., 1.1., 335 1.1.1.). 337 7.21. .type 339 No visible changes to the natural language content; keep in default 340 style. 342 7.22. .ulCompact 344 Use less spacing on a bulleted list than the default. 346 7.23. .ulEmpty 348 Indent from the margin of the previous paragraph. 350 7.24. .url 352 Should be clearly distinguished as links. 354 7.25. .xref 356 Should be clearly distinguished as links. 358 8. Security Considerations 360 Security vulnerabilities can be introduced through the CSS. How much 361 detail do we need to go into here to say "don't do foolish things and 362 introduce security issues?" 364 9. IANA Considerations 366 This draft contains no action for IANA 368 10. Acknowledgements 370 With many thanks to the RFC Format Design Team for their efforts in 371 making this transition successful: Nevil Brownlee (ISE), Tony Hansen, 372 Joe Hildebrand, Paul Hoffman, Ted Lemon, Julian Reschke, Adam Roach, 373 Alice Russo, Robert Sparks (Tools Team liaison), and Dave Thaler. 375 Additional thanks to Arlen Johnson of Spherical Cow Group, LLC, for 376 his assistance in clarifying the requirements in more CSS designer- 377 friendly language. 379 11. Draft Change Log 381 To be removed before publication 383 11.1. Changes from draft-iab-rfc-css-00 to -01 385 added .refInstance, .ulEmpty, .ears, .left, .right, .center as per 386 HTML draft 388 removed .comma, .closeParen, .openParen, .fullStop, .referenceGroup 389 as per HTML draft 391 11.2. Changes from draft-flanagan-rfc-css to draft-iab-rfc-css 393 revised draft name; no major changes 395 11.3. Changes from -02 to -03 397 Moved Appendix to correct location; fixed typos; moved lang-* to 398 Appendix, 400 11.4. Changes from -01 to -02 402 Adjusted class names where possible to a common naming pattern 403 (CamelCase). 405 Added alignCenter, alignRight, dlHanging, ulEmpty 407 11.5. Changes from -00 to -01 409 Moved full list of classes to Appendix; only discussed classes that 410 will have visible changes to the text in the body 412 Introduction: text regarding expected future changes added. 414 Body: added text regarding anchors and tags; this text also applied 415 to .relref, .url, .xref 416 Artwork: clarified non-floating behavior of artwork 418 List behavior: clarified the behavior of .ulCompact, .olCompact, and 419 .dlCompact as distinct from default list behavior; clarified behavior 420 of .dlparallel 422 Note: clarified text around behavior of notes 424 RFC: added additional class to allow the CSS to distinguish between 425 RFCs and Internet Drafts if desired 427 TOC: clarified text around behavior of table of contents 429 12. Normative References 431 [HTMLBP] W3C, "Best Practices for Authoring HTML Current Status", 432 n.d., . 434 [RFC5741] Daigle, L., Ed., Kolkman, O., Ed., and IAB, "RFC Streams, 435 Headers, and Boilerplates", RFC 5741, 436 DOI 10.17487/RFC5741, December 2009, 437 . 439 [RFC7322] Flanagan, H. and S. Ginoza, "RFC Style Guide", RFC 7322, 440 DOI 10.17487/RFC7322, September 2014, 441 . 443 [I-D.iab-html-rfc] 444 Hildebrand, J. and P. Hoffman, "HyperText Markup Language 445 Request For Comments Format", draft-iab-html-rfc-03 (work 446 in progress), June 2016. 448 [I-D.iab-rfc-framework] 449 Flanagan, H., "RFC Format Framework", draft-iab-rfc- 450 framework-06 (work in progress), June 2016. 452 Appendix A. List of classes 454 This section lists all the CSS classes. Except for those also listed 455 above in section 7, none of these result in specific changes to the 456 natural language content of a document. 458 o .adr 460 o .alignCenter 462 o .alignRight 463 o .annotation 465 o .artwork 467 .art-ascii-art 469 .art-logo 471 .art-svg 473 o .ascii 475 o .author 477 o .authors 479 o .bcp14 481 o .center 483 o .city 485 o .compact 487 o .country-name 489 o .cref 491 o .crefAnchor 493 o .crefSource 495 o .dlCompact 497 o .dlHanging 499 o .dlParallel 501 o .docInfo 503 o .ears 505 o .email 507 o .eref 509 o .finalized 510 o .fn 512 o .index 514 o .indexChar 516 o .indexIndex 518 o .indexItem 520 o .indexPrimary 522 o .indexSubItem 524 o .initial 526 o .iref 528 o .irefItem 530 o .irefRefs 532 o .irefSubItem 534 o .label 536 o .left 538 o .locality 540 o .nameRole 542 o .note 544 .rfcEditorRemove 546 o .olCompact 548 o .olPercent 550 o .org 552 o .organization 554 o .pilcrow 556 o .postal-code 557 o .published 559 o .refContent 561 o .refDate 563 o .refInstance 565 o .refTitle 567 o .reference 569 o .region 571 o .relref 573 o .rendered 575 o .RFC 577 o .rfcEditorRemove 579 o .right 581 o .role 583 o .selfRef 585 o .series 587 o .seriesInfo 589 o .sourcecode 591 .lang-* 593 o .street-address 595 o .status 597 o .street-address 599 o .surname 601 o .tel 603 o .toc 604 o .type 606 o .ulCompact 608 o .ulEmpty 610 o .url 612 o .workgroup 614 o .xref 616 o .vcard 618 Author's Address 620 Heather Flanagan 621 RFC Editor 623 Email: rse@rfc-editor.org 624 URI: http://orcid.org/0000-0002-2647-2220