DocBook links missing from PDF

[jkeys089]

I've tried simple links:

Code: Select all

<link linkend="somid">Click Me</link>

and xref's:

Code: Select all

<xref linkend="somid"/>

but nothing is making it into the final PDF.

The strange thing is the auto-generated TOC links work great.
Is there some magic required to enable links within the body of the document?

[sorin_ristache]

Hello,

If you transform the DocBook XML document to PDF using the built-in FO processor Apache FOP then the text of the links is not rendered with a different color of font style than the regular text. The link is there but you should just hover the mouse pointer over the text of the link to see the link pointer and then click the link.

If the links do not work in your Docbook document please try with the following document:

Code: Select all

<?xml version="1.0" encoding="UTF-8"?>

<?xml-model href="http://www.oasis-open.org/docbook/xml/5.0/rng/docbook.rng" schematypens="http://relaxng.org/ns/structure/1.0"?>

<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">

    <info>

        <title>Test</title>

    </info>

    <sect1>

        <title>Section 1 Title</title>

        <para>Link to <link linkend="sect">section 2</link></para>

    </sect1>

    <sect1>

        <title>Section 2 Title</title>

        <para xml:id="sect">Section 2</para>

    </sect1>

</article>

Please transform this document to PDF using the DocBook PDF transformation and hover the mouse pointer over and click the link text section 2. Is the link working in the PDF document?


Regards,
Sorin

[jkeys089]

Hmmm, your doc works perfectly.
There must be something in the structure of my doc that is prohibiting the links from working I guess. I'll do some tests on my end to see if I can understand what is causing the breakage.

Thanks for your help!

[jkeys089]

Found the issue. Apparently your linkend targets (those elements with xml:id attributes) cannot be title elements.
I moved the xml:id attribs to sect elements and magically everything starts working.

Thanks again for your help!

[P4jjb]

Hi all,

I've run into the same issue.

If the xref links to the title_<id number>, links work in DocBook 5 chunked HTML, but not the PDF.

If the xref links to the section_<id number>, links work in both chunked HTML and PDF--but the link appears with an intro phrase and surrounded by quotes:
"the section called "<section name>"

And if the linkend="section_<id number>" but the endterm="title_<id number>" like this example...
<xref xmlns:xlink="http://www.w3.org/1999/xlink" linkend="section_t2d_15x_n3"
endterm="title_u2d_15x_n3"/>
...then the output in both chunked HTML and PDF is a nice, plain link with no intro phrase and no quotes.


Configuring each xref with a linkend=correct section and endterm=correct title is tedious, especially as the IDs are random numbers.
Linking to the section is the fastest and most efficient method. But how do I modify the XSL to remove the intro phrase "the section called" and the quotes surrounding the link title? Or what parameter do I set in my duplicate DocBook 5 chunked HTML and PDF transformation scenarios?

Thanks!

[sorin_ristache]

Hi P4jjb,

Please repeat the test that I suggested to jkeys089: apply the built-in DocBook PDF transformation to the test document which I specified to see if you get the same problem with this test document, that is:

Code: Select all

<?xml version="1.0" encoding="UTF-8"?>

<?xml-model href="http://www.oasis-open.org/docbook/xml/5.0/rng/docbook.rng" schematypens="http://relaxng.org/ns/structure/1.0"?>

<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">

    <info>

        <title>Test</title>

    </info>

    <sect1>

        <title>Section 1 Title</title>

        <para>Link to <link linkend="sect">section 2</link></para>

    </sect1>

    <sect1>

        <title>Section 2 Title</title>

        <para xml:id="sect">Section 2</para>

    </sect1>

</article>

If the link works correctly in the PDF output created from the above document we have to check your DocBook XML document and see what is different there. Is your XML document valid, that is does Oxygen report any validation error when you run the action Validate which is available both on the Validate toolbar and on the Document -> Validate menu? If there are validation errors in your DocBook XML document please fix these errors first.

