Re: [auth48] [AD] AUTH48: RFC-to-be 9553 <draft-ietf-calext-jscontact-16> for your review

[Robert Stepanek <[e-mail]>]

Hi,

On Fri, Mar 22, 2024, at 2:26 AM, Karen Moore wrote:
> 2) We updated Table 2 (Section 3.5.2) by removing the reference column and linking each section number to the corresponding property context (so it now fits within the 72-character size limit). Please review and let us know if any further changes are needed. 

Thank you. No further changes are needed.

> 
> Note that we linked instances of “OrgUnit” to Section 2.2.3. Also “contexts”, mediaType”, “name”, “label”, “pref”, and “uri” contain additional section mentions.  We handled this by adding, for example, "Also see Sections 1.4.4 and 1.5.2” under the list of property contexts. Please let us know if this is agreeable or if you prefer otherwise.

Thanks, this is good.

> 
> 3) Regarding the following text, would it be clearer to add “that directs” or “on” after “information”? 
> 
> Current:
>    speakToAs: SpeakToAs (optional). The information how to address, speak to, or refer 
>         to the entity that is represented by the Card.
> 
> Perhaps:
>    speakToAs: SpeakToAs (optional). The information that directs how to address, speak to, or refer 
>         to the entity that is represented by the Card.

Yes, that would be clearer.

> 
> 4) Currently, I-D.ietf-uuidrev-rfc4122bis is in RFC-EDITOR state. We suggest finalizing AUTH48 for all three companion documents and then revisiting what state I-D.ietf-uuidrev-rfc4122bis is in prior to publication. At that time, we will have a better understanding of where that document is in the process and when it may be published.

That is great.

Best regards,
Robert

