Update guidance in references-in-rfcxml.md #105
Conversation
Rearranges and adds additional information for creating/using references in RFCs
Adds text on locating BibXML URLs for xi:includes
|
@ajeanmahoney Marked this a ready-to-review, but could use some feedback on the current layout and levels of detail. Some issues I was puzzling over:
|
| <xi:include href="https://bib.ietf.org/public/rfc/bibxml9/reference.BCP.0195.xml"/> | ||
| ``` | ||
|
|
||
| ### Inserting a Subseries Reference manually |
There was a problem hiding this comment.
I don't think this needs to be covered
| # Creating the References Section | ||
| <!-- TH: Do we need a section on creating the References section? --> | ||
|
|
||
| ## Two sections: Normative and Informative References |
There was a problem hiding this comment.
Although uncommon, it's okay for a document to have just one References sections (e.g., "Normative References" or "Informative References"). This section probably isn't needed because https://authors.ietf.org/en/drafting-in-xml points to RFCXML templates and authors can see the structure there.
| # Adding reference entries to the References Section | ||
| Reference entries can be added to the References Section using two methods: | ||
| * Using an `xi:include` to automatically add citation data from the BibXML service | ||
| * manually constructing references in a [**\<reference\>**](/rfcxml-vocabulary#reference) element |
There was a problem hiding this comment.
"manually" should be capped
| ```xml | ||
| <xi:include href="https://bib.ietf.org/public/rfc/bibxml3/reference.I-D.draft-ietf-wgname-topic-17.xml"/> | ||
| <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.7372.xml"/> |
There was a problem hiding this comment.
To make this consistent, update 7372 to 7322
| # Creating a reference to a BCP (or STD) that contains multiple RFCs | ||
| Locate the reference anchor for the reference: | ||
|
|
||
| Add an [**\<xref\>**](/rfcxml-vocabulary#xref) element with the target attribute set to the reference anchor (in this case, "RFC7322"). |
There was a problem hiding this comment.
In the text above, attributes are formatted with bold, but here the target attribute doesn't have formatting
| ## Linking to multiple sections within a document | ||
| For example, `See Sections 3 and 4.` | ||
|
|
||
| Use [**\<xref\>**](/rfcxml-vocabulary#xref) with the format attribute. For example, assuming the anchors for the relevant sections match the targets: |
There was a problem hiding this comment.
the format attribute needs to be formatted in bold here
Rearranges and adds additional information for creating/using references in RFCs. Note this is still a work in progress.