User Tools

Site Tools


design:html-requirements

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
Next revision Both sides next revision
design:html-requirements [2013/10/15 07:13]
rsewikiadmin
design:html-requirements [2014/09/15 12:59]
rsewikiadmin
Line 1: Line 1:
 ==== Requirements for HTML Output ==== ==== Requirements for HTML Output ====
 +The HTML has to render correctly on the following:
 +  * the latest released versions of Chrome, Firefox, and IE running on Windows 8 in November 2013
 +  * the latest released versions of Chrome, Firefox, and Safari running on Mac OS X 10.9 in November 2013
 +  * the latest released versions of Chrome and Safari running on iOS 7 in November 2013
 +  * the latest released versions of Chrome and Firefox running on Ubuntu 13.10 in November 2013
 +  * the latest released versions of Chrome and Firefox running on Android 4.1 in November 2013
 +These requirements are expected to change in the future to reflect the expectation that HTML rendering will be required for current versions of browsers and platforms, while ideally continuing to render correctly on earlier versions.
  
 The HTML document must preserve all semantic information that is in the canonical XML document. One use case is that preformatted text that has different tags in the XML will also be differentiable in the HTML, making it trivial to extract all of the (for example) ABNF in an RFC with a simple program. Another use case is that someone who wants to write programs that will extract information from an RFC can do so equally well with the XML and HTML, and can choose the tool that uses one or the other format for input. The HTML document must preserve all semantic information that is in the canonical XML document. One use case is that preformatted text that has different tags in the XML will also be differentiable in the HTML, making it trivial to extract all of the (for example) ABNF in an RFC with a simple program. Another use case is that someone who wants to write programs that will extract information from an RFC can do so equally well with the XML and HTML, and can choose the tool that uses one or the other format for input.
Line 15: Line 22:
 The HTML must make it easy to separate chunks into separate files. This will make creating EPUB documents easier in the future. The HTML must make it easy to separate chunks into separate files. This will make creating EPUB documents easier in the future.
  
-The output needs to be valid HTML 5.0. Language extensions might be acceptable after further discussion. The RFC Editor will need to use validating tool before publishing the HTML. This is not important for viewing with browsers, but is important for programs that will use the HTML format as input for processing.+The output needs to be HTML 5. Language extensions might be acceptable after further discussion. The RFC Editor will need to use an automated validating tool before publishing the HTML. This requirement is not important for viewing with browsers, but is important for programs that will use the HTML format as input for processing.
  
 The HTML must not have any Javascript or other active code in <script> tags. The HTML must not have any Javascript or other active code in <script> tags.
Line 22: Line 29:
  
 The abstract must be marked up or tagged in a way that search engines will extract it as summary. The abstract must be marked up or tagged in a way that search engines will extract it as summary.
 +
 +==== Open items - September 2014 ====
 +**Scope of the html document**
 +
 +> There are sections that are really requirements for people writing
 +> xml2rfc v3. Those should be teased out into the grammar draft or 
 +> draft talking about submission restrictions on the v3 format.
 +
 +
 +
 +> In section 3.2.10, we say "The id will usually be machine-generated,
 +> but MAY be human-readable if desired." Can we phrase this in terms of
 +> what the converter is expected to do instead?
 +
 +> Section 3.2.13 has what looks like instructions to authors: "If the
 +> quote needs a citation"... That should be in a document that talks in
 +> terms of the XML. What should be here is what the HTML is expected to
 +> reflect from the XML. What XML do we expect to be input to result in the
 +> HTML example in that  section?
 +
 +
 +======
 +**CSS requirements**
 +
 +> "The only tags that may contain a 'style' attribute are " (and
 +> give an explicit list).
 +
 +
 +======
 +**Basic HTML comments**
 +
 +> It would be good to double-check that the currently deployed browsers 
 +> treat that input as expected (at least at those we list as requirements).
 +
 +> Section 3.1 disallows points like U+0009. Section 4 talks about 
 +> compressing instances of U+0009 (and other disallowed points) into a 
 +> single U+0020.
 +
 +
 +
 +> Section 3.1 requires text containing elements be serialized as a single 
 +> unwrapped line (to help with diffs).
 +>
 +> There is a separate requirement to indent children. (Thus there is an 
 +> implicit requirement to start children on a new line.)
 +>
 +>  Which of the following are we wanting to happen?:
 +>
 +>  <p>For more information see <xref target='foo'>[I-D.draft-foo-bar]</xref>. Your mileage may vary.</p>
 +>
 +>  or
 +>
 +>  <p>For more information see
 +>     <xref target='foo'>[I-D.draft-foo-bar]</xref>
 +>  Your mileage may vary.</p>
 +>
 +> Either way, the text needs to be made consistent and some examples would 
 +> not hurt.
 +> Making the text consistent while dealing with nested lists may get gnarly.
 +
 +
 +
 +> There are a couple of places where the document talks about non-div 
 +> tags. I think this is from working in how we're going to place author 
 +> provided and autogenerated ids. I don't think the distinction helps, and 
 +> we can just say "tags" wherever the text says "non-div tags". (But I 
 +> also suspect we should be pulling out a section explicitly discussing 
 +> these ids). 
 +
 +====Other open issues====
 +> What prefixes to use for autogenerated tags?
 +
 +> Should an RFC style document encourage authors to use common tags for
 +> things like "Security Considerations," "IANA Considerations," etc., to
 +> help solve for the problem of intuitive pointers to common sections in 
 +> RFCs? 
 +(so far, Design Team has had one yes, one no)
 +
 +> What reference to use (if any) for HTML5?
 +
 +> Where is the line between indicating what the XML should do within the HTML
 +> for things like ASCII art, packet diagrams, etc, and what is appropriately 
 +> just information for the XML draft?
 +
 +> Should the HTML tags in the Appendixes stay (and get cleaned up) or be removed?
 +
 +>
 +> Using classes instead of ids to aid with styling.
 +> This is a very good point. If others agree, I would propose that the current 
 +> draft be changed from "<div id='abstract'>" to "<div class='abstract'>" and 
 +> that we specify classes for all sections that seem to have special meanings.
 +
 +> It's not clear what "same logic" in "Paragraphs are wrapped in <div>s using 
 +> the same logic as sections" means. Is this intending to talk about how id 
 +> attributes get placed, or something else? 
 +
  
design/html-requirements.txt ยท Last modified: 2014/09/17 07:28 by rsewikiadmin