> 
> >> 15) <!--[rfced] FYI: For clarity and ease of reading, we added a reference
> >> to RFC 4122 as shown below.
> >> 
> >> Original: 
> >>    As of this writing, a revision [I-D.ietf-uuidrev-rfc4122bis] of the
> >>    UUID standard document is being worked on and is likely to 
> >>    introduce new UUID versions and best practices to generate global
> >>    unique identifiers. 
> >> 
> >> Current: 
> >>    As of this writing, a revision [UUID] of the Universally Unique 
> >>    Identifier (UUID) Standards Track document [RFC4122] is in
> >>    progress and will likely introduce new UUID versions and
> >>    best practices for generating global unique identifiers [UUID].
> >> -->
> > 
> > At best, we could just reference the newly published RFC that currently is I-D.ietf-uuidrev-rfc4122bis? In this case we would rephrase that paragraph. Are both RFC 9953 and the UUID document get published at the same time?
> 
> 
> 5) Note that the AD will need to approve some of the updates that were made.  We will seek approval once all of the updates are complete.
> 
> —FILES— 
> The updated XML file is here:
>  https://www.rfc-editor.org/authors/rfc9553.xml
> 
> The updated output files are here:
>  https://www.rfc-editor.org/authors/rfc9553.txt
>  https://www.rfc-editor.org/authors/rfc9553.pdf
>  https://www.rfc-editor.org/authors/rfc9553.html
> 
> This diff file shows all changes made during AUTH48:
>  https://www.rfc-editor.org/authors/rfc9553-auth48diff.html
> 
> This diff file shows all changes made to date:
>  https://www.rfc-editor.org/authors/rfc9553-diff.html
> 
> Note that it may be necessary for you to refresh your browser to view the most recent version. Please review the document carefully to ensure satisfaction as we do not make changes once it has been published as an RFC.
> 
> Please contact us with any further updates or with your approval of the document in its current form.  We will await approvals from each author prior to moving forward in the publication process.
> 
> For the AUTH48 status of this document, please see:
>  https://www.rfc-editor.org/auth48/rfc9553
> 
> Best regards,
> RFC Editor/kc
> 
> 
> > On Mar 20, 2024, at 4:12 PM, Robert Stepanek <rsto=[e-mail]> wrote:
> > 
> > Thank your for your review. Attached is the updated document. Please see below for replies and additional remarks.
> > 
> > On Thu, Mar 7, 2024, at 3:13 AM, [e-mail] wrote:
> > 
> >> 3) <!--[rfced] Please clarify the meaning of "reducing complexity of
> >> their representation". Is the intended meaning that the
> >> attributes must be described as simple key-value pairs to 
> >> reduce complexity (option A) or to reduce complexity of the
> >> representation of the card data (option B)?
> >> 
> >> Original:
> >>    The attributes of the card data represented must be described as
> >>    simple key-value pairs, reducing complexity of their
> >>    representation.
> >> 
> >> Perhaps:
> >> A) The attributes of the card data being represented must be 
> >>    described as simple key-value pairs to reduce complexity.
> >> 
> >> or
> >> 
> >> B) The attributes of the card data must be described as simple 
> >>    key-value pairs to reduce the complexity of the representation 
> >>    of the card data.
> >> -->
> > 
> > Option B. We updated the document accordingly.
> > 
> >> 4) <!-- [rfced] The use of <tt> and <em>
> >> 
> >> a) In the html and pdf outputs, the text enclosed in <tt> is output in
> >> fixed-width font. In the txt output, there are no changes to the font,
> >> and the quotation marks have been removed. 
> >> 
> >> In the html and pdf outputs, the text enclosed in <em> is output in
> >> italics. In the txt output, the text enclosed in <em> appears with an
> >> underscore before and after.
> >> 
> >> Please review carefully and let us know if the output is acceptable or 
> >> if any updates are needed.
> >> 
> >> b) Some terms appear with and without the "<tt>" element, for example, 
> >> "@type", "Card", "version", etc. Please review and let us know if any 
> >> updates are needed for consistency.
> >> -->
> > 
> > We removed all use of <tt> in the document and replaced with quotes where appropriate.
> > 
> >> 5) <!--[rfced] Section 1.3.1. Please clarify the meaning of "qux-ishness"
> >> as no other RFCs contain this term. Is it a well-known term, or
> >> can it perhaps be rephrased for clarity?
> >> 
> >> Also, we removed the blockquote element from this text
> >> because it is not a direct quote. Please let us know 
> >> if any further updates are needed.
> >> 
> >> Original:
> >>    A Foo object has the following properties:
> >> 
> >>       qux: Number (mandatory). Defines the qux-ishness of this contact. 
> >>       The value MUST be an integer greater than 0 and less than 10.
> >> -->
> > 
> > The term "qux" is a metasyntactic variable names in computer programming (https://en.wikipedia.org/wiki/Metasyntactic_variable). We now changed this to better known metasyntactic name "baz", as in "foo bar baz". We did not use "bar" do avoid confusion with the actual English word.
> > 
> > We now use a <ul> to separate the contents of the example from the rest of the section, thanks to Alice Russo for coming up with this!
> > 
> >> 
> >> 
> >> 14) <!--[rfced] In Section 2.1.8, we updated the order of the enumerated
> >> relation types list by moving "co-resident" and "co-worker" above
> >> "colleague". The list is now in alphabetical order. Please let us
> >> know of any objections.
> >> 
> >> There are several other lists in the document. Please review and let
> >> us know if any other terms should be placed in alphabetical order.
> >> -->     
> > 
> > The list of NameComponent and AddressComponent kind values deliberately follows non-alphabetic order, they follow logical order. All other lists should sort in alphabetical order.
> > 
> >> 15) <!--[rfced] FYI: For clarity and ease of reading, we added a reference
> >> to RFC 4122 as shown below.
> >> 
> >> Original: 
> >>    As of this writing, a revision [I-D.ietf-uuidrev-rfc4122bis] of the
> >>    UUID standard document is being worked on and is likely to 
> >>    introduce new UUID versions and best practices to generate global
> >>    unique identifiers. 
> >> 
> >> Current: 
> >>    As of this writing, a revision [UUID] of the Universally Unique 
> >>    Identifier (UUID) Standards Track document [RFC4122] is in
> >>    progress and will likely introduce new UUID versions and
> >>    best practices for generating global unique identifiers [UUID].
> >> -->
> > 
> > At best, we could just reference the newly published RFC that currently is I-D.ietf-uuidrev-rfc4122bis? In this case we would rephrase that paragraph. Are both RFC 9953 and the UUID document get published at the same time?
> > 
> >> 
> >> 20) <!--[rfced] In Figure 39, is the term "autor" correct, or should it be
> >> "author"?
> >> 
> >> Original:
> >>     "titles/t1/name": "autor"
> >> -->
> > 
> > The term "autor" is OK as it exemplifies a Spanish localization. But we came to realize that "escritor" is the better translation and updated the document accordingly
> > 
> >> 
> >> 21) <!-- [rfced] We have included some specific questions about the IANA
> >> text below. In addition to responding to those questions, please
> >> review all of the IANA-related updates carefully and let us know
> >> if any further updates are needed.
> >> 
> >> a) FYI: In Section 3.5.1, we placed the "Reference or Description" entry
> >> below the "Change Controller" entry to match the order of the template
> >> at https://www.iana.org/assignments/jscontact/.
> >> 
> >> - As Table is 2 characters past the 72-character limit, may we reformat
> >> the table to fit by removing the Ref column and linking each section
> >> number to the corresponding Property Context? For an example of the output,
> >> see <https://www.rfc-editor.org/authors/rfc9553-table.pdf#table-2>.
> > 
> > Yes, please.
> > 
> >> 
> >> e) In Section 3.7.1, should the definition of "Reference" be added
> >> after "Change Controller" to match the template at
> >> https://www.iana.org/assignments/jscontact? Also, since "Initial
> >> Contents" is not included in the template, should it be removed and 
> >> made into a separate paragraph?
> > 
> > Yes, please
> > 
> >> 
> >> f) In Section 3.7.2, should the definition of "Change Controller" be
> >> added after "Until Version" to match the template at
> >> https://www.iana.org/assignments/jscontact? 
> > 
> > Yes, please.
> > 
> > 
> > Additional remarks:
> > 
> > The "@" in "@type" property is pronounced within the context of this specification and this is how all people in the working group refer to it. We rephrased this sentence to start as: "Instead, the @type property"
> > 
> > We moved "Section 1.5.2: extra" to its own section 1.7.3. for "Reserved Properties"
> > 
> > Section: 2.2.1.3. was mistakenly a subsection of the "name" property definition. It is now at the right level at 2.2.2.
> > 
> > 
> > Thank you!
> > Robert Stepanek
> > <rfc9553.xml>
> 
>