RSE Wiki Archive

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
==== 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.

A non-requirement is that the HTML document have any non-semantic information such as comments and processor instructions. (This non-requirement should be removed if they are not allowed the XML.)

The HTML document must come with a default internal set of CSS formatting. This will allow for a mostly-consistent display of RFCs across browsers. It will also allow for the HTML file to be moved over different transports (such as mail) and have the result look the same.

The HTML must display well in at least one text-based browser.

The HTML document must allow easy local override of the default CSS formatting. This will allow users who have a different visual style that they prefer to make RFCs display with that style without having to alter the contents of the HTML document. This might also be valuable for allowing people with specific accessibility needs to have custom CSS.

No HTML tags in the document may have style information. All style information must be done through "class" and "id" attributes, with the style for those represented in the CSS alone.

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

All section, subsections, figures, and paragraphs should have stable numbered link anchors. Additionally, anchors expressed in the source XML should be exposed as anchors in the HTML as well. 

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
RSE Wiki Archive

User Tools

Site Tools

Page Tools
