xrefs between chapters (was: links between sections)

[cexbrayat]

It looks like the links using <<_my_chapter, My Chapter>> are broken.
I'm not really sure about what's happening because it looks like the link is generated <a href="_my_chapter">My Chapter</a>.
But as I am in a multi document .adoc, using several includes, the link should maybe be of the form <a href="document-17755860.xhtml">My Chapter</a>, as they are in the TOC ?

Maybe related to #19

[mojavelinux]

Indeed, we haven't yet implemented links between chapter files. You could try the inter-document xref syntax, though I can't guarantee that would work.

<<_my_chapter#,My Chapter>>

The file name would need to match for that to work.

[mojavelinux]

The inter-document xref syntax doesn't yet work either.

[mojavelinux]

Several authors are now hitting this. We really need a solution for this one. Prioritizing.

[cexbrayat]

Hi Dan. Do you have any other workaround in mind? We are going to release our ebook next week, and that's our last problem to solve :)

[mojavelinux]

Here's the workaround I've come up with thus far.

ifdef::ebook-format[link:chapter-id.xhtml#section-id[Label]]
ifndef::ebook-format[<<section-id>>]

Basically, you have to make a manual link when the EPUB3 converter is being used.

I could try to work on a better solution over the weekend as that fix is very invasive.

The other option, of course, is to use a custom template for the inline_anchor node (e.g., inline_anchor.html.slim), then write the xref like:

<<chapter-file-name#section-id,Label>>

You'd then need to map the chapter file name to the chapter id so that you output the correct link target.

But that seems like a lot of work when we could just fix the converter :)

[cexbrayat]

Thanks for your answer. I tried the first workaround, but it looks like my xhtml files are not named after the chapter id: they all have a name like document-16251440.xhtml. Am I missing something? (I do have chapter ids).

[mojavelinux]

I do have chapter ids

You must have chapter ids. Otherwise, you get random file names in the archive.

[mojavelinux]

I have proposed a fix. However, there is still one requirement for it to work. The id on the chapter must match the basename of the chapter file.

For example, if you have a chapter file named shell-introduction.adoc, then you must define an id on the chapter as follows:

[#shell-introduction]
= Introduction to Gnome Shell

Then, you can refer to a section in this chapter from another chapter using.

<<shell-introduction#activities,Activity overview>>

The fact that the id of the chapter and the file name must match is related to #46. I think perhaps we should just retain the file name of the original file.

[mojavelinux]

For the fix, see #66.