User Tools

Site Tools


v3_guidance_received

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, the schema documentation, or the FAQ.)

  1. 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)
  2. 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.)
  3. questions about <relref> handling and entity handling (Aug 2020)
    • –> usage of <relref> should be replaced by <xref>
    • –> odd entities defined by the authors may be replaced by the equivalent text.
  4. 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)
  5. 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)
  6. 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)
  7. 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)
  8. locations where non-ASCII chars may appear (March 2020)
  9. 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)
  10. OK to leave <sourcecode>'s type empty? (Jan 2020)
    • –> yes.
  11. What element should be used for equations or formulas? (Jan 2020)
    • –> <artwork>
  12. how to set <artwork> type (Nov 2019)
  13. 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 nested_lists (internal)
  14. What is best practice for <refcontent> usage (as opposed to <seriesInfo>)? (Nov 2019)
  15. 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)
  16. What is the recommended placement for <seriesInfo>? (Sept 2019 and June 2020)
v3_guidance_received.txt · Last modified: 2021/08/04 20:52 by sginoza