This project has moved and is read-only. For the latest updates, please go here.

Including a PDF file in a .chm file (html helpfile 1) generated using SHFB.

Topics: Developer Forum, Project Management Forum
Jan 15, 2013 at 10:31 AM

I need to include a pdf file in my sandcastle documentation. The user should be able to navigate to the pdf on clicking it in the .chm file. Is it possible to do this? I've been searching all forums with no proper answer. I have tried using href tag in the xml comment and providing the url of the pdf file. But it opens the browser instead of the pdf file. Has anyone done this before?

Jan 15, 2013 at 10:54 PM

Add the PDF to the SHFB project with a Build Action of Content.  That will embed it in the help file.  You can then use an anchor link to open it.  For example:

<remarks>See <a href="../Test.pdf">Test.pdf</a> for more information</remarks>

Note the relative path which is required since the HTML pages are in a subfolder.  If you put the PDF file in a subfolder in the project, just add the subfolder to the relative path as well (i.e. ../Subfolder/Test.pdf).

It is possible to access an external file from a Help 1 file using the "file://" protocol and a fully qualified path like this:

<remarks>See <a href="file://C:\DotNet\Test\Documentation1\Test.pdf">External Test.pdf</a> for more information</remarks>

However, the fully qualified path must be the path on the system on which the help file is viewed, not just the one on which it is built so that can be a problem unless you know that the external PDF will reside in a common location on all possible systems on which the help file can be viewed.

The first method will work in Help 1 and website output.  You can add a target="_blank" attribute to force it to open in a new browser window in web output.  The second method will not work in website output due to the local file system path.  Neither method will work for MS Help Viewer output due to the way it reformats the URLs.



Oct 3, 2014 at 2:26 AM
Hi Eric,

Wonderful work on SHFB! Very impressive.

I'm trying to link to a PDF from within an AML file and the "normal" HTML you suggested above doesn't seem to work.

I've tried the MAML link and externalLink to no avail.

How can I link to a PDF and have it fill the right panel entirely? Ideally, I could make it part of the TOC via the ContentLayout.content file but it appears to only allow links to AML files.

What am I missing?

Oct 3, 2014 at 4:12 PM
For website output, adding a target="_self" attribute (a linkTarget element for the MAML externalLink element) might get it to open within the same browser frame. You can try it for other help formats such as Help 1 but I'm pretty sure they don't support it and it will always open externally. There are no provisions for adding links to external files in the TOC.

Oct 3, 2014 at 6:37 PM
Hi Eric,

I tried the following for an external link:
<linkText>My Document</linkText>
When the website was generated, the resulting link was:

Which doesn't work very well for a website. :(

Just to be sure, I tried this as well:
But that put the exact text into the link which didn't work any better.

How can I link to the document with a simple relative link?

Oct 3, 2014 at 7:26 PM
Are you using a prior release? That sounds like a bug that was fixed a while ago in the VS2010 presentation style. Upgrading to the latest release will fix that. The following works:
<para>Link to embedded PDF:
    <linkText>An embedded PDF file</linkText>
Adding a linkTarget doesn't have any effect. It doesn't appear to be supported and it'll open in an external window regardless of the help file format and target setting.

Oct 3, 2014 at 8:55 PM
Not using an old version. I just downloaded and installed a couple days ago. If you can tell me what version numbers you would like me to check, I would be glad to do so. Are there any settings that could be triggering the old bug or a variant?
Oct 4, 2014 at 3:05 AM
As long as you downloaded it from the Download page here and it's version 2014.5.31.0, you've got the latest version. I tried the above with the VS2005, VS2010, and VS2013 presentation styles and it works as expected. Looking at the HTML generated resulted in the same relative path in all cases. Do you get the same results in the Help 1 file as for the website? Where you viewing the website with the development web server or on the local file system? If on the local file system, that might be why the path was not right.