XMetaL Community Forums » General » DITA and XMetaL Discussion » xref Links to same file break in PDF
Pages: 1
« previous next »
Print
Author Topic: xref Links to same file break in PDF  (Read 738 times)
rde
Member

Posts: 7
« on: April 22, 2011, 02:47:13 PM »
I'm trying to create links to various ids in a single file, and the links don't work when the file is output to PDF. The topic type is composite. I don't have any trouble when using similar xref links to ids in different files. I'm using XMetal Author Enterprise 6.0. Here's an example:

    <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE dita PUBLIC "-//OASIS//DTD DITA Composite//EN" "http://docs.oasis-open.org/dita/v1.1/OS/dtd/ditabase.dtd">
<dita>
  <topic id="MainTopic">
    <title>Main topic</title>
    <shortdesc/>
    <prolog>
      <author type="creator"/>
      <author type="contributor"/>
      <critdates>
        <created date="2011-03-11"/>
        <revised modified=""/>
      </critdates>
      <metadata>
        <audience type="developer"/>
        <keywords>
          <keyword/>
        </keywords>
        <prodinfo>
          <prodname/>
          <vrmlist>
            <vrm version="2011-03-01"/>
          </vrmlist>
          <component/>
        </prodinfo>
      </metadata>
    </prolog>
    <body>
      <p>The following datatypes are used in the response elements of the XXX operation:</p>
      <ul>
        <li><xref href="#DataType1"/></li>
        <li><xref href="#DataType2"/></li>
      </ul>
    </body>
    <reference id="DataType1">
      <title>DataType1</title>
      <shortdesc></shortdesc>
      <refbody>
        <section>
          <title>Datatype content</title>
          <p>The following table shows the elements of the <cmdname>DataType1</cmdname>
            datatype:</p>
          <table id="RequestParametersTable" frame="all" colsep="1" rowsep="1">
            <tgroup cols="4">
              <colspec colnum="1" colname="c1" colwidth="1.1*"/>
              <colspec colnum="2" colname="c2" colwidth="1.13*"/>
              <colspec colnum="3" colname="c3" colwidth="1.0*"/>
              <colspec colnum="4" colname="c4" colwidth="1.17*"/>
              <thead>
                <row>
                  <entry>Name</entry>
                  <entry>Description</entry>
                  <entry>Required</entry>
                  <entry>Valid values</entry>
                </row>
              </thead>
              <tbody>
                <row>
                  <entry><parmname>Name1</parmname></entry>
                  <entry>
                    <p>Description1</p>
                  </entry>
                  <entry>No</entry>
                  <entry/>
                </row>
                <row>
                  <entry><parmname>Name2</parmname></entry>
                  <entry>
                    <p>Description2</p>
                  </entry>
                  <entry>No</entry>
                  <entry/>
                </row>
              </tbody>
            </tgroup>
          </table>
        </section>
      </refbody>
    </reference>
    <reference id="DataType2">
      <title>DataType2</title>
      <shortdesc></shortdesc>
      <refbody>
        <section>
          <title>Datatype content</title>
          <p>The following table shows the elements of the <cmdname>DataType2</cmdname>
            datatype:</p>
          <table id="RequestParametersTable" frame="all" colsep="1" rowsep="1">
            <tgroup cols="4">
              <colspec colnum="1" colname="c1" colwidth="1.1*"/>
              <colspec colnum="2" colname="c2" colwidth="1.13*"/>
              <colspec colnum="3" colname="c3" colwidth="1.0*"/>
              <colspec colnum="4" colname="c4" colwidth="1.17*"/>
              <thead>
                <row>
                  <entry>Name</entry>
                  <entry>Description</entry>
                  <entry>Required</entry>
                  <entry>Valid values</entry>
                </row>
              </thead>
              <tbody>
                <row>
                  <entry><parmname>Name3</parmname></entry>
                  <entry>
                    <p>Description3</p>
                  </entry>
                  <entry>No</entry>
                  <entry/>
                </row>
                <row>
                  <entry><parmname>Name4</parmname></entry>
                  <entry>
                    <p>Description4</p>
                  </entry>
                  <entry>No</entry>
                  <entry/>
                </row>
              </tbody>
            </tgroup>
          </table>
        </section>
      </refbody>
    </reference>
    <topic id="RelatedTopics">
      <title>Related topics</title>
      <shortdesc/>
      <body>
        <p></p>
      </body>
    </topic>
  </topic>
</dita>


