Links Between Project Outputs (HxS)

Topics: User Forum
Oct 9, 2007 at 7:02 PM
Hello,

I have two assemblies to document, Prodige.Drawing.dll and Prodige.Designer.dll, for the Html 2.x format. Assume they must be separately installable, and that the Designer assembly refers to Types defined in the Drawing assembly. I would like to create documentation for Prodige.Designer.dll that links to topics in the documentation for the other dll. If I exclude the namespaces from the documentation, I get no links at all. If I include them, I get links, but I also get the other dll documented.

Basically I want to treat links to Types and members as if they were framework links, to local content, not to a web file. I would like cross-project links. Is this possible using SHFB?

Thank you,
Frank Hileman
Coordinator
Oct 9, 2007 at 8:07 PM
I believe setting the ProjectLinkType to Index will do what you want. As long as the help files are in the same collection, they should work as it uses the index to look up the item. I don't know that much about how HTML Help 2 and the collections work. You may get a better response on the MSDN Documentation forum.

Eric
Oct 9, 2007 at 9:28 PM
Edited Oct 9, 2007 at 9:29 PM
Hi Eric,

Thanks for the response. I am using the Index link type. The problem I am having is the choice between:

- no links at all between, just text -- what happens when I chose to not document a namespace, or use dependencies instead of input assemblies

- links working but my project produces one output file (.HxS) with both dlls documented

So still I don't understand how to document each dll separately, yet allow one to link to pages defined in the other. If I do each separately I end up with no links. If I put them together I get good links but they are all in one .HxS document. I alreay have an existing .HxS for one of the dlls, that is why I wanted the other just to link to it, the same way it does the framework types, such as Object.

Thanks,
Frank
Coordinator
Oct 10, 2007 at 2:43 AM
If it can't find a link it automatically gets rendered as a bold, non-clickable link so if you omit a class or a namespace, it won't break anything. If you've put both assemblies in the same project such that they are documented in the same help file, use the Local option for the ProjectLinkType property and everything will be fine. If you create two separate projects, one for each assembly thus producing two HxS files, that's when you'd use the Index option as I understand it. In that case, you'd also have to add another target element to the ReferenceLinksComponent2 section of the sandcastle.config file for the assembly that isn't in the project. That's how it resolves links to other non-project assemblies such as the Framework assemblies. The help file builder isn't set up to handle non-framework assemblies. There's an open work item to add support for something like that but I haven't been able to work on it yet.

Eric
Oct 10, 2007 at 6:22 AM
Hi Eric,

That's it, I need to be able to distrubute simply the one help file, for the "core" dll, then possibly the second one. So the second dll relies on the first and its documentation needs to be able to link to the first, but they are installed separately (never the second without the first).

I found this, but have no idea how to edit this type of "code", or if it is what you are talking about. I searched for ReferenceLinksComponent2 and have not found any information yet:

<component type="Microsoft.Ddue.Tools.ResolveReferenceLinksComponent2" assembly="%DXROOT%\ProductionTools\BuildComponents.dll">
<targets base="%DXROOT%\Data\Reflection" recurse="true" files="*.xml" type="msdn" />
<targets files=".\reflection.xml" type="local" />
</component>

It seems everything in sandcastle is loaded dynamically via these files?

Thanks,
Frank
Coordinator
Oct 10, 2007 at 8:33 PM
For the time being, what you'd have to do is modify the templates to include a <targets> element for your additional XML file. For example:

<targets files="C:\SomeFolder\MyAdditionalAssembly.xml" type="index"/>

It wouldn't hurt any other projects. It would be loaded but wouldn't do anything as it wouldn't match any items in the other projects.

Eric
Oct 10, 2007 at 11:01 PM
Thanks again, Eric. Is the xml file an output from a sandcastle build step, or is that the normal xml file containing the xml comments (as for intellisense) from a Visual Studio build?

Thanks,
Frank
Coordinator
Oct 10, 2007 at 11:15 PM
The sandcastle.config is created from a template in the .\Templates folder under the SHFB installation folder. There are three (one for each style): Hana.config, Prototype.config, and VS2005.config. The XML file to add to the <targets> element is the reflection.xml file generated by the build. You can get it by setting the CleanIntermediates property to false, doing a build, and then copying it out of the .\Working folder under the output folder.

Eric
Oct 13, 2007 at 3:21 PM
Edited Oct 13, 2007 at 3:22 PM
Hi Eric,

Thanks, that was the information I needed to figure it out. The links work great now. Links work even to ndoc-generated documentation, because Index-style links only use the data type and member name to resolve a link. I tried generating the reflection file with SHFB and linking to previously installed ndoc created documentation, and it worked great. Note that the "core" dll, that the second dll depends on, should not be specified as a dependency of the second dll.

Here are a couple enhancements to SHFB that would make this simpler:

  • A property, SaveReflectionFile, indicating to save the reflection.xml file in the normal output folder, but with the name <documentation file name>.reflection.xml. This handles the generation of the "core" dll documentation. That naming convention and location would be good enough, I don't think it needs to be more fancy (custom name/location). This is just so we don't have to leave the other intermediate files around.
  • For generation of the documentation of the second assembly, a property, ReflectionFiles, specifying a collection of relative or absolute paths to reflection xml files. These paths would be inserted as targets elements in ResolveReferenceLinksComponent2 in the generated sandcastle.config file.

With those enhancements, building the documentation would be a breeze. Just build for one dll, then the other.

In order to replace ndoc for the .HxS style output we need the xml data islands at the top of each topic page. I am going to post this problem in the sandcastle forum, because I think it is a limitation of sandcastle? It is not a big change but without it we cannot show up under ".NET Framework", "Visual C#," etc filters applied to the table of contents. Visual Studio F1 does not work correctly for members either without the data island.

Thanks,
Frank
Coordinator
Oct 13, 2007 at 9:41 PM
I think your requests will be covered by the planned plug-in described in this work item: http://www.codeplex.com/SHFB/WorkItem/View.aspx?WorkItemId=7488.

Eric
Oct 15, 2007 at 3:23 PM
Edited Oct 15, 2007 at 3:25 PM
Would the planned plug-in re-generate the reflection files each time? Because that is a slow process, really I just want to save the output from the first documentation pass, then use it on the second.
Coordinator
Oct 15, 2007 at 6:19 PM
At this point I haven't really given it much thought. It could be made an option I suppose.

Eric