If there are no validation errors and the above test document works correctly for you (that is the link works correctly in the PDF output) then please post here (or send us through the online form) a sample XML document for reproducing in Oxygen the problem with the wrong links.


Best regards,
Sorin

[P4jjb]

Hi Sorin,

We're evaluating oXygen XML for purchase. Apologies that my questions are probably basic; it's been awhile since I worked in oXygen. I'll probably ask many questions in the next 18 days of the trial!

The links do work in the test you sent. In my project can get links/xrefs within a document working, but I can't get links/xrefs from one chapter to another working.

What information and attributes need to be specified to get xrefs working between chapters for DocBook5 when using XInclude? I've looked in the doc, the forums, and the videos, but can't find an answer.

It seems like you need to:
1. Add XML:ID attributes using the ID Options functionality in Author.
2. Create a validation scenario on the master XInclude file, and run that scenario on all the files to get ID attributes auto-completion across all project files, per this post: http://www.oxygenxml.com/forum/post2031 ... ref#p20311. (However, the autocompletion is working for my files, for some reason.)
3. Add the xref with the xmlns:xlink attribute <xref xmlns:xlink="http://www.w3.org/1999/xlink" />. But what attributes need to be specified here to link to another chapter? I've tried various combinations of linkend, endterm, and xml:id, but nothing works.
Am I missing any steps? Or do I need to regenerate something somewhere?

For example, here's the Appendix xml:id and a title element xml:id.

Code: Select all

<appendix xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="user_appdx">

<info>

<title xml:id="title_trv_nc1_p3">Managing SSH Keys</title>

</info>

</info>

In another chapter, I have this link, which does validate. But the link is absent in both PDF and WebHelp output.

Code: Select all

For more information, see <xref xmlns:xlink="http://www.w3.org/1999/xlink" linkend="title_trv_nc1_p3"></xref>

Thanks for your help.

[sorin_ristache]

Hi,

The links do work in the test you sent. In my project can get links/xrefs within a document working, but I can't get links/xrefs from one chapter to another working.

What information and attributes need to be specified to get xrefs working between chapters for DocBook5 when using XInclude? I've looked in the doc, the forums, and the videos, but can't find an answer.

You should add a link to other element within the same document (composed of multiple files assembled with XInclude) with the link element and the linkend attribute, not the xlink:href attribute. The xlink:href attribute should point to a URL, usually a remote document, for example http://web.server.com/target.html.

It seems like you need to:
1. Add XML:ID attributes using the ID Options functionality in Author.

You need the xml:id attribute for marking the target element of the link.

2. Create a validation scenario on the master XInclude file, and run that scenario on all the files to get ID attributes auto-completion across all project files, per this post: http://www.oxygenxml.com/forum/post2031 ... ref#p20311. (However, the autocompletion is working for my files, for some reason.)

If you want to validate the links to the other fragments of the documents and to see the possible link targets in the auto-completion window, yes, you need that validation scenario. The possible target links cannot be detected and displayed in the auto-completion window without associating the validation scenario to the edited fragment file.

3. Add the xref with the xmlns:xlink attribute <xref xmlns:xlink="http://www.w3.org/1999/xlink" />. But what attributes need to be specified here to link to another chapter? I've tried various combinations of linkend, endterm, and xml:id, but nothing works.

The xlink:href attribute should be used only for remote targets of the link. If the link target is in a fragment file of the same document you should use the linkend attribute on the link element.

For example, here's the Appendix xml:id and a title element xml:id.

Code: Select all

<appendix xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="user_appdx">

<info>

<title xml:id="title_trv_nc1_p3">Managing SSH Keys</title>

</info>

</info>

In another chapter, I have this link, which does validate. But the link is absent in both PDF and WebHelp output.

Please avoid adding the xml:id attribute on the title element. The xml:id attribute should be added either on the parent element of title, in this case section, or an element with content like para, figure, table, etc. The links to titles do not work and I think such links do not really make sense, usually the user should be pointed to a whole section or to some content element like para, table, figure, itemizedlist, etc.


Regards,
Sorin