SID-01908: GenPDFAddOn - Links to PDF WikiWords

Status:	Unanswered	TWiki version:	5.1.4	Perl version:	5.10.1
Category:	GenPDFAddOn	Server OS:	Turnkey Linux 12.1 Debian 6.0.7 Squeeze	Last update:	10 years ago

Currently, the links in generated PDFs point to the topic URLs in the originating online TWiki.

How can links in generated PDFs point to the corresponding locations INSIDE the generated PDF?

Thank you for GenPDFAddOn.

-- Patrick Townsend-Wells - 2014-04-15

Discussion and Answer

To clarify: When a single topic generates a PDF, the PDF links actually link to the topic URLs in the originating online TWiki. (Of course, only when the TWiki server is available to the user.) When multiple topics generate a PDF, the PDF links do not work.

-- Patrick Townsend-Wells - 2014-04-15

One solution is to convert the TWiki hyperlinks to HTML hyperlinks. Converting TWiki anchors to HTML anchors works, but is not necessary.

The hyperlinks in the GnePDFAddOn PDF version will then work.

Is there another solution based on configuring GenPDFAddOn and not altering the original TWiki pages?

-- Patrick Townsend-Wells - 2014-04-18

Converting TWiki hyperlinks to HTML hyperlinks does not always work in GenPDFAddOn PDF versions.

In fact, only a small percentage worked in the PDF version, even though some did work in PDF, while all seem to work in the TWiki version.

After using Global replace, some worked and most did not in the PDF, although Global replace faithfully replaced the necessary code. Links to page anchors did not work.

This was also the condition after manually entering HTML link and anchor code.

In all cases, the links worked in the TWiki version.

Some other factor seems to control whether PDF hyperlinks will work.

-- Patrick Townsend-Wells - 2014-04-21

It looks like this plugin has a number of bugs that need to be fixed. You could contribute bug fixes or hire a TWiki consultant to do that for you.

-- Peter Thoeny - 2014-04-22

I'm a tech writer. I can figure it out (workarounds), but fixing it is a good bit beyond that.

Links that specify the topic name and a page anchor work. A workaround that solves the vast majority of links that only specify a topic name is to put a page anchor with the name of the topic at the top of each topic. That makes most of the PDF links work. However, a few don't fall for that. Some of the rest will work after the topic name is changed, and then the links and the top-of-the page anchor need to be updated. (That points out a bug in the TWiki Rename feature. It identifies the topics with links to the page being renamed, but will not consistently update those links.) This last issue seems to involve TWiki remembering original topic names after they have been renamed and not updating pointers. (But that is just a guess.)

-- Patrick Townsend-Wells - 2014-04-22

In order to make hyperlinks work both in TWiki and in PDF versions generated by GenPDFAddOn, the following guidelines apply:

• TWiki guidelines that each topic name can be any length but MUST be unique among all topics in the web must be followed.
• Anchors:
  • Either TWiki or HTML anchor code can be used and will be functional in both TWiki and PDF versions, but TWiki code can result in faster linking in TWiki versions.
  • For each anchor name, the FIRST 32 characters MUST be unique among ALL topics in the web. <br> The anchor name may OR may not be the topic name (see below).
  • Each topic MUST contain an anchor, EITHER:
    • For sub-heading anchors, in the body of the topic content next to the targeted sub-heading.
    • For entire topic anchors, above all displayed topic content and below topic page-break code.
• Hyperlinks:
  • HTML hyperlink code MUST be used and will be functional in both TWiki and PDF versions. <br> However, only TWiki hyperlink code will cause TWiki to generate NEW topics.
  • In each hyperlink:
    • The topic name must be specified.
    • The anchor name may OR may not need to be specified (see below).
    • Non-functional display text must be used to show the hyperlink in TWiki versions.

These guidelines recommend the following methods:

• Use HTML hyperlink code and TWiki anchor code.
• For topics with topic names that are 32 characters or less:
  • For sub-heading hyperlinks, specify the topic and anchor names.
  • For entire topic hyperlinks:
    • In the target topic anchor, use the topic name as the anchor name.
    • In each hyperlink, specify only the topic name and NOT the anchor name.
• For topics with topic names that are longer than 32 characters:
  • For sub-heading hyperlinks, specify the topic and anchor names.
  • For entire topic hyperlinks:
    • In the target topic anchor, use an anchor name that is 32 characters or less <br>(for example, a coded reference to the topic name).
    • In each hyperlink, specify the topic and anchor names.
• If these methods STILL do not result in PDF hyperlinks that work for a targeted topic:
  • In TWiki, create a new topic and copy the target topic content into it.
  • Update the topic names in all hyperlinks.
  • It is optional whether anchor names in anchors and hyperlinks are updated.

In PDF versions of TWiki webs, hyperlinking seems to ignore topic names and relies on anchor names, although this has not been verified. <br> When adapting a TWiki web, the Global Replace addon works wonders.

When troubleshooting:

• Hyperlinks that follow TWiki guidelines will be functional in TWiki versions; however, that is NOT sufficient for them to be functional in PDF versions.
• Multiple anchors with names that MATCH in their first 32 characters, even if in different topics, will result in ALL their hyperlinks linking to the LAST registered anchor.

-- Patrick Townsend-Wells - 2014-04-25

Closing this question after more than 30 days of inactivity. Feel free to reopen if needed. Consider engaging one of the TWiki consultants if you need timely help. We invite you to get involved with the community, it is more likely you get community support if you support the open source project!

-- Peter Thoeny - 2015-12-03

If you answer a question - or someone answered one of your questions - please remember to edit the page and set the status to answered. The status selector is below the edit box.