idnits 2.17.1 draft-flanagan-rfc-css-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 abstract seems to contain references ([I-D.hildebrand-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 (September 3, 2015) is 3155 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 5741 (Obsoleted by RFC 7841) == Outdated reference: A later version (-08) exists of draft-flanagan-rfc-framework-05 Summary: 2 errors (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group H. Flanagan 3 Internet-Draft RFC Editor 4 Intended status: Informational September 3, 2015 5 Expires: March 6, 2016 7 CSS Requirements for RFCs 8 draft-flanagan-rfc-css-04 10 Abstract 12 The HTML format for RFCs, described in [I-D.hildebrand-html-rfc] 13 assigns style guidance to an RFC Editor-defined Cascading Style Sheet 14 (CSS). The embedded, default CSS as included by the RFC Editor is 15 expected to take into account accessibility needs and be built along 16 a 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-hildebrand-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 March 6, 2016. 41 Copyright Notice 43 Copyright (c) 2015 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 . . . . . . . . . . . . . . . . . . . 5 72 7.3.2. .art-logo . . . . . . . . . . . . . . . . . . . . . . 6 73 7.4. .closeParen . . . . . . . . . . . . . . . . . . . . . . . 6 74 7.5. .comma . . . . . . . . . . . . . . . . . . . . . . . . . 6 75 7.6. .cref . . . . . . . . . . . . . . . . . . . . . . . . . . 6 76 7.7. .crefAnchor . . . . . . . . . . . . . . . . . . . . . . . 6 77 7.8. .crefSource . . . . . . . . . . . . . . . . . . . . . . . 6 78 7.9. .dlCompact . . . . . . . . . . . . . . . . . . . . . . . 6 79 7.10. .dlHanging . . . . . . . . . . . . . . . . . . . . . . . 6 80 7.11. .dlParallel . . . . . . . . . . . . . . . . . . . . . . . 6 81 7.12. .docInfo . . . . . . . . . . . . . . . . . . . . . . . . 7 82 7.13. .eref . . . . . . . . . . . . . . . . . . . . . . . . . . 7 83 7.14. .finalized . . . . . . . . . . . . . . . . . . . . . . . 7 84 7.15. .fullStop . . . . . . . . . . . . . . . . . . . . . . . . 7 85 7.16. .note . . . . . . . . . . . . . . . . . . . . . . . . . . 7 86 7.16.1. .rfcEditorRemove . . . . . . . . . . . . . . . . . . 7 87 7.17. .olCompact . . . . . . . . . . . . . . . . . . . . . . . 7 88 7.18. .olPercent . . . . . . . . . . . . . . . . . . . . . . . 7 89 7.19. .openParen . . . . . . . . . . . . . . . . . . . . . . . 7 90 7.20. .pilcrow . . . . . . . . . . . . . . . . . . . . . . . . 8 91 7.21. .relref . . . . . . . . . . . . . . . . . . . . . . . . . 8 92 7.22. .rendered . . . . . . . . . . . . . . . . . . . . . . . . 8 93 7.23. .sourcecode . . . . . . . . . . . . . . . . . . . . . . . 8 94 7.24. .toc . . . . . . . . . . . . . . . . . . . . . . . . . . 8 95 7.25. .ulCompact . . . . . . . . . . . . . . . . . . . . . . . 8 96 7.26. .ulEmpty . . . . . . . . . . . . . . . . . . . . . . . . 8 97 7.27. .url . . . . . . . . . . . . . . . . . . . . . . . . . . 8 98 7.28. .xref . . . . . . . . . . . . . . . . . . . . . . . . . . 8 99 8. Security Considerations . . . . . . . . . . . . . . . . . . . 9 100 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 101 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 9 102 11. Draft Change Log . . . . . . . . . . . . . . . . . . . . . . 9 103 11.1. Changes from -02 to -03 . . . . . . . . . . . . . . . . 9 104 11.2. Changes from -01 to -02 . . . . . . . . . . . . . . . . 9 105 11.3. Changes from -00 to -01 . . . . . . . . . . . . . . . . 9 106 12. Normative References . . . . . . . . . . . . . . . . . . . . 10 107 Appendix A. List of classes . . . . . . . . . . . . . . . . . . 10 108 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 14 110 1. Introduction 112 The HTML format for RFCs, described in [I-D.hildebrand-html-rfc] 113 assigns style guidance to an RFC Editor-defined Cascading Style Sheet 114 (CSS). This CSS will be embedded in the published HTML, and may be 115 overridden by a locally defined CSS as desired. The embedded, 116 default CSS as included by the RFC Editor is expected to take into 117 account accessibility needs and be built along a responsive design 118 model. 120 This document describes the requirements for the default CSS used by 121 the RFC Editor. Unless called out otherwise, any styling provided 122 for these classes must not change the presentation of the content in 123 any visible way. Many of these classes are provided to mark the 124 elements semantically: elements using them should simply inherit 125 their surrounding styling. Exceptions are called out below. A class 126 is identified for Internet Drafts, such that certain features found 127 only in I-Ds may be made distinct in some fashion within those 128 drafts. The requirements will only be applied to HTML documents 129 published by the RFC Editor as per [I-D.flanagan-rfc-framework]. 131 The details described in this document are expected to change based 132 on experience gained in implementing the RFC production center's 133 toolset. Revised documents will be published capturing those changes 134 as the toolset is completed. Other implementers must not expect 135 those changes to remain backwards-compatible with the details 136 described in this document. 138 2. Design Goal 140 RFCs must be adaptable to a wide variety of devices and displays, 141 accessible to assisted readers, and printable. 143 3. General Requirements 145 o Support the display of the semantic HTML described in 146 [I-D.hildebrand-html-rfc]. 148 o Follow best practice for accessibility, as defined by the W3C's 149 "Best Practices for Authoring HTML" [HTMLBP]. 151 o Follow best practice for mobile devices, as defined by the W3C's 152 "Best Practices for Authoring HTML." 154 o Allow for a broad range of internationalized scripts. 156 4. Page Layout 158 4.1. Title Page Header 160 The document header must be at the top of the document and include 161 all information described in the "Style Guide" and "RFC Streams, 162 Headers, and Boilerplates" [RFC7322] [RFC5741] 164 4.2. Body 166 The body of the document must conform to the following: 168 o Examples and code blocks must be in a fixed-width font 170 o ASCII art must be in a fixed-width font 172 o Reflow the text as the screen gets smaller and limit max width 174 o Block quotes must be indented 176 o Tables must allow for distinct header rows 178 o Paragraphs should include a hover-over paragraph identifier 180 All anchor tags and URLs should be clearly distinguished as links, 181 for example through the use of color and/or text decoration, 182 following appropriate accessibility standards. 184 4.3. Font Choices 186 o Default to a sans-serif font family with broad Unicode support for 187 web browser viewing. 189 o Default to a serif font family with broad Unicode support for 190 printing. 192 o A fixed-width font must be used for code and artwork-tagged 193 sections. 195 o All fonts should be publicly licensed and supported by all major 196 web browsers. 198 5. Printing 200 The CSS must include support for a printer-friendly output. The 201 print rules should be a part of the embedded style sheet; consumers 202 of an RFC may develop their own print-specific style sheet as 203 desired. 205 6. Lists 207 Lists should provide ample whitespace between list elements for 208 legibility unless a 'compact' class is specified (e.g., .dlCompact, 209 .ulCompact, .olCompact). 211 7. CSS Classes and Attributes 213 This section describes the CSS classes that result in changes to the 214 presentation of the contents of a document. A full list of available 215 classes, not including basic selectors, are included in "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; inherit the current styling in effect. Note that 242 such images are not currently allowed in RFCs. 244 7.4. .closeParen 246 Close the whitespace before a closing parenthesis after a 247 block by moving the text within the block to the right and moving the 248 closing parenthesis to the left.. 250 7.5. .comma 252 Close the whitespace before a comma after a block by moving 253 the text within the block to the left and moving the comma to the 254 right. 256 7.6. .cref 258 A comment within an I-D; should be visually distinct. 260 For I-Ds only; not for RFCs. 262 7.7. .crefAnchor 264 A comment within an I-D; should be visually distinct. 266 For I-Ds only; not for RFCs. 268 7.8. .crefSource 270 A comment within an I-D; should be visually distinct. 272 For I-Ds only; not for RFCs. 274 7.9. .dlCompact 276 Use less spacing on a definition list than the default. 278 7.10. .dlHanging 280 Use the standard hanging indent for a definition list; indent terms. 282 7.11. .dlParallel 284 Do not use the standard hanging indent for a definition list; align 285 terms and definitions along left side. 287 7.12. .docInfo 289 Hide from visible presentation of content. 291 7.13. .eref 293 Standard link formatting (underlined, change in color). 295 7.14. .finalized 297 Hide from visible presentation of content. 299 7.15. .fullStop 301 Close the whitespace before a period or full stop after a 302 block by moving the text within the block to the left and moving the 303 period to the right. 305 7.16. .note 307 Notes should be emphasized and distinct from normal paragraph text. 309 7.16.1. .rfcEditorRemove 311 An RFC Editor note may be added after the standard boilerplage. It 312 should be visually distinct to highlight final removal of the note by 313 the RFC Editor. 315 7.17. .olCompact 317 Use less spacing on a numbered list than the default. 319 7.18. .olPercent 321 If the style attribute from the source XML contains a percent sign, a 322 particular style setting will be required to make this setting behave 323 like an HTML ordered list. 325 7.19. .openParen 327 Close the whitespace after an opening parenthesis and before a 328 block by moving the text within the block to the left and moving the 329 opening parenthesis to the right. 331 7.20. .pilcrow 333 Pilcrows, when used as described in draft-hildebrand-html-rfc, should 334 appear at the end of the paragraph, artwork, or sourcecode segment. 335 They should not appear until moused-over. They should not show when 336 printed, and should not be selected when copied with a copy/paste 337 function. 339 7.21. .relref 341 Should be clearly distinguished as links. 343 7.22. .rendered 345 Hide from visible presentation of content. 347 7.23. .sourcecode 349 Code examples or components should be in a fixed-width font if the 350 human language used has an available fixed-width font option, and 351 should be visually distinct. If no fixed-width font is available, 352 use the default font for that human language. 354 7.24. .toc 356 The table of contents should be clearly distinguished using an 357 indented, ordered list with the list style set to 'none', allowing 358 for hyperlinked, in-line dotted number notation (e.g., 1., 1.1., 359 1.1.1.). 361 7.25. .ulCompact 363 Use less spacing on a bulleted list than the default. 365 7.26. .ulEmpty 367 Indent from the margin of the previous paragraph. 369 7.27. .url 371 Should be clearly distinguished as links. 373 7.28. .xref 375 Should be clearly distinguished as links. 377 8. Security Considerations 379 Security vulnerabilities can be introduced through the CSS. How much 380 detail do we need to go into here to say "don't do foolish things and 381 introduce security issues?" 383 9. IANA Considerations 385 This draft contains no action for IANA 387 10. Acknowledgements 389 With many thanks to the RFC Format Design Team for their efforts in 390 making this transition successful: Nevil Brownlee (ISE), Tony Hansen, 391 Joe Hildebrand, Paul Hoffman, Ted Lemon, Julian Reschke, Adam Roach, 392 Alice Russo, Robert Sparks (Tools Team liaison), and Dave Thaler. 394 Additional thanks to Arlen Johnson of Spherical Cow Group, LLC, for 395 his assistance in clarifying the requirements in more CSS designer- 396 friendly language. 398 11. Draft Change Log 400 To be removed before publication 402 11.1. Changes from -02 to -03 404 Moved Appendix to correct location; fixed typos; moved lang-* to 405 Appendix, 407 11.2. Changes from -01 to -02 409 Adjusted class names where possible to a common naming pattern 410 (CamelCase). 412 Added alignCenter, alignRight, dlHanging, closedParen, openParen, 413 ulEmpty 415 11.3. Changes from -00 to -01 417 Moved full list of classes to Appendix; only discussed classes that 418 will have visible changes to the text in the body 420 Introduction: text regarding expected future changes added. 422 Body: added text regarding anchors and tags; this text also applied 423 to .relref, .url, .xref 424 Artwork: clarified non-floating behavior of artwork 426 List behavior: clarified the behavior of .ulCompact, .olCompact, and 427 .dlCompact as distinct from default list behavior; clarified behavior 428 of .dlparallel 430 Note: clarified text around behavior of notes 432 RFC: added additional class to allow the CSS to distinguish between 433 RFCs and Internet Drafts if desired 435 TOC: clarified text around behavior of table of contents 437 12. Normative References 439 [HTMLBP] W3C, "Best Practices for Authoring HTML Current Status", 440 n.d., . 442 [RFC5741] Daigle, L., Ed., Kolkman, O., Ed., and IAB, "RFC Streams, 443 Headers, and Boilerplates", RFC 5741, 444 DOI 10.17487/RFC5741, December 2009, 445 . 447 [RFC7322] Flanagan, H. and S. Ginoza, "RFC Style Guide", RFC 7322, 448 DOI 10.17487/RFC7322, September 2014, 449 . 451 [I-D.hildebrand-html-rfc] 452 Hildebrand, J. and P. Hoffman, "HyperText Markup Language 453 Request For Comments Format", draft-hildebrand-html-rfc-10 454 (work in progress), August 2015. 456 [I-D.flanagan-rfc-framework] 457 Flanagan, H., "RFC Format Framework", draft-flanagan-rfc- 458 framework-05 (work in progress), August 2015. 460 Appendix A. List of classes 462 This section lists all the CSS classes. Except for those also listed 463 above in section 7, none of these result in changes to the content of 464 a document. 466 o .adr 468 o .alignCenter 470 o .alignRight 471 o .annotation 473 o .artwork 475 .art-ascii-art 477 .art-logo 479 .art-svg 481 o .ascii 483 o .author 485 o .authors 487 o .bcp14 489 o .city 491 o .closeParen 493 o .comma 495 o .compact 497 o .country-name 499 o .cref 501 o .crefAnchor 503 o .crefSource 505 o .dlCompact 507 o .dlHanging 509 o .dlParallel 511 o .docInfo 513 o .email 515 o .eref 517 o .finalized 518 o .fn 520 o .fullStop 522 o .index 524 o .indexChar 526 o .indexIndex 528 o .indexItem 530 o .indexPrimary 532 o .indexSubItem 534 o .initial 536 o .iref 538 o .irefItem 540 o .irefRefs 542 o .irefSubItem 544 o .label 546 o .locality 548 o .nameRole 550 o .note 552 .rfcEditorRemove 554 o .olCompact 556 o .olPercent 558 o .openParen 560 o .org 562 o .organization 564 o .pilcrow 565 o .postal-code 567 o .published 569 o .refAuthor 571 o .refContent 573 o .refDate 575 o .refTitle 577 o .reference 579 o .referenceGroup 581 o .region 583 o .relref 585 o .rendered 587 o .RFC 589 o .rfcEditorRemove 591 o .role 593 o .selfRef 595 o .series 597 o .seriesInfo 599 o .sourcecode 601 .lang-* 603 o .street-address 605 o .status 607 o .street-address 609 o .surname 611 o .tel 612 o .toc 614 o .type 616 o .ulCompact 618 o .url 620 o .workgroup 622 o .xref 624 o .vcard 626 Author's Address 628 Heather Flanagan 629 RFC Editor 631 Email: rse@rfc-editor.org 632 URI: http://orcid.org/0000-0002-2647-2220