Internet DRAFT - draft-iab-rfc-css

draft-iab-rfc-css







Internet Architecture Board                                  H. Flanagan
Internet-Draft                                                RFC Editor
Intended status: Informational                           January 4, 2016
Expires: July 7, 2016


                       CSS Requirements for RFCs
                          draft-iab-rfc-css-00

Abstract

   The HTML format for RFCs, described in [I-D.hildebrand-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-hildebrand-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 July 7, 2016.

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 July 7, 2016                  [Page 1]

Internet-Draft                     I-D                      January 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.  .closeParen . . . . . . . . . . . . . . . . . . . . . . .   6
     7.5.  .comma  . . . . . . . . . . . . . . . . . . . . . . . . .   6
     7.6.  .cref . . . . . . . . . . . . . . . . . . . . . . . . . .   6
     7.7.  .crefAnchor . . . . . . . . . . . . . . . . . . . . . . .   6
     7.8.  .crefSource . . . . . . . . . . . . . . . . . . . . . . .   6
     7.9.  .dlCompact  . . . . . . . . . . . . . . . . . . . . . . .   6
     7.10. .dlHanging  . . . . . . . . . . . . . . . . . . . . . . .   6
     7.11. .dlParallel . . . . . . . . . . . . . . . . . . . . . . .   7
     7.12. .docInfo  . . . . . . . . . . . . . . . . . . . . . . . .   7
     7.13. .eref . . . . . . . . . . . . . . . . . . . . . . . . . .   7
     7.14. .finalized  . . . . . . . . . . . . . . . . . . . . . . .   7
     7.15. .fullStop . . . . . . . . . . . . . . . . . . . . . . . .   7
     7.16. .note . . . . . . . . . . . . . . . . . . . . . . . . . .   7
       7.16.1.  .rfcEditorRemove . . . . . . . . . . . . . . . . . .   7
     7.17. .olCompact  . . . . . . . . . . . . . . . . . . . . . . .   7
     7.18. .olPercent  . . . . . . . . . . . . . . . . . . . . . . .   7
     7.19. .openParen  . . . . . . . . . . . . . . . . . . . . . . .   7
     7.20. .pilcrow  . . . . . . . . . . . . . . . . . . . . . . . .   8
     7.21. .relref . . . . . . . . . . . . . . . . . . . . . . . . .   8
     7.22. .rendered . . . . . . . . . . . . . . . . . . . . . . . .   8
     7.23. .sourcecode . . . . . . . . . . . . . . . . . . . . . . .   8
     7.24. .toc  . . . . . . . . . . . . . . . . . . . . . . . . . .   8
     7.25. .type . . . . . . . . . . . . . . . . . . . . . . . . . .   8
     7.26. .ulCompact  . . . . . . . . . . . . . . . . . . . . . . .   8



Flanagan                  Expires July 7, 2016                  [Page 2]

Internet-Draft                     I-D                      January 2016


     7.27. .ulEmpty  . . . . . . . . . . . . . . . . . . . . . . . .   8
     7.28. .url  . . . . . . . . . . . . . . . . . . . . . . . . . .   8
     7.29. .xref . . . . . . . . . . . . . . . . . . . . . . . . . .   9
   8.  Security Considerations . . . . . . . . . . . . . . . . . . .   9
   9.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .   9
   10. Acknowledgements  . . . . . . . . . . . . . . . . . . . . . .   9
   11. Draft Change Log  . . . . . . . . . . . . . . . . . . . . . .   9
     11.1.  Changes from -02 to -03  . . . . . . . . . . . . . . . .   9
     11.2.  Changes from -01 to -02  . . . . . . . . . . . . . . . .   9
     11.3.  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.hildebrand-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.flanagan-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 July 7, 2016                  [Page 3]

Internet-Draft                     I-D                      January 2016


3.  General Requirements

   o  Support the display of the semantic HTML described in
      [I-D.hildebrand-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 July 7, 2016                  [Page 4]

Internet-Draft                     I-D                      January 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 July 7, 2016                  [Page 5]

Internet-Draft                     I-D                      January 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.  .closeParen

   Close the whitespace before a closing parenthesis after a <span>
   block by moving the text within the block to the right and moving the
   closing parenthesis to the left..

7.5.  .comma

   Close the whitespace before a comma after a <span> block by moving
   the text within the block to the left and moving the comma to the
   right.

7.6.  .cref

   A comment within an I-D; should be visually distinct.

   For I-Ds only; not for RFCs.

7.7.  .crefAnchor

   A comment within an I-D; should be visually distinct.

   For I-Ds only; not for RFCs.

7.8.  .crefSource

   A comment within an I-D; should be visually distinct.

   For I-Ds only; not for RFCs.

7.9.  .dlCompact

   Use less spacing on a definition list than the default.

7.10.  .dlHanging

   Use the standard hanging indent for a definition list; indent terms.





Flanagan                  Expires July 7, 2016                  [Page 6]

Internet-Draft                     I-D                      January 2016


7.11.  .dlParallel

   Do not use the standard hanging indent for a definition list; align
   terms and definitions along left side.

7.12.  .docInfo

   Hide from visible content.

7.13.  .eref

   Standard link formatting (underlined, change in color).

7.14.  .finalized

   Hide from visible content.

7.15.  .fullStop

   Close the whitespace before a period or full stop after a <span>
   block by moving the text within the block to the left and moving the
   period to the right.

7.16.  .note

   Notes should be emphasized and distinct from normal paragraph text.

7.16.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.17.  .olCompact

   Use less spacing on a numbered list than the default.

7.18.  .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.19.  .openParen

   Close the whitespace after an opening parenthesis and before a <span>
   block by moving the text within the block to the left and moving the
   opening parenthesis to the right.



Flanagan                  Expires July 7, 2016                  [Page 7]

Internet-Draft                     I-D                      January 2016


7.20.  .pilcrow

   Pilcrows, when used as described in draft-hildebrand-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.21.  .relref

   Should be clearly distinguished as links.

7.22.  .rendered

   Hide from visible content.

7.23.  .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.24.  .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.25.  .type

   No visible changes to the natural language content; keep in default
   style.

7.26.  .ulCompact

   Use less spacing on a bulleted list than the default.

7.27.  .ulEmpty

   Indent from the margin of the previous paragraph.

7.28.  .url

   Should be clearly distinguished as links.





Flanagan                  Expires July 7, 2016                  [Page 8]

Internet-Draft                     I-D                      January 2016


7.29.  .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

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 -02 to -03

   Moved Appendix to correct location; fixed typos; moved lang-* to
   Appendix,

11.2.  Changes from -01 to -02

   Adjusted class names where possible to a common naming pattern
   (CamelCase).

   Added alignCenter, alignRight, dlHanging, closedParen, openParen,
   ulEmpty

11.3.  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.



Flanagan                  Expires July 7, 2016                  [Page 9]

Internet-Draft                     I-D                      January 2016


   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

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.hildebrand-html-rfc]
              Hildebrand, J. and P. Hoffman, "HyperText Markup Language
              Request For Comments Format", draft-hildebrand-html-rfc-10
              (work in progress), August 2015.

   [I-D.flanagan-rfc-framework]
              Flanagan, H., "RFC Format Framework", draft-flanagan-rfc-
              framework-08 (work in progress), December 2015.

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



Flanagan                  Expires July 7, 2016                 [Page 10]

Internet-Draft                     I-D                      January 2016


   o  .alignRight

   o  .annotation

   o  .artwork

         .art-ascii-art

         .art-logo

         .art-svg

   o  .ascii

   o  .author

   o  .authors

   o  .bcp14

   o  .city

   o  .closeParen

   o  .comma

   o  .compact

   o  .country-name

   o  .cref

   o  .crefAnchor

   o  .crefSource

   o  .dlCompact

   o  .dlHanging

   o  .dlParallel

   o  .docInfo

   o  .email

   o  .eref




Flanagan                  Expires July 7, 2016                 [Page 11]

Internet-Draft                     I-D                      January 2016


   o  .finalized

   o  .fn

   o  .fullStop

   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  .locality

   o  .nameRole

   o  .note

         .rfcEditorRemove

   o  .olCompact

   o  .olPercent

   o  .openParen

   o  .org

   o  .organization




Flanagan                  Expires July 7, 2016                 [Page 12]

Internet-Draft                     I-D                      January 2016


   o  .pilcrow

   o  .postal-code

   o  .published

   o  .refAuthor

   o  .refContent

   o  .refDate

   o  .refTitle

   o  .reference

   o  .referenceGroup

   o  .region

   o  .relref

   o  .rendered

   o  .RFC

   o  .rfcEditorRemove

   o  .role

   o  .selfRef

   o  .series

   o  .seriesInfo

   o  .sourcecode

         .lang-*

   o  .street-address

   o  .status

   o  .street-address

   o  .surname




Flanagan                  Expires July 7, 2016                 [Page 13]

Internet-Draft                     I-D                      January 2016


   o  .tel

   o  .toc

   o  .type

   o  .ulCompact

   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 July 7, 2016                 [Page 14]