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
Abstract
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.
Status of This Memo
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 Notice
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
Flanagan Expires January 5, 2017 [Page 1]
Internet-Draft I-D July 2016
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.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Design Goal . . . . . . . . . . . . . . . . . . . . . . . . . 3
3. General Requirements . . . . . . . . . . . . . . . . . . . . 4
4. Page Layout . . . . . . . . . . . . . . . . . . . . . . . . . 4
4.1. Title Page Header . . . . . . . . . . . . . . . . . . . . 4
4.2. Body . . . . . . . . . . . . . . . . . . . . . . . . . . 4
4.3. Font Choices . . . . . . . . . . . . . . . . . . . . . . 4
5. Printing . . . . . . . . . . . . . . . . . . . . . . . . . . 5
6. Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
7. CSS Classes and Attributes . . . . . . . . . . . . . . . . . 5
7.1. .alignCenter . . . . . . . . . . . . . . . . . . . . . . 5
7.2. .alignRight . . . . . . . . . . . . . . . . . . . . . . . 5
7.3. .artwork . . . . . . . . . . . . . . . . . . . . . . . . 5
7.3.1. .art-ascii-art . . . . . . . . . . . . . . . . . . . 6
7.3.2. .art-logo . . . . . . . . . . . . . . . . . . . . . . 6
7.4. .cref . . . . . . . . . . . . . . . . . . . . . . . . . . 6
7.5. .crefAnchor . . . . . . . . . . . . . . . . . . . . . . . 6
7.6. .crefSource . . . . . . . . . . . . . . . . . . . . . . . 6
7.7. .dlCompact . . . . . . . . . . . . . . . . . . . . . . . 6
7.8. .dlHanging . . . . . . . . . . . . . . . . . . . . . . . 6
7.9. .dlParallel . . . . . . . . . . . . . . . . . . . . . . . 6
7.10. .docInfo . . . . . . . . . . . . . . . . . . . . . . . . 6
7.11. .eref . . . . . . . . . . . . . . . . . . . . . . . . . . 7
7.12. .finalized . . . . . . . . . . . . . . . . . . . . . . . 7
7.13. .note . . . . . . . . . . . . . . . . . . . . . . . . . . 7
7.13.1. .rfcEditorRemove . . . . . . . . . . . . . . . . . . 7
7.14. .olCompact . . . . . . . . . . . . . . . . . . . . . . . 7
7.15. .olPercent . . . . . . . . . . . . . . . . . . . . . . . 7
7.16. .pilcrow . . . . . . . . . . . . . . . . . . . . . . . . 7
7.17. .relref . . . . . . . . . . . . . . . . . . . . . . . . . 7
7.18. .rendered . . . . . . . . . . . . . . . . . . . . . . . . 7
7.19. .sourcecode . . . . . . . . . . . . . . . . . . . . . . . 8
7.20. .toc . . . . . . . . . . . . . . . . . . . . . . . . . . 8
7.21. .type . . . . . . . . . . . . . . . . . . . . . . . . . . 8
7.22. .ulCompact . . . . . . . . . . . . . . . . . . . . . . . 8
7.23. .ulEmpty . . . . . . . . . . . . . . . . . . . . . . . . 8
7.24. .url . . . . . . . . . . . . . . . . . . . . . . . . . . 8
7.25. .xref . . . . . . . . . . . . . . . . . . . . . . . . . . 8
8. Security Considerations . . . . . . . . . . . . . . . . . . . 8
Flanagan Expires January 5, 2017 [Page 2]
Internet-Draft I-D July 2016
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8
10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 9
11. Draft Change Log . . . . . . . . . . . . . . . . . . . . . . 9
11.1. Changes from draft-iab-rfc-css-00 to -01 . . . . . . . . 9
11.2. Changes from draft-flanagan-rfc-css to draft-iab-rfc-css 9
11.3. Changes from -02 to -03 . . . . . . . . . . . . . . . . 9
11.4. Changes from -01 to -02 . . . . . . . . . . . . . . . . 9
11.5. Changes from -00 to -01 . . . . . . . . . . . . . . . . 9
12. Normative References . . . . . . . . . . . . . . . . . . . . 10
Appendix A. List of classes . . . . . . . . . . . . . . . . . . 10
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 14
1. Introduction
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.
2. Design Goal
RFCs must be adaptable to a wide variety of devices and displays,
accessible to assisted readers, and printable.
Flanagan Expires January 5, 2017 [Page 3]
Internet-Draft I-D July 2016
3. General Requirements
o Support the display of the semantic HTML described in
[I-D.iab-html-rfc].
o Follow best practice for accessibility, as defined by the W3C's
"Best Practices for Authoring HTML" [HTMLBP].
o Follow best practice for mobile devices, as defined by the W3C's
"Best Practices for Authoring HTML."
o Allow for a broad range of internationalized scripts.
4. Page Layout
4.1. Title Page Header
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]
4.2. Body
The body of the document must conform to the following:
o Examples and code blocks must be in a fixed-width font
o ASCII art must be in a fixed-width font
o Reflow the text as the screen gets smaller and limit max width
o Block quotes must be indented
o Tables must allow for distinct header rows
o Paragraphs should include a hover-over paragraph identifier
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.
4.3. Font Choices
o Default to a sans-serif font family with broad Unicode support for
web browser viewing.
o Default to a serif font family with broad Unicode support for
printing.
Flanagan Expires January 5, 2017 [Page 4]
Internet-Draft I-D July 2016
o A fixed-width font must be used for code and artwork-tagged
sections.
o All fonts should be publicly licensed and supported by all major
web browsers.
5. Printing
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.
6. Lists
Lists should provide ample whitespace between list elements for
legibility unless a 'compact' class is specified (e.g., .dlCompact,
.ulCompact, .olCompact).
7. CSS Classes and Attributes
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".
7.1. .alignCenter
To be used with '.artwork' to indicate the figure should align in the
center of the page flow.
7.2. .alignRight
To be used with '.artwork' to indicate the figure should align on the
right of the page flow.
7.3. .artwork
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.
Flanagan Expires January 5, 2017 [Page 5]
Internet-Draft I-D July 2016
7.3.1. .art-ascii-art
Must use a mono-spaced font.
7.3.2. .art-logo
No visible changes to the natural language content; keep in default
style. Note that such images are not currently allowed in RFCs.
7.4. .cref
A comment within an I-D; should be visually distinct.
For I-Ds only; not for RFCs.
7.5. .crefAnchor
A comment within an I-D; should be visually distinct.
For I-Ds only; not for RFCs.
7.6. .crefSource
A comment within an I-D; should be visually distinct.
For I-Ds only; not for RFCs.
7.7. .dlCompact
Use less spacing on a definition list than the default.
7.8. .dlHanging
Use the standard hanging indent for a definition list; indent terms.
7.9. .dlParallel
Do not use the standard hanging indent for a definition list; align
terms and definitions along left side.
7.10. .docInfo
Hide from visible content.
Flanagan Expires January 5, 2017 [Page 6]
Internet-Draft I-D July 2016
7.11. .eref
Standard link formatting (underlined, change in color).
7.12. .finalized
Hide from visible content.
7.13. .note
Notes should be emphasized and distinct from normal paragraph text.
7.13.1. .rfcEditorRemove
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.
7.14. .olCompact
Use less spacing on a numbered list than the default.
7.15. .olPercent
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.
7.16. .pilcrow
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.
7.17. .relref
Should be clearly distinguished as links.
7.18. .rendered
Hide from visible content.
Flanagan Expires January 5, 2017 [Page 7]
Internet-Draft I-D July 2016
7.19. .sourcecode
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.
7.20. .toc
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.).
7.21. .type
No visible changes to the natural language content; keep in default
style.
7.22. .ulCompact
Use less spacing on a bulleted list than the default.
7.23. .ulEmpty
Indent from the margin of the previous paragraph.
7.24. .url
Should be clearly distinguished as links.
7.25. .xref
Should be clearly distinguished as links.
8. Security Considerations
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?"
9. IANA Considerations
This draft contains no action for IANA
Flanagan Expires January 5, 2017 [Page 8]
Internet-Draft I-D July 2016
10. Acknowledgements
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.
11. Draft Change Log
To be removed before publication
11.1. Changes from draft-iab-rfc-css-00 to -01
added .refInstance, .ulEmpty, .ears, .left, .right, .center as per
HTML draft
removed .comma, .closeParen, .openParen, .fullStop, .referenceGroup
as per HTML draft
11.2. Changes from draft-flanagan-rfc-css to draft-iab-rfc-css
revised draft name; no major changes
11.3. Changes from -02 to -03
Moved Appendix to correct location; fixed typos; moved lang-* to
Appendix,
11.4. Changes from -01 to -02
Adjusted class names where possible to a common naming pattern
(CamelCase).
Added alignCenter, alignRight, dlHanging, ulEmpty
11.5. Changes from -00 to -01
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
Flanagan Expires January 5, 2017 [Page 9]
Internet-Draft I-D July 2016
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
12. Normative References
[HTMLBP] W3C, "Best Practices for Authoring HTML Current Status",
n.d., <http://www.w3.org/standards/techs/htmlbp>.
[RFC5741] Daigle, L., Ed., Kolkman, O., Ed., and IAB, "RFC Streams,
Headers, and Boilerplates", RFC 5741,
DOI 10.17487/RFC5741, December 2009,
<http://www.rfc-editor.org/info/rfc5741>.
[RFC7322] Flanagan, H. and S. Ginoza, "RFC Style Guide", RFC 7322,
DOI 10.17487/RFC7322, September 2014,
<http://www.rfc-editor.org/info/rfc7322>.
[I-D.iab-html-rfc]
Hildebrand, J. and P. Hoffman, "HyperText Markup Language
Request For Comments Format", draft-iab-html-rfc-03 (work
in progress), June 2016.
[I-D.iab-rfc-framework]
Flanagan, H., "RFC Format Framework", draft-iab-rfc-
framework-06 (work in progress), June 2016.
Appendix A. List of classes
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.
o .adr
o .alignCenter
o .alignRight
Flanagan Expires January 5, 2017 [Page 10]
Internet-Draft I-D July 2016
o .annotation
o .artwork
.art-ascii-art
.art-logo
.art-svg
o .ascii
o .author
o .authors
o .bcp14
o .center
o .city
o .compact
o .country-name
o .cref
o .crefAnchor
o .crefSource
o .dlCompact
o .dlHanging
o .dlParallel
o .docInfo
o .ears
o .email
o .eref
o .finalized
Flanagan Expires January 5, 2017 [Page 11]
Internet-Draft I-D July 2016
o .fn
o .index
o .indexChar
o .indexIndex
o .indexItem
o .indexPrimary
o .indexSubItem
o .initial
o .iref
o .irefItem
o .irefRefs
o .irefSubItem
o .label
o .left
o .locality
o .nameRole
o .note
.rfcEditorRemove
o .olCompact
o .olPercent
o .org
o .organization
o .pilcrow
o .postal-code
Flanagan Expires January 5, 2017 [Page 12]
Internet-Draft I-D July 2016
o .published
o .refContent
o .refDate
o .refInstance
o .refTitle
o .reference
o .region
o .relref
o .rendered
o .RFC
o .rfcEditorRemove
o .right
o .role
o .selfRef
o .series
o .seriesInfo
o .sourcecode
.lang-*
o .street-address
o .status
o .street-address
o .surname
o .tel
o .toc
Flanagan Expires January 5, 2017 [Page 13]
Internet-Draft I-D July 2016
o .type
o .ulCompact
o .ulEmpty
o .url
o .workgroup
o .xref
o .vcard
Author's Address
Heather Flanagan
RFC Editor
Email: rse@rfc-editor.org
URI: http://orcid.org/0000-0002-2647-2220
Flanagan Expires January 5, 2017 [Page 14]
