Re: [Xml-sg-cmt] [AD] Use of <u> - Re: AUTH48: RFC-to-be 9290 <draft-ietf-core-problem-details-08> for your review

["Murray S. Kucherawy" <[e-mail]>]

I must confess that it would take me longer than is reasonable to develop
the background needed to take a position, so I'm going to yield to John's
suggestion.

-MSK

On Mon, Aug 15, 2022 at 4:38 PM John R Levine <[e-mail]> wrote:

> > I’ve dropped the authors and auth48archive list from this discussion in
> case this issue has already been debated.  Please let me know if you’d like
> me to take this to the wider list.
> >
> > This document includes the following Hebrew string using <u>.
> >
> > In the XML:
> >    <t>The following example shows how the Hebrew-language string
> > <u>םולש</u> is represented.
> >
> > In the text:
> >  The following example shows how the Hebrew-language string "םולש"
> >  (HEBREW LETTER SHIN, HEBREW LETTER LAMED, HEBREW LETTER VAV, HEBREW
> >  LETTER FINAL MEM, U+05E9 U+05DC U+05D5 U+05DD) is represented.
> >
> > We discussed this presentation with the RFC XML and Style Guide change
> management (CCed) team and we’re wondering if this is the desired
> presentation?  There was discussion about whether the U+ notation and names
> should be grouped differently, for example, HEBREW LETTER SHIN (U+05E9),
> HEBREW LETTER LAMED (U+05DC)….  There was also a suggestion that the
> authors describe the U+ notation instead of xml2rfc automatically doing
> this, in an attempt to provide better explanations — for example, because
> Hebrew is read RTL, should the U+ notation be described RTL?  Using <
> translate.google.com>, the RTL string means “peace” while the LTR version
> means “three”.  Has this already been discussed?  Are changes needed?  Do
> you want to encourage explanatory text?
>
> Under the circumstances, particularly since the word makes sense in
> either direction, I would ask the authors to reword the sentence to make
> it clear which one they mean, and also whether they think the Unicode
> names or the hex codes would be useful to readers.
>
> R's,
> John
>
>
>
> >> On Aug 4, 2022, at 12:59 PM, [e-mail] wrote:
> >>
> >> Authors,
> >>
> >> While reviewing this document during AUTH48, please resolve (as
> necessary) the following questions, which are also in the XML file.
> >>
> >> 1) <!-- [rfced] Please note that the title of the document has been
> >>     updated as follows:
> >>
> >> Abbreviations have been expanded per Section 3.6 of RFC 7322 (“RFC
> >> Style Guide”). Please review.
> >>
> >> Original:
> >> Concise Problem Details For CoAP APIs
> >>
> >> Current:
> >> Concise Problem Details for Constrained Application Protocol (CoAP) APIs
> >> -->
> >>
> >>
> >> 2) <!--[rfced] *Thomas - we note your organization has been indicated as
> >>     "Arm Limited" and "ARM" in recently published RFCs.  Please let
> >>     us know if/how "arm" should be updated.-->
> >>
> >>
> >> 3) <!--[rfced] Is this sentence redundant with regard to the use of
> >>     "information...is sometimes not sufficient to convey enough
> >>     information"?
> >>
> >> Original:
> >> REST response status information such as CoAP response codes
> >> (Section 5.9 of [RFC7252]) is sometimes not sufficient to convey
> >> enough information about an error to be helpful.
> >>
> >> -->
> >>
> >>
> >> 4) <!-- [rfced] Regarding the SVG in this document, please see the
> >>     warning below when generating HTML output. May the attributes be
> >>     updated so that the figure can scale?
> >>
> >> Warning: Found SVG with width or height specified, which will make the
> >> artwork not scale. Specify a viewBox only to let the artwork scale.
> >>
> >> Current:
> >> artwork type="svg" align="center"><svg
> >> xmlns="http://www.w3.org/2000/svg" version="1.1" height="256"
> >> width="288" viewBox="0 0 288 256" class="diagram" text-anchor="middle"
> >> font-family="monospace" font-size="13px"
> >> -->
> >>
> >>
> >> 5) <!--[rfced] This document uses pointers to section numbers of STDs.
> >>
> >> (Section 5.1 of [STD66])
> >> as per Section 5 of [STD66]
> >> per Section 5.1.3 of [STD66]
> >> (see Section 5.3.2 of [STD94])
> >> Section 6.2 of [STD94]
> >>
> >> As STDs may contain more than one RFC in the future, should the
> >> reference entries actually point to the individual RFCs?  Or is an
> >> update like the following desirable?
> >>
> >> (Section 5.1 of RFC 3986 [STD66])
> >> as per Section 5 of RFC 3986 [STD66].
> >> per Section 5.1.3 of RFC 3986 [STD66]
> >> (see Section 5.3.2 of RFC 8949 [STD94]).
> >> Section 6.2 of RFC 8949 [STD94].
> >> -->
> >>
> >>
> >> 6) <!--[rfced] The verb "persist" is intransitive (takes no object).
> >>     Please review this text and let us know how we may rephrase.
> >>
> >> Original:
> >>   To support the use case of message body
> >>   persistence without support by the problem-details generator, the
> >>   entity that persists the Concise Problem Details data item can copy
> >>   over the CoAP response code that it received on the CoAP level.
> >> -->
> >>
> >>
> >> 7) <!--[rfced] May we replace the slashes with "and" or "or" for
> clarity?
> >>
> >> Original:
> >> When storing the data item for future use or forwarding it to other
> >> consumers, it is strongly RECOMMENDED to retain the unrecognized
> >> entries; exceptions might be when storage/forwarding occurs in a
> >> different format/protocol that cannot accommodate them or when the
> >> storage/forwarding function needs to filter out privacy-sensitive
> >> information and for that needs to assume unrecognized entries might be
> >> privacy-sensitive.
> >>
> >> Suggested:
> >> When storing the data item for future use or forwarding it to other
> >> consumers, it is strongly RECOMMENDED to retain the unrecognized
> >> entries; exceptions might be when storage or forwarding occurs in a
> >> different format or protocol that cannot accommodate them or when the
> >> storage and forwarding function needs to filter out privacy-sensitive
> >> information and for that needs to assume unrecognized entries might be
> >> privacy-sensitive.
> >> -->
> >>
> >>
> >> 8) <!--[rfced] May we replace the slashes with "and" or "or" for
> clarity?
> >>
> >> Original:
> >> Note that the URI given for the extension is for identification
> >> purposes only and, even if dereferenceable in principle, it MUST NOT be
> >> dereferenced in the normal course of handling problem details
> >> (i.e., outside diagnostic/debugging procedures involving humans).
> >>
> >> Suggested:
> >> Note that the URI given for the extension is for identification
> >> purposes only and, even if dereferenceable in principle, it MUST NOT be
> >> dereferenced in the normal course of handling problem details
> >> (i.e., outside diagnostic and debugging procedures involving humans).
> >> -->
> >>
> >>
> >> 9) <!--[rfced] This text is difficult to parse.  Perhaps breaking up
> this
> >>     sentence would be helpful for the reader?  In particular, we had
> >>     trouble with "the keys...are defined specifically to the
> >>     identifier": is the identifier the receiver of the definition or
> >>     is the intended meaning that the keys are customized by
> >>     identifier?  Please rephrase.
> >>
> >> Original:
> >>   In summary, the keys for the maps used inside Custom Problem Detail
> >>   entries are defined specifically to the identifier of that Custom
> >>   Problem Detail entry, the documentation of which defines these
> >>   internal entries, typically chosen to address a given application
> >>   domain.
> >>
> >>
> >> -->
> >>
> >>
> >> 10) <!--[rfced] We had the following questions about this text from
> >>     Section 5.
> >>
> >> a) Please review our update to the following to ensure we have
> >> captured your intent.
> >>
> >> Original:
> >> ...they equally apply to the problem detail entry definitions used
> >> here Section 3;
> >>
> >> Current:
> >> ...they equally apply to the problem detail entry definitions used
> >> in Section 3;
> >>
> >> b) Who does "they" refer to here?
> >>
> >>   ...in summary: both when defining new detail entries, and when
> >>   actually generating a Concise Problem Details data item, care needs
> >>   to be taken that they do not leak sensitive information.
> >>
> >> -->
> >>
> >>
> >> 11) <!--[rfced] May we update the occurrences of [RFC7807] or RFC 7807
> as
> >>     an adjective as follows?
> >>
> >> Originals:
> >> ...for new RFC 7807 problem types...
> >>
> >> Carry RFC 7807 problem  details in a Concise Problem Details data
> item...
> >>
> >> On certain occasions, it will be necessary to carry ("tunnel")
> >> [RFC7807] problem details in a Concise Problem Details data item.
> >>
> >> To carry an [RFC7807] problem details JSON object in a Concise
> >> Problem Details data item, ...
> >>
> >> Move the values for "title", "detail", and "instance", if present,
> >> from the [RFC7807] problem details to the equivalent Standard Problem
> >> Detail entries.
> >>
> >> ...in the converted [RFC7807] problem details object to the Custom
> >> Problem Details map unchanged.
> >>
> >> Suggesteds:
> >> ...for new problems types as described in RFC 7807...
> >>
> >> Carry problem  details as described in RFC 7807 in a Concise Problem
> Details data item
> >>
> >> On certain occasions, it will be necessary to carry ("tunnel")
> >> problem details (from RFC 7807) in a Concise Problem Details data item.
> >>
> >> To carry a problem details JSON object (from RFC 7807) in a Concise
> >> Problem Details data item, ...
> >>
> >>
> >> Move the values for "title", "detail", and "instance", if present,
> >> from the problem details from RFC 7807 to the equivalent Standard
> Problem
> >> Detail entries.
> >>
> >> ...in the converted problem details object from RFC 8707 to the Custom
> >> Problem Details map unchanged.
> >>
> >> -->
> >>
> >>
> >> 12) <!--[rfced] Note that we updated the title of this registry to match
> >>     use by IANA (see
> >>
> https://www.iana.org/assignments/core-parameters/core-parameters.xhtml#core-custom-problem-detail-ke
> >> ys).
> >>
> >> Old:
> >> 6.1.  Standard Problem Detail Key Registry
> >>
> >> New:
> >> 6.1.  Standard Problem Detail Keys Registry
> >> -->
> >>
> >>
> >> 13) <!--[rfced] Please note that "Change Controller" is not a field in
> the
> >>     subregistry listed for "Standard Problem Detail Keys" or "Custom
> >>     Problem Detail Keys" at
> >>     https://www.iana.org/assignments/core-parameters/.  Please review
> >>     and let us know if any further updates are necessary to the
> >>     document or the registry itself for either of these subregistries.
> >>
> >> -->
> >>
> >>
> >> 14) <!--[rfced] Because the "Standard Problem Detail Keys" subregistry
> >>     uses "Specification Required" as a Registration Procedure, will
> >>     the reader know who "The expert" is in the text below?  Or should
> >>     the Registration Procedure be updated?  (We note "Custom Problem
> >>     Detail Keys" uses "Expert Review"...).
> >>
> >> Original:
> >>   The expert is requested to assign the shortest key values (1+0 and
> >>   1+1 encoding) to registrations that are likely to enjoy wide use and
> >>   can benefit from short encodings.
> >> -->
> >>
> >>
> >> 15) <!--[rfced] As we assume you are talking about registration
> >>     procedures, we have made "first-come-first-served" be "First Come
> >>     First Served" to match the use in RFC 8126. Please let us know if
> >>     this is not as intended.
> >>
> >> Original:
> >> The expert is instructed to attempt making the registration
> >> experience as close to first-come-first-served as reasonably
> >> achievable, ...
> >>
> >> Current:
> >> The expert is instructed to attempt making the registration experience
> >> as close to First Come First Served as reasonably achievable, ...
> >>
> >> -->
> >>
> >>
> >> 16) <!--[rfced] Please confirm that this text is intended to appear in
> >>     Section 6.2.  We see the same text in Section 6.1, but the Key
> >>     Values in both registries seem quite different.
> >>
> >> Original:
> >>   The expert is requested to assign the shortest key values (1+0 and
> >>   1+1 encoding) to registrations that are likely to enjoy wide use and
> >>   can benefit from short encodings.
> >> -->
> >>
> >>
> >> 17) <!--[rfced] We note that the Media Type registration in Section 6.3
> is
> >>     missing some of the fields from the template set out in RFC 6838.
> >>
> >> Specifically, we do not see "Additional Information:" and its
> >> subfields (Deprecated alias names for this type, Magic number(s), File
> >> extension(s), and Macintosh file type code(s)).  Note that RFC 6838
> >> gives advice regarding these fields when empty.  Please let us know
> >> if/how we may update.
> >>
> >> Note that we will communicate any updates to this text to IANA for
> >> them to update
> >>
> https://www.iana.org/assignments/media-types/application/concise-problem-details+cbor
> >> accordingly prior to pubication.
> >> -->
> >>
> >>
> >> 18) <!--[rfced] We note that the CoAP Content-Formats registry
> >>     (
> https://www.iana.org/assignments/core-parameters/core-parameters.xhtml#content-formats
> )
> >>     has the following headings:
> >>
> >> Media Type
> >> Encoding
> >> ID
> >> Reference
> >>
> >> This document mentions in a comment (marked to be removed):
> >>
> >>   In the registry as defined by Section 12.3 of [RFC7252] at the time
> >>   of writing, the column "Content-Type" is called "Media type" and the
> >>   column "Content Coding" is called "Encoding".
> >>
> >> Should Table 4 be updated to use these same headings?  Or is there a
> >> reason for the disparity between this document and the IANA
> >> registry?-->
> >>
> >>
> >> 19) <!--[rfced] We do not see mention of Appendix A in the CBOR Tags
> >>     registry
> >>     (https://www.iana.org/assignments/cbor-tags/cbor-tags.xhtml)
> >>     "Reference" column as requested in Section 6.5 of this document.
> >>     Please let us know if an update to this document or IANA is
> >>     necessary.-->
> >>
> >>
> >> 20) <!--[rfced] Please note that we have moved the annotations from the
> Unicode references into the body
> >> of the document that discusses Unicode.  -->
> >>
> >>
> >> 21) <!-- [rfced] Please review whether any of the notes in this document
> >>     should be in the <aside> element. It is defined as "a container
> >>     for content that is semantically less important or tangential to
> >>     the content that surrounds it"
> >>     (https://xml2rfc.tools.ietf.org/xml2rfc-doc.html#name-aside-2).
> >> -->
> >>
> >>
> >> 22) <!-- [rfced] FYI - address munging is not allowed per Section 4.12
> of
> >>     RFC 7322 "RFC Style Guide"; we have updated Peter's email address
> >>     as follows:
> >>
> >> Original:
> >> poccil14 at gmail dot com
> >>
> >> Changed to:
> >> [e-mail]
> >>
> >> -->
> >>
> >>
> >> 23) <!-- [rfced] We have several questions about the names of data
> items,
> >>     keys, and entries throughout the text.  Please review and let us
> >>     know how we may make these more uniform.
> >>
> >> a) Please review the uses below and let us know if any updates should
> >> be made as relates to the use of these seemingly related terms:
> >>
> >> ...defines a concise "problem detail"...
> >> Concise Problem Details data item
> >> ...beyond concise problem details may adopt the tag defined here.)
> >>
> >>
> >> b) We see both "Custom Problem Detail" and "Custom Problem Details"
> >> (plural).  May we default to the singular?  Some related use cases
> >> that may warrant review follow, which may also illuminate some capping
> >> issues:
> >>
> >> ...register such a custom problem detail entry to receive a ...
> >> Custom Problem Detail entry
> >> Custom Problem Details entry (see Appendix B)
> >> Custom Problem Detail key
> >> Custom Problem Details map
> >>
> >> c) May we update "Problem Details data item" to read as "Custom
> >> Problem Detail data item" in the following text?
> >>
> >> Original:
> >>   Applications may extend the Problem Details data item with
> >>   additional entries to convey additional, application-specific
> >>   information.
> >>
> >> Perhaps:
> >>   Applications may extend the Custom Problem Detail data item with
> >>   additional entries to convey additional, application-specific
> >>   information.
> >>
> >> d) We will lowercase "Entries" to match use of other similar terms for
> >> "Standard Problem Detail Entries" (i.e., making it "Standard Problem
> >> Detail entries").
> >>
> >> e) Please review the capitalization of "problem details" in the two
> >> following sentences as relates to the JSON object.  SHould this be
> >> made consistent?
> >>
> >> Original:
> >>   To carry an [RFC7807] problem details JSON object in a Concise
> >>   Problem Details data item,...
> >>
> >> and
> >>
> >> The inverse direction, carrying Concise Problem Details in a Problem
> >>   Details JSON object
> >> -->
> >>
> >>
> >> 24) <!--[rfced] Throughout the document, we see use of similar terms
> that
> >>     may be inconsistent.  Please review these occurrences and let us
> >>     know if any updates are necessary.
> >>
> >> a) Should mentions of the follow be made uniform?
> >>
> >> tag38
> >> tag 38
> >> CBOR Tag 38
> >> CBOR tag 38
> >>
> >> b) The following uses seem similar, but have some variances in
> quotation and parenthetical use.  Please review for uniformity.
> >>
> >> The "title" string
> >>
> >> unadorned text string (not using tag 38) vs. unadorned text string vs.
> >> unadorned CBOR text string (text)
> >>
> >> language-tagged text string (tag38)
> >> language-tagged text strings in COBR
> >> language-tagged strings
> >>
> >> UTF-8 text string (major type 3)
> >>
> >> c) How should member names be treated?  We see some names in double
> >> quotes:
> >>
> >> "base-uri" member vs. base-uri member
> >> "response-code" member vs. the response-code member (also
> "response-code" value)
> >>
> >>
> >> -->
> >>
> >>
> >> 25) <!-- [rfced] Please review the "Inclusive Language" portion of the
> online
> >> Style Guide <
> https://www.rfc-editor.org/styleguide/part2/#inclusive_language>
> >> and let us know if any changes are needed. -->
> >>
> >>
> >> Thank you.
> >>
> >> RFC Editor/st/mf
> >>
> >> *****IMPORTANT*****
> >>
> >> Updated 2022/08/04
> >>
> >> RFC Author(s):
> >> --------------
> >>
> >> Instructions for Completing AUTH48
> >>
> >> Your document has now entered AUTH48.  Once it has been reviewed and
> >> approved by you and all coauthors, it will be published as an RFC.
> >> If an author is no longer available, there are several remedies
> >> available as listed in the FAQ (https://www.rfc-editor.org/faq/).
> >>
> >> You and you coauthors are responsible for engaging other parties
> >> (e.g., Contributors or Working Group) as necessary before providing
> >> your approval.
> >>
> >> Planning your review
> >> ---------------------
> >>
> >> Please review the following aspects of your document:
> >>
> >> *  RFC Editor questions
> >>
> >>   Please review and resolve any questions raised by the RFC Editor
> >>   that have been included in the XML file as comments marked as
> >>   follows:
> >>
> >>   <!-- [rfced] ... -->
> >>
> >>   These questions will also be sent in a subsequent email.
> >>
> >> *  Changes submitted by coauthors
> >>
> >>   Please ensure that you review any changes submitted by your
> >>   coauthors.  We assume that if you do not speak up that you
> >>   agree to changes submitted by your coauthors.
> >>
> >> *  Content
> >>
> >>   Please review the full content of the document, as this cannot
> >>   change once the RFC is published.  Please pay particular attention to:
> >>   - IANA considerations updates (if applicable)
> >>   - contact information
> >>   - references
> >>
> >> *  Copyright notices and legends
> >>
> >>   Please review the copyright notice and legends as defined in
> >>   RFC 5378 and the Trust Legal Provisions
> >>   (TLP – https://trustee.ietf.org/license-info/).
> >>
> >> *  Semantic markup
> >>
> >>   Please review the markup in the XML file to ensure that elements of
> >>   content are correctly tagged.  For example, ensure that <sourcecode>
> >>   and <artwork> are set correctly.  See details at
> >>   <https://authors.ietf.org/rfcxml-vocabulary>.
> >>
> >> *  Formatted output
> >>
> >>   Please review the PDF, HTML, and TXT files to ensure that the
> >>   formatted output, as generated from the markup in the XML file, is
> >>   reasonable.  Please note that the TXT will have formatting
> >>   limitations compared to the PDF and HTML.
> >>
> >>
> >> Submitting changes
> >> ------------------
> >>
> >> To submit changes, please reply to this email using ‘REPLY ALL’ as all
> >> the parties CCed on this message need to see your changes. The parties
> >> include:
> >>
> >>   *  your coauthors
> >>
> >>   *  [e-mail] (the RPC team)
> >>
> >>   *  other document participants, depending on the stream (e.g.,
> >>      IETF Stream participants are your working group chairs, the
> >>      responsible ADs, and the document shepherd).
> >>
> >>   *  [e-mail], which is a new archival mailing list
> >>      to preserve AUTH48 conversations; it is not an active discussion
> >>      list:
> >>
> >>     *  More info:
> >>
> https://mailarchive.ietf.org/arch/msg/ietf-announce/yb6lpIGh-4Q9l2USxIAe6P8O4Zc
> >>
> >>     *  The archive itself:
> >>        https://mailarchive.ietf.org/arch/browse/auth48archive/
> >>
> >>     *  Note: If only absolutely necessary, you may temporarily opt out
> >>        of the archiving of messages (e.g., to discuss a sensitive
> matter).
> >>        If needed, please add a note at the top of the message that you
> >>        have dropped the address. When the discussion is concluded,
> >>        [e-mail] will be re-added to the CC list and
> >>        its addition will be noted at the top of the message.
> >>
> >> You may submit your changes in one of two ways:
> >>
> >> An update to the provided XML file
> >> — OR —
> >> An explicit list of changes in this format
> >>
> >> Section # (or indicate Global)
> >>
> >> OLD:
> >> old text
> >>
> >> NEW:
> >> new text
> >>
> >> You do not need to reply with both an updated XML file and an explicit
> >> list of changes, as either form is sufficient.
> >>
> >> We will ask a stream manager to review and approve any changes that seem
> >> beyond editorial in nature, e.g., addition of new text, deletion of
> text,
> >> and technical changes.  Information about stream managers can be found
> in
> >> the FAQ.  Editorial changes do not require approval from a stream
> manager.
> >>
> >>
> >> Approving for publication
> >> --------------------------
> >>
> >> To approve your RFC for publication, please reply to this email stating
> >> that you approve this RFC for publication.  Please use ‘REPLY ALL’,
> >> as all the parties CCed on this message need to see your approval.
> >>
> >>
> >> Files
> >> -----
> >>
> >> The files are available here:
> >>   https://www.rfc-editor.org/authors/rfc9290.xml
> >>   https://www.rfc-editor.org/authors/rfc9290.html
> >>   https://www.rfc-editor.org/authors/rfc9290.pdf
> >>   https://www.rfc-editor.org/authors/rfc9290.txt
> >>
> >> Diff file of the text:
> >>   https://www.rfc-editor.org/authors/rfc9290-diff.html
> >>   https://www.rfc-editor.org/authors/rfc9290-rfcdiff.html (side by
> side)
> >>
> >> Diff of the XML:
> >>   https://www.rfc-editor.org/authors/rfc9290-xmldiff1.html
> >>
> >> The following files are provided to facilitate creation of your own
> >> diff files of the XML.
> >>
> >> Initial XMLv3 created using XMLv2 as input:
> >>   https://www.rfc-editor.org/authors/rfc9290.original.v2v3.xml
> >>
> >> XMLv3 file that is a best effort to capture v3-related format updates
> >> only:
> >>   https://www.rfc-editor.org/authors/rfc9290.form.xml
> >>
> >>
> >> Tracking progress
> >> -----------------
> >>
> >> The details of the AUTH48 status of your document are here:
> >>   https://www.rfc-editor.org/auth48/rfc9290
> >>
> >> Please let us know if you have any questions.
> >>
> >> Thank you for your cooperation,
> >>
> >> RFC Editor
> >>
> >> --------------------------------------
> >> RFC9290 (draft-ietf-core-problem-details-08)
> >>
> >> Title            : Concise Problem Details For CoAP APIs
> >> Author(s)        : T. Fossati, C. Bormann
> >> WG Chair(s)      : Jaime Jimenez, Marco Tiloca
> >> Area Director(s) : Murray Kucherawy, Francesca Palombini
> >>
> >>
> >
> >
>
> Regards,
> John Levine, [e-mail], Taughannock Networks, Trumansburg NY
> Please consider the environment before reading this e-mail. https://jl.ly
>