X-refs are not working in the PDF output

Report · Apr 12, 2011

I correctly generated a PDF from a ditamap using DITA-FMx and cross-references are not working.

Thanks for your help.

Report · Apr 12, 2011

Are these local or external xrefs? For external xrefs you need to enable the "Convert xrefs/links to hyperlinks" option in the book-build Options. If these are internal links (to other topics in the project) .. first check the console window to make sure you didn't have any errors, then open the generated FM file with the xref. Locate the xref and check to make sure it points to the FM target and not the original XML target (in the @href attribute). You need to make sure that the "Normalize Reference Paths" and "Reload References" options are also enabled in the Bookbuild Options.

Note that you may want to send DITA-FMx questions to the dita-fmx-users Yahoo list .. that's where you'll find a group of FMx users who can help with your questions.

Thanks,

...scott

Report · May 09, 2011

Thanks for your reply.

I refer to internal links and the properties you mentioned are correctly set. In fact, the issue only concerns the topic-to-topic links across different ditamaps. The links created within the same ditamap work correctly.

To crete the link at the DITA level, I used the tag <fm-xref>.

Thanks

Arianna

Report · May 09, 2011

Ah .. you're making links to topics in a different map? That won't work. If you look in the FrameMaker console window, you'll see an error message about an xref that points to a topic outside the scope of this map. An "internal" link is on that points to a topic that is within the same map. The only way to make a link to a topic outside of that scope is to use an "external" link, and you need to specify the actual location of that target in the target PDF.

This Community KB topic may help with the xref syntax ..

http://kb.leximation.com/dfm/?kbid=61

Cheers,

...scott

Report · May 10, 2011

Thank you.

I understand that I need to create an external link to a specific

destination in the PDF. And I understand how to create a Destination in my

PDF. That's fine.

BUT my PDF is not located on a website, identifiable through a URL. My PDF

is in a folder on a specific server. Then, how do I specify the path for the

HREF below?

Instead of //www.example.com// what should I put?

href=http://www.example.com//myfile.pdf#DEST

Thanks

Arianna

Report · May 10, 2011

In theory you should be able to use the "file" protocol to reference a PDF on the local filesystem or via a drive or server. To access the file at "c:\folder\file.pdf" use this (3 slashes) ..

href="file:///c:/folder/file.pdf"

Or for a UNC server "\\servername\folder\file.pdf" use this (4 slashes) ..

href="file:////servername/folder/file.pdf"

Or .. if you're on a UNIX system "/directory/path/file.pdf" (3 slashes) ..

href="file:///directory/path/file.pdf"

I hope that helps.

Cheers,

...scott

Report · May 24, 2011

Regarding your last reply, do you think that a reltable can represent a valid alternative? I mean, x-refs across different ditamaps would work better if handled through a reltable?

Thanks

Report · May 24, 2011

Nope. The exact same limitations will apply. If a reference is to a file that's outside of the "scope" of the current map (i.e., it's not a topic within the map), you'll need to use an "external" reference and use the "file:" or "http:" protocol.

...scott

Report · May 24, 2011

OK, thanks.

Then, it's not clear to me how to define the path in the external reference

when I create it in my DITA source.

Say for ex: that I need to create a link to the section "Prerequisites" in

the PDF named "ScreeningProcedure.pdf".

How would the path look like?

Thanks

Report · May 24, 2011

Well .. it depends on where the target PDF lives. You have to know that in order to create the xref. If this PDF is accessed via the web, you'd use the following (assuming "Prerequisites" is a named destination in the PDF) ..

href="http://www.example.com/ScreeningProcedure.pdf#Prerequisites"

and if the file is accessed on a file system, you'd use this ..

href="file:///c|/path/ScreeningProcedure.pdf#Prerequisites"

Note that both of these will end up being viewed in the default web browser, which may not be the desired result for the "file" option. If you open the generated FM file, you'll be able to look at the code in the Hypertext marker (which is what is used by the PDF to make the link). DITA-FMx currently uses the "message URL" Hypertext command .. but I'm thinking that when the file: protocol is used it should really use "message openfile" instead, which should open the file in Acrobat .. I think. I'll look in to making this work better for the "file" option.

The above @href values should "work" though.

...scott

Report · May 26, 2011

Thanks Scott, although I don't think this is the best solution in our case.

The target PDF is a file that is delivered to a customer. This means that it won't keep the same location on the file system, and therefore links will no longer work I guess. In addition to that, we are still not ready for publishing our doc on the web. So the delivered PDF is a file that lives on its own.

If the problem occurs only across different nested ditamaps, I thought I could get rid of these nested diatamaps and just have a global ditamap containing only topics. But then how would I obtain the different section levels in the TOC?

Today, I use nested diatamaps in order to get the following structure:

|_ Section 1

|

|_ Section 2

|_ Section 2.a

|_ Section 2.b

|_ Section 2.c

|

|_ Section 3

where Section 2 is a ditamap with three topics.

Are there other alternatives to nested ditamaps in order to keep the same level of indentation?

Thanks

Arianna

Report · May 26, 2011

Hi Arianna...

The linking issue is more of a PDF limitation than a DITA or DITA-FMx issue. The link has to be statically defined, and if the actual target file's location isn't known, there's not much that can be done. If you can set this up to work outside of DITA, let me know and we can figure out how to make it work.

This shouldn't be a problem with nested maps, since everything under the root map would end up in the same generated book, and therefore in the same PDF. This problem happens when trying to link to targets that are in separate PDFs and thus separate root maps.

There are basically three ways to achieve nested topics (with various permutations in each) ..

- root map and submaps with nested topicrefs to separate topics

- single map with nested topicrefs to separate topics

- single map with topicrefs that reference topic files with nested topics

However, using a different method for grouping the topics would have no bearing on your PDF linking issue. Using nested maps or a single map should be a decision you make based on workflow or other rationale.

Thanks,

...scott

Report · May 27, 2011

Hi Scott,

thank you again.

In my case the broken x-refs are the ones across different nested maps

within the same root ditamap.

Let me better clarify the context and the actual need.

My root ditamap contains topics and nested maps, as follows:

rootditamap

|_topic 1

|_topic 2

|_topic 3

|_nestedmap 1

|_topic 1.a

|_topic 1.b

|_topic 1.c

|_topic 4

|_nestedmap 2

|_topic 2.a

|_topic 2.b

|_nestedmap 3

Links from topic 1 to topic 2 =>. work fine.

Links from topic 1.a to topic 2.a => do not work.

Thanks

Arianna

Report · May 27, 2011

HI Arianna...

I'm so sorry if I led you down this path. I completely misunderstood the problem. The internal structure of a "project" (everything under the root map) should have no bearing on the ability to link from one location to another. When linking from one topic to another where the target topic is within the same root map, you would just use a standard xref (or fm-xref). Do not set the @scope attribute to "external" and don't worry about specifying a special @href value. This is just a normal internal xref.

If one instance of an xref is working and another is not, it's likely that you've created that xref incorrectly or linked to the wrong place (or it is possible that DITA-FMx is choking on the folder/file structure, but those problems should have been eliminated with recent updates). Try recreating the bad xref using exactly the same technique and method you used to create the one that works.

If you can't get the xref to work properly, feel free to send me your files so I can debug the problem. If it's a problem with DITA-FMx, I'll fix it, if it's a problem with your structure or linking method I'll let you know how to fix it.

Please contact me through the web form or other means here ..

http://leximation.com/contact.php

Cheers,

...scott

Report · May 27, 2011

Thanks Scott,

I sent my reply to

http://leximation.com/contact.php

Arianna