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
design:html-requirements [2013/10/17 09:42]
rsewikiadmin
design:html-requirements [2014/09/17 07:28] (current)
rsewikiadmin
Line 1: Line 1:
 ==== Requirements for HTML Output ==== ==== Requirements for HTML Output ====
-The RFC must be able to display the HTML output as intended on the latest released versions of Chrome, and Firefox in October 2013, as well as the latest released versions of IE and Safari as shipped on the latest released version of their respective operating systems as of that same date.+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 ChromeFirefox, 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 24: Line 30:
 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 ====
 +Answer added where possible, per RFC Format Design Team call 16-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.
 +
 +  * Joe will look at this; Paul notes that this assumes you have XML v3; Joe will need to work with Paul
 +
 +> 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?
 +
 +  * Joe will go through v3 draft and try to highlight what might impact HTML
 +
 +======
 +**CSS requirements**
 +
 +> "The only tags that may contain a 'style' attribute are " (and
 +> give an explicit list).
 +
 +  * punt on that, this won’t help developers, and we’re likely to change our minds
 +  * we will need guidance to say this is an exceptional situation; make sure that where you KNOW a style attrib needs to be explicitly placed, make sure to say so, and we will tell the developer “unless you see instruction to use style directly, don’t”   
 +  * There are style attributes, and things that inform style.  At the very end, we will have a complete list, but not now (and that's ok).
 +
 +======
 +**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).
 +
 +  * this draft should say the RFC Ed will maintain a list of browsers we will be testing against, and strip the actual list out of the draft; post on the RFC Ed website and maintain there
 +
 +> 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.
 +
 +  * not applicable; this applied to submitters (which we won't have) not the tool
 +
 +> Section 3.1 requires text containing elements be serialized as a single 
 +> unwrapped line (to help with diffs).
 +
 +  * all that was about stuff submitted as HTML; we should talk about what to indent with (spaces, not tabs) 
 +  * also, let’s keep the ease of diffs as a motive, because some people will want to run diffs against the HTML.  
 +  * Since we are building a diff tool for the XML, diff-ing the HTML will be less of a normal workflow case.  
 +  * So, remove any reference to wrapped text, and let the tools team do whatever and we’ll see what feedback we get
 +
 +>
 +> 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.
 +
 +  * Will probably pull out the whole indenting stuff too.  
 +  * Will put in something fuzzy about pretty-printed, don’t want it compressed or smooched up one line
 +
 +> 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). 
 +
 +  * Mention of non-div tags should be removed
 +
 +====Other open issues====
 +> What prefixes to use for autogenerated tags?
 +
 +  * Heather to just pick something
 +
 +> 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? 
 +
 +  * How to write software that identifies security considerations?  The IESG should have an opinion here.  RFC Editor can recommend, but the IESG is the one that would require.  
 +  * The only mandatory tag right now is for abstract.  
 +  * We can have two lists: one for mandatory, and one for suggested.    
 +  * Or maybe just make mandatory and see who complains.  
 +  * Paul to add something here in XML draft.  We’ll look at the name.
 +
 +> What reference to use (if any) for HTML5?
 +
 +  * leave that up to the RFC Editor what we’re currently tracking, similar to browsers.  The HTML5 people won’t use version numbers going forward.
 +
 +
 +> 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?
 +
 +  * Joe and Paul to review
 +
 +>
 +> 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.
 +
 +  * Joe might have a counter proposal; the one Paul has is a starting place that might work as well
 +  * will have more info to make a decision after the id section is done
 +
 +> 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? 
 +
 +  * Joe to to review
 +
 +> The document says "Additionally, anchors expressed in the source XML should 
 +> be exposed as anchors in the HTML as well." I suggested in my nits message 
 +> striking "Additionally," and "as well". But it occurs to me that the document 
 +> needs to be more specific and reflect _how_ the source XML allows anchors to 
 +> be expressed, and how those will be translated into the HTML. This falls, I 
 +> think, into being clearer about author-provided and autogenerated ids.
 +
 +> There's text that says to wrap section numbers in an 
 +> <a class='self-ref' href=...>. I suspect this should apply to other <a href> 
 +> that are generated?
 +
 +> The paragraph that begins "For other block items, such as <figure>, <t>, 
 +> and <texttable> is talking about XML, not HTML. Can it be rewritten more 
 +> specifically in terms of input and output? 
 +
 +  * Joe and Paul to review
design/html-requirements.1382028154.txt.gz · Last modified: 2013/10/17 09:42 by rsewikiadmin