xml2rfc
xml2rfc copied to clipboard
ietf-tools
Need better hangText crossreference format
type_enhancement | by [email protected]
In RFC terminology section, terms are usually defined via a hangText, eg:
<t hangText="ACP (ANI/AN) Domain Certificate:" anchor="domcert-def">
Often it is required for one terms explanation to have an xref to another term. But there is no good XREF option to do this because there seems to be no way to refer to the actual hanging text. Instead, the reference will have to show something else, like the section number or so, which is all useless.
The best option i found is like this:
<xref target="domcert-def" format="title">->"ACP domain certificate"</xref>
Because i can not let the xref generate the referred text, the xref has to repeat that whole text, and i also need to write the typical way you show a reference to another term (->).
But this format still creates a redundant () at the end, and IESG reviewers did not like that.
Maybe i am overlooking something, but i spent a already way too much time just to get to this point of understanding.
example from draft-ietf-anima-autonomic-control-plane-16
This is against xml2rfc.tools.ietf.org. That web page only says v2, so i am just assuming it is 2.5.x.
Issue migrated from trac:347 at 2022-02-05 12:44:30 +0000
@[email protected] commented
I agree that the formatter should handle that better.
In my formatter, it seems to work right, see file:///C:/projects/xml2rfc/v3test.html#n-referring-to-list-items.
@[email protected] commented
This is OBE for v2, but there may still be an analogous enhancement to be made in v3.
Missing attachments: (added .txt to overcome GitHub rules).
xref-tests.txt
xref-tests.html.txt
xref-tests.xml.txt
@reschke, @rjsparks: Is this still a valid issue? If so what are the enhancements required?
The original issue description is hard to read; maybe some formatting was lost?
I edited the original description to put the content in blockquotes.
If you suspect you see something broken try to edit it. if it won't let you edit it, try to quote reply and you should see the pre-markdown bits.
We solved a related problem in https://www.ietf.org/archive/id/draft-ietf-core-href-10.html#c-scheme -- see how the items are defined in Section 2 and referenced in Section 3.
See https://github.com/core-wg/href/blob/main/draft-ietf-core-href.md#constraints-constraints (setup) and https://github.com/core-wg/href/blob/main/draft-ietf-core-href.md#creation-and-normalization (reference) for the source. https://www.ietf.org/archive/id/draft-ietf-core-href-10.xml if you prefer XML.
Well, this does not work too well with definition lists:
{:#ant} ant (en):
: Ameise (de)
{:#bat} bat (en):
: Fledermaus (de), afraid of {{<<cat1}}
{:#cat1} cat (en):
: Katze (de), does not eat {{<<ant}}
<dl>
<dt anchor="ant">ant (en):</dt>
<dd>
<t>Ameise (de)</t>
</dd>
<dt anchor="bat">bat (en):</dt>
<dd>
<t>Fledermaus (de), afraid of <xref format="title" target="cat1"/></t>
</dd>
<dt anchor="cat1">cat (en):</dt>
<dd>
<t>Katze (de), does not eat <xref format="title" target="ant"/></t>
</dd>
</dl>
➔
ant (en): Ameise (de)
bat (en): Fledermaus (de), afraid of cat1
cat (en): Katze (de), does not eat ant
So it uses the anchor as the title (!).
Indeed.
See rfcxml.xslt's output at
https://greenbytes.de/tech/webdav/xref-tests-rfc7991.html#rfc.section.2.7.2
and xml2rfc's
file:///C:/projects/xml2rfc/xref-tests-rfc7991.xml2rfcv3.html#section-2.7.2
for format=title, rfcxml.xslt takes the text content instead of the anchor name.
See also https://github.com/rfc-format/draft-iab-xml2rfc-v3-bis/issues/109#issuecomment-641145352