Cross document links from includes in same PDF don't work

[ctargett]

In one file that's included with a master file used to generate a PDF, we have a cross-document reference in the form of:

see <<managing-product.adoc#,Managing Product>>.

The 'managing-product.adoc' file is another .adoc file included in the same PDF output. When the PDF is generated, the link that's created is file://path/managing-product.pdf. Before we added the hash (#) to the end of the filename, the PDF would underline the text properly, but the underlined text was not clickable and no URL displayed in the PDF Reader.

We're using asciidoctor-ant 1.5.3, which has asciidoctor-pdf 1.5.0.alpha.10. I tried it with 1.5.0.alpha.11 directly, and got the same result.

This looks like the problem that was reported in #83 , but that's been closed for a while so that isn't it.

[mojavelinux]

It appears the interdocument xrefs that reference the top of the page aren't implemented yet, so whatever behavior you are seeing is by random chance.

Even with that fixed, I don't think it's going to do what you expect. When you use an interdocument xref to a document that may be (or is being) included in the current document, you almost always want to specify a specific anchor after the #. Otherwise, when you include the document into the master, it's going to create a link to the top of the document.

In other words, you want something like:

See <<managing-product#_managing_product,Managing Product>>.

where managing-product.adoc might have content as follows (the explicit ID on the section is optional, but shown for clarity):

[#_managing_product]
== Managing Product

content

Note that the .adoc part is optional in an interdocument xref. It's assumed when you use #.

[ctargett]

Belated thanks on this Dan. I understand it a little better, but still need to figure out what to do with our content.

Just to elaborate on this point a little bit:

... you almost always want to specify a specific anchor after the #. Otherwise, when you include the document into the master, it's going to create a link to the top of the document.

That's basically what we want. I'm moving documentation from Confluence to Asciidoctor, and we have a lot of page cross references that point only to the top of a page (for example: to use Feature B, it's helpful if you know about Feature A, which is described elsewhere...). Confluence sort of lends itself to this behavior by making it really easy to add xrefs at the page-level, but not so easy to figure out and then properly format a pointer to the proper section. Trying to find and fix all of these is going to extend our conversion process, but we can't call it a "go" until we have working links.

[mojavelinux]

Perfect, then the fix addresses precisely your situation.