[rfc-i] Review of v3 vocabulary

[paul.hoffman at vpnc.org (Paul Hoffman)]

On Nov 4, 2014, at 9:41 PM, ietf at augustcellars.com wrote:

> Paul,  I apologize for this being so disjointed.  I am doing it on a surface as my laptop is n the shop and I have not figured out how to do things correct yet.  Also I reviewed in terms of grammar rather than linear.  Hope it is not too disjoint or incoherent.

It was, but I did by best. Fortunately, Julian did a lot of the legwork.

Everyone: if you want to comment on my comments below, and I haven't already started a new thread, PLEASE START A NEW THREAD. There is no way we'll be able to know what the community wants if it is all jumbled into one thread with the wrong title on it.

--Paul Hoffman

> Section 2.31 if only one allowed,  the draft processor might remove the <link> element ?

Fixed in the next draft to allow zero or more <link>s.

> Section 2.31.2  what does an empty rel attribute mean.
> Is there a required warning for unknown rel values?

This document doesn't detail all the possible warnings from the processors. Those will evolve over time.

> 2.45.4  is ipr required for all drafts?  Any other documents?

No, but a processor might require certain values for submission. This document is about the vocabulary, not the submission requirements for drafts or RFCs. If this draft strays into the latter, it should be removed from the draft.

> A.2.1.2   does the word default imply a processor action?

No.

> A.2.1.3 is this incompatible independent  rfcs?

That is a question for the ISE, who is on the design team and is thus presumably reviewing this document.

> Section 2.45.7 why a single section?

This is a historical value. Clearly, values in 2.45 will change over time.

> Section 2.45.7  is  this numbers or strings rfc XXXX for rfcs? 

Numbers, as it says.

> What about obsolete="draft-foo-03" for -04?

This is a process question, not a format question.

> Section 2.45.8 - is this based on the category attribute?

Yes.

> Is there additional notation if the document is part of a series (i.e. of 3 documents)

Not yet. I'll start a separate thread on this question later.

> Section 2.45.9 - default - "yes"?

Given that this is a new feature, some people might be surprised if their references got sorted when they didn't want them to be (or if they are sorted using an algorithm they don't like). Thus, I think the default should be "no".

> Section 2,45,14 can have both updates and obsoletes?

Sure.

Foreshadowing: If you disagree on any of the ASCII-related issues, first read draft-flanagan-nonascii. If you still disagree, please start a new thread about *that* document, and I can reflect the result in this one.

> Section 2.60  how do abbrev and ascii interact   is there an ascii only requirement on abbrev?

They do not interact; there is no need for an ASCII version of the abbreviation. 

> Section 2.7 -- no ascii equivalents for initials and surname?   But no restriction either

Correct. 

> Section 2.36.1   ascii restricted?

No.

> Section >>}] should org have a lang attribute?   Chinese name at Japanese company

Yes; fixed in the next draft.

> Section 2.15  restricted to country codes?  

No.

> If not needs ascii attribute

See above.

> Why allow multiple postal?

Fixed in the next draft.

> Section 2.64  intl characters here?

No; this explicitly says URI.

> Section 2.172  this is inconsistent with 2/17

In what way?

> 2.17 restricted to ascii?

Yes.

> 2.46  need to note it can be in a boilerplate element>?

That is already there.

> 2.46.6  what does the value include mean?   Include even if past tocDepth?

Unfortunately, we need to start a new thread on this one because it may be different than v2.

> 2.46  is name optional?  If not sections cannot be empty   if so would title be required?

Fixed in the next draft.

> I don?t understand artwork

You need to spend more time in museums. :-) See below.

> 2.11.2  If I quote a private email or an unpublished document, what do I put here?   I don't understand how this can be required.

I copied the element from HTML5, where the cite attribute must be a URI. It is not required but, if supplied, must be a URI.

> 2.20  missing section po9inters for dt and dd elements

They are there in the paragraph immediately following the one you are looking at.

> Section 2.48  it is not clear to me that this is  or is not a fixed width font thing

Yes. I have added a note to that effect in the next draft.

> 2.35.4  what is the bullets here doing?  Bullets are ul as well

There are no bullets here.

> 2.63  do I get control on bullet characters?

Nope. There is a balance between freedom and predictability, and on this one folks seem to prefer predictability.

> 2.58 - td is missing the open angle bracket

Fixed.

> 2.54 - why are more than one tbody is allowed?

I copied the element from HTML5, where more than one tbody is allowed. You might want more bodies without repeating the headers, for example.

> 2.43 - does displayreference change the sort order?

Yes. A note on this will be in the next draft.

> 2.43 - how do I do <references title=references><references title=normative/> or is that no longer allowed?

It looks from later in the thread you discovered that this was wrong.

> 2.43 - I want reference elements to be optional in the references section. I often put in the structure without yet filling any references until I need one

Good call. Fixed in the next draft.

