Migration spec currently requires a non-standard version of xml2rfc

[Michael Jones]

There are several problems with this:

1. COSTS OF USING A NON-STANDARD TOOL: Forcing editors to use non-standard versions of tools is a non-starter. Maintaining and installing those tools then becomes an unnecessary tax on the working group and the editors and means that special expertise would needed to build a spec, rather than just going to http://xml2rfc.tools.ietf.org/old.html and using the standard version. We should only move off of the standard tools without a compelling reason to do so (which there isn't, because the existing specs are an existence proof that they work fine).

2. SHOULD REQUIRE WG DECISION: Changing to use a non-standard tool chain should be a decision made by the working group since it potentially affects many working group members and the long-term maintainability of the spec - not a decision made by individual editors.

3. FORMAT DIFFERENT THAN CURRENT SPECS: Using the non-standard extension ipr="oidf", as presently implemented, produces drafts with a different format than the approved OpenID Connect specifications. There's no compelling reason to format specs differently than we always have in the past.

4. DIFFERENT TITLE FOR IPR NOTICES: Our current specs use the title "Notices" for the board-required IPR statements. The revised tool emits the title "Full Copyright Statement", which is unnecessarily different.

5. ADDING NEW IPR CONTENT REQUIRES BOARD APPROVAL AND LEGAL REVIEW: The revised tool emits a new section "Intellectual Property" that contains additional information about IPR. I believe that a board decision is required before any additional IPR content is added to any specifications. Legal review may also be required.

[Michael Jones]

Issue #935 was marked as a duplicate of this issue.

[Michael Jones]

We agreed to build this spec using the standard old.html version of the tool.

Nat will write text in an HTML comment saying that the ipr="trust200902" is just there to satisfy the tool and not an accurate statement.

[Nat Sakimura]

Here are some of the discussion points around Mike's comment:

1. COSTS OF USING A NON-STANDARD TOOL: We are relying on the old tool now. New tool does not work for us right now. Unless the new tool is made compatible with the old tool, we would eventually have to start maintaining the old tool, so the cost implication may become the same. For the perceived issue, see the comments following this one.
2. SHOULD REQUIRE WG DECISION: If the XML is authoritative, then it is not the WG decision but the BOARD decision to continue relying on the tool as it renders danger to the OpenID IPR.
3. FORMAT DIFFERENT THAN CURRENT SPECS: The new version of the xml2rfc produces format different than current specs, so this point is rather moot. In addition, the perceived change in the format is not produced because of ipr="oidf" as pointed out in the Mike's comment. It was the result of deleting <?rfc private> tag. The removal of it produced exactly the same format as I-D including the expiry date, etc.
4. DIFFERENT TITLE FOR IPR NOTICES: It is the result of the <?rfc private> tag and aligned with I-D and RFC. It is not the result of the modification of the tool at all on the contrary to the comment.
5. ADDING NEW IPR CONTENT REQUIRES BOARD APPROVAL AND LEGAL REVIEW: This may be so, but it actually is puzzling why this is not there to start with. Our current specs has no pointer at all to the OpenID IPR and OpenID Process that governs these specs. This should be taken up by the Board in the next call. Perhaps having the link to "The OpenID Intellectual Property Rights policy" in the Copyright text would be a good idea.

As the result of the discussion that it was determined that the XML source is just the tool and not the authoritative copy. It has never been declared despite XML files are recoded in the official release repository in parallel to the HTML versions. Board should announce it clearly to the readers.

To achieve this, it was determined to put an XML comment to the XML source.

Since now it is determined that XML file is just a tool for editors and not an official copy, then ipr="" and <?rfc private="..."> can be anything as long as it is associated with the clear XML comment.

ACTION

1. Nat to draft an XML Comment to put in.
2. Nat to take the issue of "no-link to the IPR policy" to the board.
3. Mike to communicate the bugs and requirements to the xml2rfc 2.0 team.

[Nat Sakimura]

Here is the Draft XML Comment:

<!--
NOTE on this XML File. 

This XML file is a tool to produce the authoritative copy of OpenID Foundation spec. 
The authoritative copy is the HTML, and the corresponding XML source is not authoritative. 
The statement that ipr="none" is here only to satisfy the tool. 
The IPR of this document is OpenID IPR Policy found at 
http://openid.net/ipr/OpenID_IPR_Policy_(Final_Clean_20071221).pdf 
and governed by OpenID Process found at 
http://openid.net/wordpress-content/uploads/2010/01/OpenID_Process_Document_December_2009_Final_Approved.pdf. 
The directive private="..." is here only to satisfy the tool and desired HTML output. 
This is a public OIDF document and not an individual private memo as private="..." indicates. 
-->

[Nat Sakimura]

Followings are the issues that I identified with xml2rfc 2.0.

1. <?rfc private="draft"> does not give "draft" in the title header as in the old tool.
2. artwork in the old.html is produced in fixed-width font while new one does not so the diagrams gets broken. This is becasue pre was associated with courier-new in the old version while the new version has not.
3. The header is wider, and centered. It used to be narrower and left aligned.
4. The file name shows up below the title in the new version.
5. Title is centered instead of left aligned.
6. No links to get back to the TOC.
7. No <hr /> as the section separator.
8. hovering on the <xref> does not produce tool-tip showing the reference anymore.
9. <xref> used to produced bold red text so that it stood out. New one produces normal blue text only.
10. Section headers are now using bigger font.
11. <spanx style="verb"> used to produce <tt></tt> with font being courier-new while the new tool produces <samp></samp> without any associated style. IMHO, there should be an associated style sheet entry to samp with font:courier-new.

[Michael Jones]

I would not include links to specific IPR documents in the comment without a board decision because we update these from time to time. If you want to say anything in the comment, you could just say that current versions of the OpenID IPR Policy and Process documents can be found at openid.net.

I agree that xml2rfc 2.0 is different in a few mostly non-substantive ways from the 1.0 version. I think we should continue using 1.0 for now because it produces output equivalent to our current approved specs. The IETF has shown no indication that it will remove the old tool. I'm on the tools and xml2rfc mailing lists there and will alert us if that is discussed. Unless that occurs, I don't think there's anything we need to do, other than keep using the version at xml2rfc.tools.ietf.org/old.html.

However, I've also filed bugs against the 2.0 tool based on ways that it renders openid-connect-core-1_0.xml differently than the 1.0 tool. Are there any additional bugs that the working believes that I should file, based on Nat's list above?

It would be better to file these while the new tool is still under active development.

[Nat Sakimura]

Most of the original descriptions are invalid.

Through the discussion, a few interesting points came up and they will get new ticket numbers.