Support for eref + section references

[ioggstream]

I wish

To define keywords that reference specification sections.

normative:
    SEMANTICS: I-D.ietf-httpbis-semantics

...

## Notational Conventions
{::boilerplate bcp14-tagged}

The definitions of  "representation", "selected representation", "representation
data" are to be interpreted as described in {{SEMANTICS}}.

[representation]: {{Section 3.2 of SEMANTICS}}
[selected representation]: {{RFC7231}}

## My Spec

This specification requires that a  [representation] and [selected representation] blablabl

Instead

If I try to build the code above, the parser (reasonably) expects to have an URL, thus returning

** space(s) in cross-reference '{{Section 3.2 of SEMANTICS}}' -- are you trying to use section references?

and the xml is rendered as

<eref target="{{Section 3.2 of SEMANTICS}}">representation</eref>, 
...
<eref target="{{RFC7231}}">selected representation </eref>, 

Note

If this feature is of any interests, I could possibly help. Just point me to the relevant code :)

[cabo]

Interesting! I'll have a look at why there is no processing of section reference in the the link definition. (What is SEMANTICS? An RFC?)

[ioggstream]

@cabo thanks! I updated the issue. Let me know if/how I can help:

• in normative I have SEMANTICS: I-D.ietf-httpbis-semantics so it is an RFC refernce.
• the output is similar, but without errors just referencing {{RFC7231}}
• I attached the xml output <eref target="{{Section 3.2 of SEMANTICS}}">representation</eref>, ... <eref target="{{RFC7231}}">selected representation </eref>,

[ioggstream]

@cabo iiuc (not a ruby expert)

• the link definition is processed in a static method RFC2629Kramdown.idref_cleanup
• which is called by Element.rfc2629_fix

and is not processed by parse_xref (which processes {{Section ... of ...}}).

Inspecting convert_p I found that [ref]: url always create a simple kd:a instead of a kd:xref .

** convert_p: <kd:p options={:location=>75} children=[
<kd:text value="A non working " options={:location=>75}>, 
<kd:a attr={"href"=>"{{Section 3.0 of HTTP}}"} options={:location=>75, :ial=>nil} children=[
   <kd:text value="section_of" options={:location=>75}>
]>
]>

HTH, R.

[cabo]

Indeed, this would be some special processing we would add to convert_a. We already do special processing on targets starting with #. We probably would need to funnel the target value through a recursive parser instance and take apart the result...

[ioggstream]

It would be great to leave the job to xref or relref, eg

<relref target="HTTP" section="3" displayFormat="bare" >Content-Type</relref>

but iiuc it generates by design the following html

<a href="https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-semantics-19#section-3" class="relref">3</a>
(<a href="https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-semantics-19#section-3" class="relref">section_of</a>)

Referencing documents without the section can be done this way, but it's not very useful.

<xref target="HTTP" format="none" >Content-Type</xref>

A solution compliant with xml2rfc v3 probably needs to compute the target url and set it into an <eref/>. Dunno if there are better solutions.

PS: I mocked it in convert_a but not sure it's the right place.

       def convert_a(el, indent, opts)
         gi = el.attr.delete('gi')
         res = inner(el, indent, opts)
         target = el.attr['target']
         if target[0] == "#"     # handle [](#foo) as xref as in RFC 7328
           el.attr['target'] = target = target[1..-1]
           if target.downcase == res.downcase
             res = ''            # get rid of raw anchors leaking through
           end
           gi ||= "xref"
+        elsif target[0..1] == "{{" && target[-2..-1] == "}}"
+          el.attr["section"] = "3"
+          el.attr["target"] = "HTTP"
+          el.attr["displayFormat"] = "bare"
+          gi ||= "relref"

[cabo]

1.6.3 has some very basic support for xrefs on the right hand side of link definitions. The effect may be somewhat surprising, so please play around whith that. The closest I could find was:

[apple]: {{3 (foo)<SEMANTICS}}

apple is the name of the link you use in the markdown text. 3 should be the section number (but is not translated; still figuring that out). foo is what you find in the rendered text -- with a link in the HTML, and totally unadorned in the TXT.

Not quite what you need yet, but as I was creating a new version for another reason, I thought I might want to push this with that.

[ioggstream]

The following seems to work with 1.6.4 :)

@LPardue @martinthomson WDYT?

Hi [representation] bar baz


[representation]: {{section-3.2 (representation)<SEMANTICS}}

generates

Hi <xref section="representation" relative="#section-3.2" sectionFormat="bare" target="SEMANTICS"/>

[martinthomson]

Hmm, that isn't really the XML you want there. You probably want...

<xref target="SEMANTICS" section="3.2" format="none">representation</xref>

Though I'm not sure how that renders.

[ioggstream]

Hi @martinthomson

<xref target="SEMANTICS" section="3.2" format="none">representation</xref>

Though I'm not sure how that renders.

It seems it doesn't render :( iiuc format="none" can't be used with "section", or something like that (xml2rfc feature).

tmp.xml(65): Error: Found sectionFormat="of" with blank derivedContent

[ioggstream]

@martinthomson given that the XML you suggest does not seem to work with xml2rfc, can we agree that the XML generated via https://github.com/cabo/kramdown-rfc/issues/155#issuecomment-1060882076 is a reasonable output ?

This would allow using .md files instead of xml and will improve the reader experience.

[martinthomson]

If you are looking to change this tool, why not also consider changes to xml2rfc as well?

[cabo]

I'm not entirely sure what the objective is, but the XML looks good to me. The contorted markdown needed to generate this does not make me proud, but it seems workable.

[ioggstream]

@cabo the goal is to define once in a .md the reference to a specific link/keyword instead of repeating every time the URL. This is a major simpllification for editors.

@martinthomson why do you think the XML is problematic?

[martinthomson]

You proposed this:

<xref section="representation" relative="#section-3.2" sectionFormat="bare" target="SEMANTICS"/>

The relative and section attributes should be replaced with a section="3.2". You managed to get what you wanted, but you did that by abusing the semantics of the attributes.

What I think we want is to use <xref ... format="none">text you want to display</xref> using appropriate values for section and target. The cost is that xml2rfc would need to be updated, but for something like this it would be worthwhile.

[ioggstream]

If it's just a matter of code, I think it's ok.

I don't know if this change in xmlrfc requires to modify the specifications too: this might be more complex.

[cabo]

I think what we should do is, after IETF 114, is to create a convincing bug report on xml2rfc. Once we know how that goes, we can make sure that kramdown-rfc can generate the desired syntax from something more palatable than we have now. Until then, we can continue to use the slight abomination that works today.