Cross-reference :xrefstyle: attribute and [reftext=""] attributes are ignored

[isobering]

The RFD site appears to ignore the xrefstyle cross-reference style attribute for both the global document attribute (e.g., :xrefstyle:) and in inline cross reference macros (e.g., xref:installation[xrefstyle=short]).

Additionally, the RFD site appears to ignore the reftext attribute (e.g., [reftext="Installation"]).

In both cases, creating a cross reference displays the full ID of the target section, table, or figure, enclosed in square brackets, regardless of style attribute. This prevents us from creating cross references that just say "Table X" or "Section X".

Example: My document specifies the :xrefstyle: short attribute. I create the following table:

:xrefstyle: short

...

.RMU Connector Signals
[[table-rmu-connector-signals]]
[%header, cols="20,20,10,40"]
|===

|Pin Name
|Net Name
|I/O
|Description

|===

I create the following cross-reference:

<<table-rmu-connector-signals>> lists and describes the RMU connector signals the PSC monitors or controls.

The cross-reference should render as

Table X lists and describes the RMU connector signals the PSC monitors or controls.

Instead, the cross-reference renders as:

[table-rmu-connector-signals] lists and describes the RMU connector signals the PSC monitors or controls.

This behavior is the same for all xrefstyle options.

[benjaminleonard]

Have you got an RFD published with xrefs that I could take a look at?

[isobering]

Sure! Take a look at Section 5.1 and Section 5.2 of RFD 121 Power Shelf Controller. Those are the only sections I've put xrefs in so far.

[benjaminleonard]

Interestingly it is working for me locally, just not on the RFD site. Will investigate further.

[isobering]

Ooh, interesting! Thanks for taking a look at this so quickly.

[isobering]

Could it be a browser issue? I'm on Firefox 114.0.2 (64-bit)

[benjaminleonard]

Unlikely, i'm running a chromium browser and the first render should be done server-side anyway. Looking into any discrepancies between the node and asciidoctor versions now.

[benjaminleonard]

So @augustuswm managed to fix this with a redeploy — and we're still non the wiser as to why it's working now.

I'm not too clued up on xref — is xrefstyle and reftext still not working?

Also worth saying that you can't necessarily rely on all attributes being customisable. Some we set ourselves in the backend, though no xref ones.

[isobering]

xrefstyle is working for me now! Thank you so much!

I tried reftext as a last resort, so I don't have any RFDs that actually use it.

[isobering]

Scratch that - xrefstyle is working in RFD 121, but isn't working in RFD 363. See Section 6:

https://rfd.shared.oxide.computer/rfd/0363

[isobering]

Apologies for letting this fall off my radar - I'm back in RFD-land, and the RFD site appears to still not be handling :xrefstyle: short correctly (for cases where we want the xref text to say "Figure 1", for example, it instead prints the entire figure name). The original example in my first comment still applies.

[benjaminleonard]

We've moved to our own AsciiDoc renderer now, so things might have broken in new fun ways: https://github.com/oxidecomputer/react-asciidoc

Are you defining that attribute at the beginning of the document?

[isobering]

Yep - I define the attribute at the beginning of the document. Here's the macros for the RFD I'm working in right now:

:showtitle:
:numbered:
:icons: font
:state: discussion
:discussion: https://github.com/oxidecomputer/rfd/pull/580
:revremark: State: {state} | {discussion}
:authors: Ian Sobering <[email protected]>
:imagesdir: figures
:toc: left
:toclevels: 2
:sectnums: 
:sectnumlevels: 5
:xrefstyle: short

Nothing out of the ordinary here as far as I know.

[benjaminleonard]

I'll take a look! I would note that the site might override some of these – for example :toclevels: shouldn't have any effect because we want that to be universal.

In theory at the inline text level we hand it back to asciidoctor.js to render to HTML – need to figure out why it's not working as it should.

[hawkw]

I also seem to have been hit by this one in RFD 520, where I've used the :xrefstyle: and :section-refsig: macros to attempt to render internal section references in the form "§ X.Y.Z":
https://github.com/oxidecomputer/rfd/blob/52637f9ef032ed6e420b90dc7fa223f57e298e3b/rfd/0520/README.adoc?plain=1#L10-L11

This works as expected in asciidoctor-pdf, for example:

However, it doesn't appear to be honored by the RFD site:

This isn't the end of the world, but I figured I'd mention it, since the issue seems to still exist.

[benjaminleonard]

So at some point the xrefstyle got added as a default attribute. So by removing that, it fixes your issue. That said, I'm wary to remove it, if only because I think the site in general should behave somewhat consistently.

Not to say that the current setting is correct. The shorter version might be fine because xrefs are internal (I'm fairly sure any external ones would not work). What do you think?

[hawkw]

That said, I'm wary to remove it, if only because I think the site in general should behave somewhat consistently.

Not to say that the current setting is correct. The shorter version might be fine because xrefs are internal (I'm fairly sure any external ones would not work). What do you think?

So, I agree that the RFDs should all be formatted as consistently as possible --- that's actually why I was trying to set the xrefstyle. I've noticed that other RFDs (at least those written by @rmustacc) tend to use the style "§ X.Y [rfdNNN]" for external references to other RFDs, and I was just trying to mimic that for internal references to be consistent with the existing corpus. Not that this is terribly important, but it seemed nice to do.

For what it's worth, if we search the RFD repo for RFDs that attempt to set an xrefstyle, all the existing ones that do so are trying to select the short style: https://github.com/search?q=repo%3Aoxidecomputer%2Frfd%20xrefstyle&type=code

[hawkw]

Incidentally, it occurs to me that it would be cool to have a macro for referencing sections in other RFDs that automatically Does The Right Thing...but I imagine that other asciidoc renderers might choke on that, so maybe it's a non-starter?

[benjaminleonard]

I'm thinking we could default to the short xrefstyle and use a popover to show the full context. Related to #68