RSE Wiki Archive

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
===== v3 guidance received =====

This is a summary of guidance received; it is not a comprehensive list.

"–>"  indicates the takeaways of the guidance received.\\ "See" indicates where this info is captured in more detail. (All items are already captured in this wiki, [[https://xml2rfc.tools.ietf.org/xml2rfc-doc.html|the schema documentation]], or the [[https://www.rfc-editor.org/materials/FAQ-xml2rfcv3.html|FAQ]].)

  -  artwork vs. sourcecode determination (revisited Sept 2020)
    * –> <artwork> contains a diagram or similar. (“character-based art, diagrams of message layouts, and so on” to quote https://xml2rfc.tools.ietf.org/xml2rfc-doc.html)
    * –> <sourcecode> contains code that compiles or does not; it can be one of the preferred type values or no type at all; this includes snippets of code or pseudocode.
    * See [[v3_artwork_tips]] (internal)
  -  guidance on <contact> element (April and Dec. 2020)
    * –> use it for any individual’s name, regardless of whether it requires non-ASCII characters, and regardless of whether the individual is already tagged as <author> elsewhere. [original practice]
      * -> Feb 2021: guidance revised to only use <contact> in Contributors, Acks, IAB Members, and "Contact" in IANA Considerations. Also, use when needed to hold an individual's name that contains non-ASCII characters.
    * Henrik advised using it for any organization’s name. 
      * -> [This does not match current practice. RPC will not start using it in that manner.]
      * -> Feb 2021: Confirmed not using it for organizations. (Exception: if the org is the source of the doc.)
    * See [[v3_examples#contributors_using_contact]] and [[v3_examples#acknowledgments_using_contact]] (internal)
  -  questions about <relref> handling and entity handling (Aug 2020)
    * –> usage of <relref> should be replaced by <xref>
      * <relref> is deprecated per [[https://xml2rfc.tools.ietf.org/xml2rfc-doc.html#name-elements-from-v2-that-have-b|Section 3.2 of schema doc]]
    * –> odd entities defined by the authors may be replaced by the equivalent text.
  -  general guidance on choosing the right element for specific content (June 2020)
     * –> Considerations when choosing appropriate markup
       * Aesthetic: Does the output look right?
       * Semantic: Is it an accurate label for the data?
       * Does it match precedent? (i.e., the markup of similar text in past v3 RFCs.)
       * [Perhaps also worth including ease/efficiency, i.e., what is simpler?]
     * See [[v3_tricky_ones]] (internal)
  -  guidance on <svg> attributes (June 2020 questions from Jean)
    * –> for scaling issues, remove height and width attributes; increase 3rd number in viewBox.
    * See [[svg]] (internal)
  -  using <ul empty="true"> to get indentation should be avoided (June 2020)
     * -> In some cases, use other markup to attain the desired effect (indent attribute was added to <t>). 
     * -> It’s not always nec. to replicate the indentation in the original I-D. (editorial judgment)
     * See [[v3_when_to_use_indent_attribute]] (internal)
  -  questions about postal address handling (April and July 2020)
    * –> template for mail when RPC can’t replicate the postal address provided by the author: "The discrepancy is due to xml2rfc now using a library to display addresses in a country-specific manner”
    * See [[format_of_addresses]] (internal)
  -  locations where non-ASCII chars may appear (March 2020)
      * –> Besides <author> and <contact>'s child elements and attributes, non-ASCII chars can appear in <artwork>, <sourcecode>, and <u>.
      * See FAQ: [[https://www.rfc-editor.org/materials/FAQ-xml2rfcv3.html#name-how-do-i-insert-non-ascii-c|How do I insert non-ASCII characters?]]
  -  guidance on <br> vs. &br; (Jan and May 2020)
    * –> use <br> not &br;
    * –> use <br> sparingly; there typically should be other markup to get the desired output.
    * See [[v3_when_to_use_br]] (internal)
  -  OK to leave <sourcecode>'s type empty? (Jan 2020)
    * –> yes.
  -  What element should be used for equations or formulas? (Jan 2020)
      * –> <artwork>
  -  how to set <artwork> type (Nov 2019)
    * –> all the <artwork> we encounter is type=“ascii-art” (when it's not svg) and Henrik advised setting it explicitly.
    * –> “call-flow” and “hex-dump” should not be used, even if that’s what the artwork looks like. currently described as “not supported” in https://xml2rfc.tools.ietf.org/xml2rfc-doc.html#section-2.6.7
    * See [[v3_artwork_tips]] (internal)
   -  guidance on nested lists (July 2019)
    * –> various examples; essentially, within <li> or <dd>, you must use <t> around text that precedes a nested list.
    * See [[v3_examples#nested_lists]] (internal)
   - What is best practice for <refcontent> usage (as opposed to <seriesInfo>)? (Nov 2019)
     * See [[refcontent]] (internal)
   - What is best practice for <aside> in light of the definition in 7991 as "a container for content that is semantically less important or tangential to the content that surrounds it"? (April 2021)
     * Better to use <t> instead. (with or without "indent" attribute)
   - What is the recommended placement for <seriesInfo>? (Sept 2019 and June 2020)
     * inside <front> or outside <front>?
     * schema allows either placement. (June 2020: better for it to be outside <front>, matching v2)
     * See proposal for rewrite in https://datatracker.ietf.org/doc/html/draft-levkowetz-xml2rfc-v3-implementation-notes#section-3.1.21
RSE Wiki Archive

User Tools

Site Tools

Page Tools