> 2.43 - what about referencegroup as an element?

Not sure what this means.

> Section 1 - s/version (/version 2/

I assume this is a typo on your part.

> 'section 1.2.1 - dl, ul and ol are not restricted to being children of section

Good catch; fixed in the next draft.

> Section 1.2.2 - boilerplatetext is not an attribute - should move to 1.2.1 and become boilerplate

Good catch; fixed in the next draft.
 
> Section 1.2.2 - look for commentary on why partNumber is not used in all cases rather than sectionNumber and so forth -- I don't see a reasoning behind this lack of consistency.

sectionNumber is needed for numbering in the TOC and the generated headings. partNumber is only used for generated anchors.

> Section 2. - I am having a number of different problems with the artwork text   I don't know if this is because it is not clear, or I am being more ornery than usual.

The first is true (and will be fixed in the next draft), the second is possible as well.

> The text appears to imply that bitmaps are reasonable artwork.  I thought that it was going to be restricted to ascii art and svg at this time.  (Yes I realize that one can put a bitmap into an svg object.)  it might be better to remove some of the "such as a bitmap" type text.

Nothing yet has prohibited bitmap graphics on their own. If you want to do so, please start a thread about saying this in draft-flanagan-rfc-framework. If the RSE agrees, I'll fix this document.

> s/there are four was to include SVG/there are four ways to include external artwork/

It's not clear we want to do that yet.

> Section 2.5.2 - I don't understand why the alt attribute does different things based on the src attribute.  I can understand it doing different things based on the type attribute - that is for svg it can look for description in the text.  However if I do src="foo.txt" then it does not make sense for the program to try and find alt text in that file
>  
> This also gets strange if an xml->xml processor moves the object inline because it will change processing - this is also a bad thing

Fully agree; the text got out of sync with the process. This is fixed in the next draft.

> Also note that artwork does not have a caption - so that piece of text in 2.5.2 does not make sense

Clarified in the next draft.

> Section 2.5.8 - is there any base line processing that all processors are expected to do for any of these items - i.e. use fixed width fonts for ascii-art.  Look for descriptions in svg files?  If so this should be documented

There is not.

> Section 2.11.4 - this has a persons name or a book title - should there be an ascii equivalent for this field?

See above about ASCII.

> Section 2.16 - I have started trying to do more things with cref in my documents of late - specifically I have tried to capture feedback comments into cref elements for better viewing and tracking.   This has lead me to want to be able to do two things that are currently not supported.  1) to have an attribute that allows me to control if the cref is displayed or not.   This would allow me to surprises those crefs that have been resolved, while keeping the conversation in the document for later reference if needed.  2) allow for <t> elements to be used to recorded multiple comments into a single cref.

I added the "display" attribute to the next draft. I do not want to include the second proposal because it opens a rats nest of problems of embedding things in other things via <cref>. You can instead do multiple <cref>s.

> Section  - there was a conversation around the question of what happens if an xref references an element of a reference group.   This conversation should at a minimum be alluded to if any warnings are expected to be issued in the general case.  The same thing would also be true for a reference that is part of a group and standalone.   Currently this would fail due to the conflict in anchors - is that desired behavior?

I'll have to open a new thread on this one. We are still not sure how reference groups will be rendered, and those questions are pertinent to that.

> Section 2.25 - I would like to register a protest at the deprecation preamble and postamble from table and figure.   The only reason why the kludge suggested works is the fact that there is currently no support expected for the concept of floating tables and figures.   If these ever came into existence, then the fact that these do not exist means that the attachment of this text to the figure/table would be lost.

Noted.

> Section 2.35  is the style attribute mandatory?  It only says it can't be empty  if not, is there a default

"style" is optional.

> Section 2.48 - should I be able to label a code fragment as oppose to a full item - for example a fragment of asn;1 vs the complete asn.1 module

The list could be doubled in length for fragments, but that seems excessive. Do you foresee that an ASN.1 fragment would be rendered differently than a full ASN.1 module? Of that a program looking for ASN.1 in a published RFC will do something different with a fragment than with a full module?

> Section 2.48 - are there known requirements on processing- i.e. fixed width font - or s this dependent on the type:

A note about always being rendered as fixed-width font will be in the next draft.

> Section 2.54  -- is there a reasoning behind allowing multiple tbody elements?  If so should that be discussed:

See above: this is adopted from the HTML5 spec.

> I don't understand what to do for td elements with rowspan > 1.  'are these cells skipped in the next tr, or d they need to have empty td elements for this.  Is it an error t have an element that has anything in it?

I'm hesitant to have a complete copy of the HTML5 table processing rules, but maybe some more text could be added.

> Section 2.56  was it intentional that the align attribute of c, ttcol were lost in the transition?

Again, I copied this from HTML5, where there is no align attributes. However, the next draft will have an "align" attribute for <th> and <td>.