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 <ian@oxidecomputer.com>
: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.