xrefstyle is ignored for docbook backend

[mmatrosov]

Take this input.adoc file:

:sectnums:

:xrefstyle: full
Full style: <<LinkedHeader>>

:xrefstyle: short
Short style: <<LinkedHeader>>

:xrefstyle: basic
Basic style: <<LinkedHeader>>

[[LinkedHeader]]
=== Linked header

Here is how it is rendered:

This is expected. Then I convert it to docbook:

asciidoctor -d book -s --backend docbook --out-file output.db input.adoc

And here is the output:

<preface>
<title></title>
<simpara>Full style: <xref linkend="LinkedHeader"/></simpara>
<simpara>Short style: <xref linkend="LinkedHeader"/></simpara>
<simpara>Basic style: <xref linkend="LinkedHeader"/></simpara>
</preface>
<section xml:id="LinkedHeader">
<title>Linked header</title>

</section>

This is not expected. As you can see, all xref elements look exactly the same. The information about xrefstyle is lost. I would expect to see endterm attribute set in docbook.

[mojavelinux]

You are correct that the xrefstyle is currently relevant for the HTML backend only.

We got the idea originally from the xrefstyle attribute in DocBook, so its reasonable to assume we can support it there too. If you know which values this attribute is supposed to add, I'd be happy to add them to the converter. I will also accept a PR to update the DocBook converter if that's simpler. Looking for your input.

The information about xrefstyle is lost. I would expect to see endterm attribute set in docbook.

I think you meant "xrefstyle" attribute.

[mojavelinux]

Btw, the correct syntax here would be:

Full style: xref:#LinkedHeader[xrefstyle=full]

Short style: xref:#LinkedHeader[xrefstyle=short]

Basic style: xref:#LinkedHeader[xrefstyle=basic]

[mmatrosov]

I think you meant "xrefstyle" attribute.

No, I meant endterm:

If the endterm attribute is specified on xref, the content of the element pointed to by endterm will be used as the text of the cross-reference.

While:

Unlike endterm and xreflabel which have rigid semantics, the content of the xrefstyle attribute is simply additional information for the processing system. What effect it has, if any, is dependent on the processing system.

So it seems that endterm is a more robust choice.

If you know which values this attribute is supposed to add, I'd be happy to add them to the converter.

Sorry, I did not quite understand the question. I expected the content of endterm to be exactly the same as the content of the link generated for HTML backend.

I will also accept a PR to update the DocBook converter if that's simpler.

Yeah, totally understand. Unfortunately, I cannot provide any estimates on when I would be able to prepare one.

[mojavelinux]

I expected the content of endterm to be exactly the same as the content of the link generated for HTML backend.

Oh, I see.

Hmm, technically, we don't know this information. In the DocBook output, it's the toolchain that fills in these values (including the numbers of sections). So we don't even have the information for what the text would be. We have it in the HTML converter since the converter itself has to resolve these values.

It seems to me xrefstyle is the better attribute to use because it allows the DocBook toolchain to fulfill the request based on its internal reference tables (assuming the toolchain honors that attribute).

[mmatrosov]

technically, we don't know this information

Oh, I see. Hmm. I did a quick search on how xrefstyle is used and did not find anything relevant. Since I feed the .db file to Pandoc to obtain .docx, maybe @jgm or @mb21 can comment on this? Currently, Pandoc ignores xrefstyle completely.

One possible approach is to set docbook's xrefstyle to be the same as asciidoc's xrefstyle.

[RobJamesRamos]

I'll +1 this as a needed feature. I use short xrefstyle extensively, but I also need to export to docx frequently for my collaborators. The docbook -> pandoc pipeline is the most straightforward way to do this and requires the least manual tweaking afterward. Unfortunately this issue has forced me to stop using <> syntax and listing everything as an xref with a manual label. This basically means that I can't used the auto numbering tables and figures feature of Asciidoctor which is a huge inconvenience.

[mojavelinux]

There's still no clear path forward, so I wouldn't know what code to change if I wanted (and had time) to change it. I'll restate what I said above:

If you know which values this attribute is supposed to add, I'd be happy to add them to the converter. I will also accept a PR to update the DocBook converter if that's simpler.

If it's important to you, please step forward to propose a change.

Here's information about the xrefstyle in DocBook: http://www.sagehill.net/docbookxsl/CustomXrefs.html

[RobJamesRamos]

Apologies, I was not trying to sound impatient. I don't have a strong understanding of docbook. As a workaround I've been trying to change <xref linkend="my.id"/> to <xref linkend="my.id" xrefstyle="select: label"/> as I believe that should reproduce the behavior of xrefstyle short. Though nothing seems to work and I am beginning to wonder if Pandoc is part of the problem

[mojavelinux]

I see references to xrefstyle in the DocBook stylesheets by running this search: https://github.com/docbook/xslt10-stylesheets/search?q=xrefstyle However, I think I got stuck where you are. If I understand what the output needs to be, updating this converter to generate that is relatively straightforward. The hard work is figuring out what it should be. And I just don't know.

[mojavelinux]

Aha! Using this:

<xref linkend="s1" xrefstyle="select: labelnumber quotedtitle"/>

I got this when using the DocBook toolchain with the FOP/PDF output format:

see 1: “Section Title”

So it appears this does work. We just need to translate the xrefstyle keyword that we use into a select command in the DocBook output.

The next step is to figure out what those select commands should be in each case. Here's a proposal:

• short - select: labelname labelnumber
• full - select: labelname labelnumber quotedtitle

However, labelname doesn't seem to resolve to "Chapter" when pointing to a chapter, so I'm not getting that part.

We won't be able to tune it quite as much as we can with the HTML output, but this should at least give a close approximation.

[fitzoh]

Hey, just stumbled across this issue while trying to figure out how to link to numbered items.

Any thoughts on if the proposed select commands are a viable path forward?