| Internet Architecture Board | H. Flanagan |
| Internet-Draft | RFC Editor |
| Intended status: Informational | July 4, 2016 |
| Expires: January 5, 2017 |
CSS Requirements for RFCs
draft-iab-rfc-css-01
The HTML format for RFCs, described in [I-D.iab-html-rfc] assigns style guidance to an RFC Editor-defined Cascading Style Sheet (CSS). The embedded, default CSS as included by the RFC Editor is expected to take into account accessibility needs and be built along a responsive design model. This document describes the requirements for the default CSS used by the RFC Editor. The class names are based on the classes defined in draft-iab-html-rfc.
Discussion of this draft takes place on the rfc-interest mailing list (rfc-interest@rfc-editor.org), which has its home page at https://www.rfc-editor.org/mailman/listinfo/rfc-interest.
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 http://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 January 5, 2017.
Copyright (c) 2016 IETF Trust and the persons identified as the document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.
The HTML format for RFCs, described in [I-D.iab-html-rfc] assigns style guidance to an RFC Editor-defined Cascading Style Sheet (CSS). This CSS will be embedded in the published HTML, and may be overridden by a locally defined CSS as desired. The embedded, default CSS as included by the RFC Editor is expected to take into account accessibility needs and be built along a responsive design model.
This document describes the requirements for the default CSS used by the RFC Editor. Unless called out otherwise, any styling provided for these classes must not alter the natural language content in any visible way. Many of these classes are provided to mark the elements semantically: elements using them should simply inherit their surrounding styling. Exceptions are called out below. A class is identified for Internet Drafts, such that certain features found only in I-Ds may be made distinct in some fashion within those drafts. The requirements will only be applied to HTML documents published by the RFC Editor as per [I-D.iab-rfc-framework].
The details described in this document are expected to change based on experience gained in implementing the RFC production center's toolset. Revised documents will be published capturing those changes as the toolset is completed. Other implementers must not expect those changes to remain backwards-compatible with the details described in this document.
RFCs must be adaptable to a wide variety of devices and displays, accessible to assisted readers, and printable.
The document header must be at the top of the document and include all information described in the "Style Guide" and "RFC Streams, Headers, and Boilerplates" [RFC7322] [RFC5741]
The body of the document must conform to the following:
All anchor tags and URLs should be clearly distinguished as links, for example through the use of color and/or text decoration, following appropriate accessibility standards.
The CSS must include support for a printer-friendly output. The print rules should be a part of the embedded style sheet; consumers of an RFC may develop their own print-specific style sheet as desired.
Lists should provide ample whitespace between list elements for legibility unless a ‘compact’ class is specified (e.g., .dlCompact, .ulCompact, .olCompact).
This section describes the CSS classes that result in specific changes to the natural language content of a document. A full list of available classes, not including basic selectors, are included in "Appendix A".
To be used with '.artwork' to indicate the figure should align in the center of the page flow.
To be used with '.artwork' to indicate the figure should align on the right of the page flow.
These classes will mostly be styled as part of .artwork. Specific classes may include '.art-ascii-art' and '.art-svg'. Artwork will be held in its own block of space, centered in the page flow, and will not float. Images should have a max width of 100% so views will scale properly across a variety of screens and devices.
Must use a mono-spaced font.
No visible changes to the natural language content; keep in default style. Note that such images are not currently allowed in RFCs.
A comment within an I-D; should be visually distinct.
For I-Ds only; not for RFCs.
A comment within an I-D; should be visually distinct.
For I-Ds only; not for RFCs.
A comment within an I-D; should be visually distinct.
For I-Ds only; not for RFCs.
Use less spacing on a definition list than the default.
Use the standard hanging indent for a definition list; indent terms.
Do not use the standard hanging indent for a definition list; align terms and definitions along left side.
Hide from visible content.
Standard link formatting (underlined, change in color).
Hide from visible content.
Notes should be emphasized and distinct from normal paragraph text.
An RFC Editor note may be added after the standard boilerplage. It should be visually distinct to highlight final removal of the note by the RFC Editor.
Use less spacing on a numbered list than the default.
If the style attribute from the source XML contains a percent sign, a particular style setting will be required to make this setting behave like an HTML ordered list.
Pilcrows, when used as described in draft-iab-html-rfc, should appear at the end of the paragraph, artwork, or sourcecode segment. They should not appear until moused-over. They should not show when printed, and should not be selected when copied with a copy/paste function.
Should be clearly distinguished as links.
Hide from visible content.
Code examples or components should be in a fixed-width font if the human language used has an available fixed-width font option, and should be visually distinct. If no fixed-width font is available, use the default font for that human language.
The table of contents should be clearly distinguished using an indented, ordered list with the list style set to 'none', allowing for hyperlinked, in-line dotted number notation (e.g., 1., 1.1., 1.1.1.).
No visible changes to the natural language content; keep in default style.
Use less spacing on a bulleted list than the default.
Indent from the margin of the previous paragraph.
Should be clearly distinguished as links.
Should be clearly distinguished as links.
Security vulnerabilities can be introduced through the CSS. How much detail do we need to go into here to say "don't do foolish things and introduce security issues?"
This draft contains no action for IANA
With many thanks to the RFC Format Design Team for their efforts in making this transition successful: Nevil Brownlee (ISE), Tony Hansen, Joe Hildebrand, Paul Hoffman, Ted Lemon, Julian Reschke, Adam Roach, Alice Russo, Robert Sparks (Tools Team liaison), and Dave Thaler.
Additional thanks to Arlen Johnson of Spherical Cow Group, LLC, for his assistance in clarifying the requirements in more CSS designer-friendly language.
To be removed before publication
added .refInstance, .ulEmpty, .ears, .left, .right, .center as per HTML draft
removed .comma, .closeParen, .openParen, .fullStop, .referenceGroup as per HTML draft
revised draft name; no major changes
Moved Appendix to correct location; fixed typos; moved lang-* to Appendix,
Adjusted class names where possible to a common naming pattern (CamelCase).
Added alignCenter, alignRight, dlHanging, ulEmpty
Moved full list of classes to Appendix; only discussed classes that will have visible changes to the text in the body
Introduction: text regarding expected future changes added.
Body: added text regarding anchors and tags; this text also applied to .relref, .url, .xref
Artwork: clarified non-floating behavior of artwork
List behavior: clarified the behavior of .ulCompact, .olCompact, and .dlCompact as distinct from default list behavior; clarified behavior of .dlparallel
Note: clarified text around behavior of notes
RFC: added additional class to allow the CSS to distinguish between RFCs and Internet Drafts if desired
TOC: clarified text around behavior of table of contents
| [HTMLBP] | W3C, "Best Practices for Authoring HTML Current Status", n.d.. |
| [RFC5741] | Daigle, L., Kolkman, O. and IAB, "RFC Streams, Headers, and Boilerplates", RFC 5741, DOI 10.17487/RFC5741, December 2009. |
| [RFC7322] | Flanagan, H. and S. Ginoza, "RFC Style Guide", RFC 7322, DOI 10.17487/RFC7322, September 2014. |
| [I-D.iab-html-rfc] | Hildebrand, J. and P. Hoffman, "HyperText Markup Language Request For Comments Format", Internet-Draft draft-iab-html-rfc-02, February 2016. |
| [I-D.iab-rfc-framework] | Flanagan, H., "RFC Format Framework", Internet-Draft draft-iab-rfc-framework-06, June 2016. |
This section lists all the CSS classes. Except for those also listed above in section 7, none of these result in specific changes to the natural language content of a document.