User Tools

Site Tools


design:20150602-notes

Attendees: Heather, Joe, Robert, Julian, Paul, Nevil, Alice, Tony

0. Agenda bash

1. HTML - <title> vs <h1>

Team agrees that <title> and something else is needed. Whether that is <h1> or <head> or something else in the body is the question? People will be ok with <title> in the <head> plus <h1>, following the way they do this in the W3C. This is a change in the v2 document, not in the HTML doc.

2. XML v2 - <xref> definition

  • how tied is this to the v3 discussion? Can we close this out for v2?

Julian: has made some small progress regarding how erefs with no content are formatted, but we still have vagueness regarding what the formatting tool is supposed to do with xrefs when they have text context. We can either document that it’s vague and not document it, or we can try to come to consensus on what it should be at which point it should be the same between v2 and v3. The v2 formatters today do not agree on what to do; we can’t easily tell what the converter to do for v3 if we don’t know what v2 should do.

Paul: disagree that it needs to match between the v2 and v3 spec. There are questions about what is the syntax, but then there is what should the output be when converted. We can agree in v2 that xref can have content, and that it can be empty. What is vague, is what would be generated by a text formatter. OK to say “the syntax is this, and formatters handle it differently.” We can then be clearer in the v3 spec on what formatters have to do.

Julian: do the specs define how it will be shown, or just the semantics? Originally, the goal was to describe the semantics, but in cases like this it leaves something unspecified that needs to be specified somewhere in the end.

Paul: we have these for v3, but not for v2, and that’s ok. Propose that Julian will put the semantics, which are clear, but state that the different outputters will represent it differently.

Robert: We have a well defined mapping from v2 to v3; if we have that, then if we have some “we don’t know what happens in v2 space” we ack that and move on.

Julian: if v2 spec says “formatters disagree on how to format these references” but we also agree that we have a well-defined conversion tool, then for some users of the <xref> elements, their output will change. If you are in v2 world, and want your <xref> to be formatted consistently, then this is the subset that is implemented consistently.

3. XML v3 - <xref> and <relref> Heather: thinks that one side is more semantically correct, one side is more author supportive

Paul: think that relref is simpler than xref; thinks that both are semantically correct.

Joe: don’t care about the distinction between semantic/author split. Just wants it to be clear. Whether it is two elements or one element, as long as the doc is clear.

Julian: the idea behind proposing <relref> is that it might make the description of how it’s formatted easier. That more functionality within xref might be a combinational explosion of possible features. But that can be handled in the xref definition itself, without adding a new element, because we can state up front what combination of attributes are supported and meaningful.

Tony: What Julian just said is totally correct. Whether it’s in xref or relref, we need to understand all the ramifications of the attributes, how they can be used together. Would prefer that it all be in xref, but that’s a separate discussion.

Paul: agree that having this clear does make sense. Paul tried creating a the list of interactions and it got fairly ugly; that’s why relref was created.

Julian: taking the actual element and attributes aside, do we agree on the functionality for relative references? Yes.

Paul: Yes. We want something relative. We want the something relative when it is to our documents that they don’t need to understand our naming scheme for drafts. We also want to be able to point that way to other SDO’s docs.

Julian: the goal is to make relative references in our own documents as simple as possible, while making relative references to other SDO documents possible for those authors who care enough.

Heather; yes.

Julian: will try to write this up as a variant of <xref> - turning a nonspecific reference to a doc to a more specific reference should only involve adding an attribute.

Paul: Note that the HTML draft is also on hold for this. Prep tool draft is also going to need to consume this.

Heather: If we can get alternative text by next call (9 June) then that would be good to discuss, else may move forward with the relref description so we can unblock the HTML and Prep tool draft.

Paul: Joe and Paul will update the docs as if <relref> is real; but make it so the functionality will directly map into <xref> if we ultimately decide on Julian’s text.

Tony: asks Julian to think about whether there is any way to simplify it. You have an idea how current attributes work; are there ways to make it easier?

4. Preptool and Formatter SoW

Paul: note that preptool has a new draft; please review since there are some specific concerns regarding questions of logic in the doc

Robert: reviews need to be soon; we should be counting this in days now not in months. When formatting for RFCs will not allow the use of deprecated elements, but they will still be allowed for I-Ds. We shouldn’t assert that formatters will ignore them.

Joe: It is possible that the formatters might do anything with deprecated elements and attributes, including ignoring them, when working in v3 mode. It might also warn, or error, depending on the setting. The thing that is prepped, after it has gone through the I-D submission process, we’ll hold on to the author submitted and the prepped version, the prepped shouldn’t have the deprecated stuff either.

Robert: you want to support draft authors that are making transition into v3, may want to use deprecated elements while still working on their draft.

Tony: there are two paths: final RFC publication work, and I-D work. RFC publication should remove deprecated elements, but for I-Ds, the deprecated elements should be acting the way they do in v2.

Joe: will find out a lot as we write the tooling; let’s get running code and then decide. Gut feel is that we will want something that has no deprecated stuff as the thing that we hold on to in prepped form, but ok with testing that gut with data.

Robert: If your gut field is correct, then we made a mistake in including the deprecated elements in the vocabulary.

Joe: agree.

Tony: don’t see a way to gradually move into v3 without supporting the v2 elements in drafts.

Joe: could do this in conversion tool.

Robert: does the conversion tol map all the deprecated elements to non-deprecated forms?

Tony: it does as much as it can, except where there has been something entirely removed from the grammar (e.g., vspace)

Joe: assertion that all the places where we have no mapping, removing that deprecated element is likely to not be a big problem, but won’t know that until we have tests.

Robert: how to say that in the preptool document?

Paul: didn’t say that in the preptool document. Joe is careful is not that the preptool should rip them out, it’s that the formatter tools have flexibility about what they do.

Tony: the definition of deprecated is that it acts the way its supposed to act, and will be removed at some point and will not be allowed after.

Julian: discuss where we deprecated things because they were introduced for vertical whitespace optimization, or when replaced them with things we thought were semantically better. They are different classes of problems.

Tony: consider tables; the v2 table mechanism is being replaced, but it should act to produce tables. The final RFC will not use the v2 table specs. the formatters need to be able to deal with the v2 table specs.

Joe: this can be done by an early conversion to v3, or some other way, but it’s an architectural decision and not something we need to answer today.

Robert: read through current version of preptool draft, and current wording is fine.

Julian: Tony is concerned about semantics of v2 and v3 tables, so the test will be if we have a direct mapping of v2 to v3 tables it doesn’t make a big different what the formatter implements.

Joe: also need to capture that we discuss what is stored as the prepped version of the document. At what point do you store? After the translation or not? Fine with authors being able to submit valid v2 documents, and for us to hold on to that original document. It’s a policy question on what’s accepted, and what will be the prepped version that’s left behind.

Paul: Asks Tony to come up with a list of what is not convertible at this point. Those could be oversights in v3, or could be points where we should clarify what will happen in v3 (you will be surprised by the output, and we don’t know in what way)

Tony: comments in the perl code already spell those out. Will pull them out.

5. AOB

design/20150602-notes.txt · Last modified: 2015/06/02 14:15 by rsewikiadmin