mixing conceptual and reference guide help

Sep 6, 2010 at 1:08 PM

I've been using Sandcastle for some time with plugins and producing output correctly.

I recently added in some extra content pages to the eventual CHM but the links to the files in the reference guide have to be hard coded to the pages using href tags. This means that I can't run my plugins through the extra pages.

I recently started tryin to mix the conceptual content into the mix to solve this problem, but so far have been unsuccessful.

Has anyone got an example of successully mixing conceptual help with the reference guide help? i.e. mixing the sandcastle.config an conceptual.config into a single.config?

The table of contents is something I can worry about later (along with the chm which will be ok), but for now i just want to process the content from both into a single config file so that my files can cross link between the two sets of documentation.

Sep 7, 2010 at 2:33 AM
Edited Sep 7, 2010 at 2:34 AM

>> I recently started tryin to mix the conceptual content into the mix to solve this problem, but so far have been unsuccessful.

The conceptual content is really powerful and extensible, and should be able to meet your needs.

>>Has anyone got an example of successully mixing conceptual help with the reference guide help?

Combining the conceptual and reference topics is simply. You do not need to combine the configuration files
since each is designed to act separately and differently.

What you will need to do is to split the build steps.

  1. The first set of steps create the reflections, combining the XML document comments and generating the reference TOC.
  2. You will need the reference files above to resolve the links in the conceptual topics.
  3. Create the conceptual TOC and merge that with the reference to form the final TOC.
  4. Build the conceptual topics to generate the HTML (running BuildAssembler the conceptual.config)
  5. Build the reference topics to generate the HTML (running BuildAssembler on the sandcastle.config)
  6. Making sure the output directory is the same for both the conceptual and reference tools.
  7. Finally run your build tools like the CHM and HXS compilers to complete the process.

You may use tools like SHFB and DocProject, which will perform these steps and more for you.
However, if you wish to completely control the build steps you can use my library at Sandcastle Assist.

NOTE: Splitting the build steps is all you need if you want to integrate your own contents, which are not Sandcastle
conceptual topics, since after running the BuildAssembler on the conceptual.config, you will get the HTML similar to
your own contents, so it is essentially the same. 

Both the DocProject and the Sandcastle Assist do not yet support the current Sandcastle release.
I have completed the support in the Sandcastle Assist, and was trying to complete some other changes in the build process this
weekend to upload the codes. However, I will be busy this weekend helping with a fun-raising concert for orphans.  The updates
will definitely be uploaded by Sept. 20.

Best regards,

Sep 7, 2010 at 9:13 PM

Can you describe your scenario in more detail?  You say you are using plug-ins to produce the output.  In what way?  Are you generating the conceptual topics at build time?  Linking from a MAML topic to an API topic is accomplished using the <codeEntityReference> element.  There is no equivalent for linking from an API topic (XML comments) to a MAML topic.  As you mentioned, you need to use an anchor tag with an href attribute that references the topic's page name (topic ID + ".htm").

The conceptual and API topic builds are distinct and must be done separately.  I doubt you could combine them into a single build using one configuration file.  In theory, you could put the configuration for just the ResolveConceptualLinksComponent from conceptual.config in sandcastle.config so that it handles any <conceptualLink> elements that it finds in the XML comments.  It would probably go just above the ResolveReferenceLinksComponent2.  You'd have to use <conceptualLink> elements rather than anchor tags to reference the MAML topics in the XML comments.  You'd still need to know the topic's ID so there's not much difference really and it may not be worth the effort since the anchor tag accomplishes the same thing.



Sep 16, 2010 at 3:40 PM
Edited Sep 16, 2010 at 3:44 PM

Ok I've found a way. Trick seems to be to use the IFThenComponent to switch between the two forms of document then resolve all other xml in the sandcastle config in a similar way.

This does mean you need to have a specific first few hex characters for the conceptual ids as well as different index names for the conceptual documentation from the VS generated xml.

for example the skeleton is:

                <component type="Microsoft.Ddue.Tools.IfThenComponent" assembly="%DXROOT%\ProductionTools\BuildComponents.dll">
                    <if condition="starts-with($key, '1234567')" />
                        <!-- Create skeleton document -->
                        <component type="Microsoft.Ddue.Tools.CopyFromFileComponent" assembly="%DXROOT%\ProductionTools\BuildComponents.dll">
                            <data file="%DXROOT%\Presentation\Vs2005\Transforms\skeleton_conceptual.xml" />
                            <copy source="/*" target="/" />
                        <!-- Create skeleton document -->
                        <component type="Microsoft.Ddue.Tools.CopyFromFileComponent" assembly="%DXROOT%\ProductionTools\BuildComponents.dll">
                            <data file="%DXROOT%\Presentation\vs2005\Transforms\skeleton.xml" />
                            <copy source="/*" target="/" />


also need to remove the syntax generators:

                <!-- Generate syntax -->
                <component type="Microsoft.Ddue.Tools.IfThenComponent" assembly="%DXROOT%\ProductionTools\BuildComponents.dll">
                    <if condition="not(starts-with($key,'Overload:') or starts-with($key,'R:')) and not(starts-with($key, '1234567'))" />
                        <component type="Microsoft.Ddue.Tools.SyntaxComponent" assembly="%DXROOT%\ProductionTools\BuildComponents.dll">
                            <syntax input="/document/reference" output="/document/syntax" />
                                <generator type="Microsoft.Ddue.Tools.VisualBasicDeclarationSyntaxGenerator" assembly="%DXROOT%\ProductionTools\SyntaxComponents.dll" />
                                <generator type="Microsoft.Ddue.Tools.CSharpDeclarationSyntaxGenerator" assembly="%DXROOT%\ProductionTools\SyntaxComponents.dll" />
                                <generator type="Microsoft.Ddue.Tools.CPlusPlusDeclarationSyntaxGenerator" assembly="%DXROOT%\ProductionTools\SyntaxComponents.dll" />
                                <!--<generator type="Microsoft.Ddue.Tools.ScriptSharpDeclarationSyntaxGenerator" assembly="%DXROOT%\ProductionTools\SyntaxComponents.dll" />-->


certain bits you might want to be conceptual Only:

            <component type="Microsoft.Ddue.Tools.IfThenComponent" assembly="%DXROOT%\ProductionTools\BuildComponents.dll">
                    <if condition="starts-with($key, '1234567')" />
                        <component type="Microsoft.Ddue.Tools.CopyFromFilesComponent" assembly="%DXROOT%\ProductionTools\BuildComponents.dll">
                            <copy base="%maml_dir%\metadata" file="concat($key,'.cmp.xml')" source="/metadata/topic[@id=$key]/*" target="/document/metadata" />


Sep 16, 2010 at 3:42 PM

forgot to add, thanks to you both for your suggestions.


Kind Regards

Les Baker