The two xref links (<xref href="#DataType1"/> and <xref href="#DataType2"/> don't work in the PDF output. Has anyone else seen this problem?

Thanks,
Rick
Logged
Derek Read
Program Manager (XMetaL)
Administrator
Member

Posts: 1546



WWW
« Reply #1 on: April 26, 2011, 05:45:44 PM »
I think I can reproduce what you are seeing, but I'm not sure because I'm making a few assumptions. The main one being which deliverable you are using to generate your PDF, "XMetaL Enhanced PDF via RenderX XEP", and the second one being that no changes have been made to the DITA Open Toolkit.

If I generate a PDF using "XMetaL Enhanced PDF via RenderX XEP" I see that the links are generated just fine, it is just that if you click on them they don't go anywhere because they both point to the same page. Everything fits on page 3. If you add additional content so that the three topics (topic + 2 reference topics) end up on separate pages you should find that the links actually do something (if they point to different pages).

See screen capture: pdf_out.gif

If that isn't what you are seeing please provide some more information so that I can try to reproduce the problem.

Note: I'm also ignoring the fact that the document is invalid (it has an attribute value "developer" for @type on an audience element). However, the DITA Open Toolkit itself does not catch this error for me for some reason (I'm not sure why but I will look into that). XMetaL Author does catch the error though. Allowed values include (only): user, purchaser, adminstrator, programmer, executive, services, other, and -dita-use-conref-target.

One more point. This appears to be a test of some kind (unless you've dumbed things down to ask this question on the forum). Unless you have specific reason to do so, I would recommend saving one topic per file and making use of DITA maps. DITA obviously allows "composite" documents but using maps provides many advantages.

* pdf_out.gif (24.83 KB, 688x869 - viewed 79 times.)
« Last Edit: April 26, 2011, 05:56:09 PM by Derek Read » Logged
rde
Member

Posts: 7
« Reply #2 on: April 29, 2011, 07:32:58 PM »
Thanks for your answers, Derek.

To answer your questions, I did "dumb down" my example topic because the original topic from which my example was based is for unreleased documentation. Unfortunately I made the example topic so small that you couldn't test whether or not the links actually jumped to a different point on the page. Also we're using composite topics because we are writing API reference pages and we want all of the elements to appear in the same topic.

Fortunately, I discovered the problem. XMetal appears to require that you use the file name as well as the anchor in your links for the links to work in the transformed PDFs. In other words, I get broken links in my PDFs when I use links like the following: <xref href="#DataType1"/>. But the links work fine when I use links like the following: <xref href="Filename.dita#DataType1"/>.

Thanks,
Rick
Logged
Derek Read
Program Manager (XMetaL)
Administrator
Member

Posts: 1546



WWW
« Reply #3 on: May 02, 2011, 03:43:39 PM »
There is no requirement to include the filename in the @href.

<xref href="#DataType1"/> and this <xref href="Filename.dita#DataType1"/> should be equivalent when the xref and what it is linking to are both inside the file filename.dita and the DITA OT treats handles this just fine (at least in my tests).

The behavior of the DITA OT follows what the DITA 1.1 Language Reference says (my highlighting in blue) for the usage of the href attribute:
Quote from: http://docs.oasis-open.org/dita/v1.1/CS01/langspec/langref/xref.html#xref__xref_attr
A hyperlink to an external Web page (URL) or other non-DITA resource, to another DITA topic in the same file or in another file, or to a specific element inside a DITA topic . . . DITA content is targetted as follows:
Target elsewhere in the same file:
  href="#topicID"
  href="#topicID/elemID
Target in a different file:
  href="filename.dita#topicID"
  href="fname.dita#topicID/elemID"
. . .

Having said that, XMetaL Author Enterprise will include the filename when you use the Insert Cross Reference dialog. The DITA OT has no problem handling either and the XMetaL Author Enterprise link checking functionality also handles both methods (when you have broken links you have the option to view a dialog named "Unresolved References Log").
Logged
MarcB
Member

Posts: 5
« Reply #4 on: February 27, 2012, 10:55:29 AM »
I am observing the same behaviour as rde. Using XMetaL 6.0.1 on Windows XP SP3 and outputting to PDF using the XMetaL interface via RenderX, links built with href="#topicid" pointing to a topic in the same dita file do not work in PDF (they work fine in HTML). Links built as href="filename.dita#topicid" work in PDF.
The dita file is a composite topic (a <topic> wrapper containing multiple <concept> and <task> topics).
This is an issue to watch when converting legacy formats to DITA.

However, interestingly enough, the "topicid-only" links work when using FrameMaker with the DITA-FMx plugin to generate PDF.

Marc Beckers
Software AG
Logged
Pages: 1
Print
« previous next »
Jump to: