Attendees: Joe, Julian, Nevil, Paul, Heather, Robert, Tony, Sandy
0. Agenda bash
1. deprecated/obsoleted discussion (From Heather’s email to rfc-design) We could say that we will continue with the deprecated/obsoleted path for vocabulary items out of v2 (since it has never been canonical) but continue support for the v3 vocabulary in perpetuity, regardless of future changes and enhancements to the vocabulary. I'm not thrilled with that, but I think it could be a reasonable compromise. Thoughts?
Joe doesn’t agree with the approach to the email that Paul drafted. One, HF has said pretty directly that the canonical documents to be published will be valid v3 without deprecated features (leaving aside forward compatibility for the moment). Given that, at some point in the tool chain, we are going to be generating a valid v3 without deprecation XML document. If you send plain text to the RPC, that might happen sooner, if you send a v2 XML, it might happen later. Tooling will need to exist to do this from at least v2. If we look at each one of the features in v2 that are deprecated in v3, some of them have straightforward mappings into v3, some require some finesse that mostly works, and some don’t work at all (because those features just don’t exist (e.g., some expressions of vspace) So, the way to think about this is: there are configurations of the tooling that might generate warnings, errors, or nothing for different settings of the configuration parameters. For something that is easy and straightforward to translate, you might just translate it before you turn it into the actual output file (actually implementation details will vary). For other things, you might issue a warning (“we think we got this right, but you should check”). For other things, you might issue an error. For the things you might error on, you might set it up to ignore those with your configuration of the tooling. What that allows us to do is that during the transition period, with the target audience being people like us, to use the v2 format, to use the new tooling against it, and output the new output formats pretty easily. Also gives nice incentives to move people to v3 over time, esp. during AUTH48 when people might say “I haven’t seen the conversion done before approval; I should do that myself.” That will let us keep the current definition of deprecated, make a case-by-case decision on tooling, decide on the configuration nobs for errors and outputs, and might allow to move forward.
Paul: that captures the conversation, and while isn’t what I proposed, sounds very sensible
Robert: I followed, I think it’s the right target
Julian: what does this mean for Paul’s draft as currently written? It recently changed to require a name element, for instance, instead of title
Joe: there are a couple of things to do in Paul’s document. For all things that can be translated, specify those translations in that document. (If you use this deprecated feature, it has the same effect as this new feature.) There are a couple of places like Title where we need to specify what you need to do if you have both. And there is name, for example, where instead of being required.
Julian: agree having the mapping written down will be a good thing; not sure it needs to be in the v3 draft.
Joe: would rather not have to jump between documents, but can be convinced if you have a good use case. Once you have the rules in there, you may as well have the mappings.
Julian: the main concern is writing down the mappings might slow us down, but since this won’t be finally published, that’s ok?
Joe: yes
Julian: summarize: we will stick with original definition of deprecation, but there shall not be deprecated features in the v3 format. Can Tony write this for the v3 draft, since he has the code to do it? Tony’s information can help
Joe: suggest Paul to take a look at the mapping tool, and pull what you can out of there? Paul may try reverse, by mapping what he thinks it should be and then comparing it to Tony’s tool. Julian will create a test document to let us work on this.
Tony: that test document should go in the examples draft.
Joe: No, we need something just to test edge cases; examples should guide people to what we actually want them to do.
Paul: this means Paul needs to look through the v3 document at what’s marked deprecated, where it says “instead use such and such” and turn that into an actual set of mappings
Joe: one other bit, a tool requirement. That one of the potential output formats of the tooling is this finalized version. Make sure it doesn’t have any deprecated feature in that output is one of the things that must go on that list.
2. Where to put DOIs?
(From Paul’s message to rfc-interest) In order to have DOIs in both locations, we can: 1) Leave it in <link> for the current document and <seriesInfo> for references 2) Create <doi> to be part of <front>
Paul: would like something that works equally well for the reference as well as for the specific RFC.
Joe: agreed.
Julian: it would be nice if that was the case, but it’s already confusing now with the attributes on the rfc elements. To make it true, we would need to have series info somewhere else, not in <front>
Paul: agree this would be good, but now might not be a good time; this is a lot of work
Joe: if we don’t it now, we will never get it done
Julian: willing to look at it again, and writing it up for the team to consider. How much refactoring do we do on v2 features which might not like but which aren’t really broken?
Joe: we don’t have bibliographic references for BCP and STD, so we are going to have to come up with something and this could help that.
Julian: really don’t want to add something specific for DOI; should be generic
3. Draft status - plain-text - non-ASCII (maybe not “ASCII” but “alternate” and have rules of thumb and be reasonable) - HTML (bunch of comments to review and possibly incorporate; several edge cases that Paul pointed out that Joe has put in code for, and now needs to put back in the document) - PDF (no progress since Hawaii; hopefully will get back to this later this month) - XML v3 (we have pending issues from Jim Schaad that are updated in a revised draft, but am waiting for Julian to do the many little updates needed for v2; will go ahead and push it out now)
For numbered things, we have four names: figurenumber, sectionnumber, table number, and part number. (Julian) can we just rename them all to “pn”? It doesn’t change the semantics, it just makes the generated document more clear. (Joe) fine with it, will write tooling against it to see if it breaks. (Julian) if something breaks because of that, that would be interesting because it’s not supposed to. In HTML they are supposed to become id attributes. (Tony) no immediate concerns, but would like to review in the notes or in the revised draft.
4. AOB
(From Julian)
1) I discovered one left-over TODO in the v2 spec. I'll try to get to that asap, and then post a new draft. (as draft-iab...?) 2) I started to cherry-pick features from the v3 spec for support in my XSLT code; and started to use those in the v2 draft. See: <http://greenbytes.de/tech/webdav/rfc2629xslt/rfc2629xslt.html#v3> for the documentation and <http://greenbytes.de/tech/webdav/draft-reschke-xml2rfc-latest.html> for the HTML generated for the v2 draft.
Tony should look at Julian’s documentation on this, to see how it might feed the conversion code.
(From Heather)
I'd also like to add a discussion on the following: "One of the SoW, probably the presentation format converter, needs additional text pointing to a description of the processing that will be performed on a v3 document before publication as an RFC (things like calculating section anchors and including the expanded boilerplate). The description itself will likely land in the framework document."
Much of this will have to be things that land in detailed instructions to the programmers. There is stuff that Robert is capturing and writing down, some of that needs to be said in framework. Framework doesn’t say it will have an expanded version of the boilerplate; it needs to say that (though not what the boilerplate is). Robert will propose text; we need to tell people what we’re going to do, completing that list in the same level of detail. Other bits have already been detailed in v2 and v3 in the appendix (B.2.1. in v3 that calls out the format, from that you can infer information; the SoW need to tie it all together)
