support external links

May 21, 2008 at 2:31 PM
Does sandcastle support external links?
For example, I have 2 projects (A and B), I want to create one help file for each project, but my project B includes dll's from A, so I want that in the help file generated for B project does not have the A dll's but a link to the A help file, and when I click on these links it opens the A help file without show that I'm opening another help file. The help file is opened in the same help viewer screen.

May 21, 2008 at 4:03 PM
It's possible if you are generating Help 2 files.  I don't think it can be done with Help 1 files but I could be wrong.  As for the Help 2 files, the exact method of accomplishing it will depend on what you use to build the help files (Sandcastle Help File Builder, DocProject, or a basic build script like those supplied with Sandcastle).

May 21, 2008 at 5:41 PM
Thank you Eric,
which one is the easiest? I have to create a build script because I should not use a gui to create the help files, what I have to do in my script to accomplish it?
May 21, 2008 at 6:27 PM

The tools that Eric pointed out (Sandcastle Help File Builder and DocProject) provide user interfaces for configuring and building help, but they also provide a way to build help in a console, which can be invoked by a build script.  (DocProject has a dependency on MSBuild, however.)

If you're not going to be integrating your help into Visual Studio, then you don't need to build Help 2.x output.  I agree with Eric that Help 1.x output may not have the feature that you are asking for though.  In that case you must either build two separate .chm files with some duplication or create one .chm file with all of the content that you need.  Alternatively, you may prefer to build one .chm that contains the documentation for project B, one that includes internal content for A, and then another file that contains the public content in A.  The third .chm can be deployed with each of the first two.
I assume that you're segregating the topics simply because you need to deploy them separately; otherwise, you're probably better off just building one help file to make maintenance and distribution a bit easier.

- Dave
May 21, 2008 at 6:29 PM
The Sandcastle Help File Builder contains both a GUI and a console mode app that can be ran from build scripts.  DocProject is a VS2005/2008 add-in which lets you use a VS project to build a help file and has MSBuild support.  Using SHFB, the Beta contains a plug-in (Additional Reference Links) that can be used to add other projects to use as a source of reference links.  I'm not familiar with DocProject so I can't say how that might work.  If using a build script, you can run it on the Project B and then take its file and add it to Project A's sandcastle.config file in the ResolveReferenceLinksComponent2 configuration section.  Add a new <target> element for the file and set the type to Index.

May 26, 2008 at 8:30 PM
Thank you,
Eric I tried to use the SHFB beta, first I created a
SHFB project for my Project A, for test purpose  it only has Interfaces, and ran the SHFB to generate the HtmlHelp2x files, second I created my Project B, that has some dlls that implement the Interfaces from A, and in the shfb project for B I added A's shfb file in the Additional Reference Links plugin, and set A's dlls in the Dependencies.
When I opened the
HxS built for Project B, I noticed that there is no link to the interfaces created in A. I'm opening the HXS using H2Viewer. What am I doing wrong?
May 26, 2008 at 8:41 PM
You've done everything right but you'll need to register the Project A help file with a collection before you can link to it from Project B's help file.  H2Viewer lets you view an unregistered help file by registering it temporarily I think.  It won't know about any other unregistered ones you might have.  Note that the collection files generated by the current version of SHFB aren't quite ready for registering the help file without some modifications.  The next release of SHFB produces valid collection files as well as an H2Reg config file that can be used to register them.  With luck, the next Sandcastle release should be out later this week and the next SHFB release will be out within a week of it.

May 27, 2008 at 1:57 PM
Thank you for your quick responses. So I have to register the Project A help file before add it's shfb file in the Additonal Reference Links of Project B. I can't see the relation between  the shfb and the HxS when I set the A's help file in the Additional Reference Links in the Project B' shfb file.
Just for curiosity when I built the Project B this warn was logged:
Warn: ResolveReferenceLinksComponent2: Unknown reference link target 'T:Comp.ITest'.
Is it related to the fact that the Project A's help file isn't registered?

May 27, 2008 at 3:35 PM

There is no connection between registering the help file and building either of them.  You only have to register the help file with a help collection if you want to be able to link to it from the other help file, it doesn't have anything to do with building it or using SHFB.  The warning is because it can't find the noted class for some reason.  In that case, you won't have a clickable link in the help file at all.  Do you see any messages in the log from the plug-in?  Have you checked to make sure it hasn't been disabled?  If you're still having problems, feel free to send me an example and I can take a look at it.  My e-mail address is in the About box and the footer of the pages in the help file.