Platform and Version information

Topics: General Questions, Help 1.x/2.x, Sandcastle
Aug 18, 2008 at 6:19 PM
I'm a newcomer to DocProject and Sandcastle.

Short question: How do I add the "Platforms" (supported Windows versons) and "Version information" (supported .NET Framework versions) to my documentation? Similar to the VS2008 help.

I'm building three class libraries with one combined documentation file (just a CHM for now). Two of the libraries support .NET 2.0, but the third requires .NET 3.5.

I did some grepping around, and found utilities_reference.xsl, which processes some nodes under /document/reference/versions and /document/reference/platforms. I believe these are from a master combined xml file created by sandcastle.help1x.config, which uses Microsoft.Ddue (completely undocumented, even to Google) to generate /document/reference from some reflection information.

This is as far as I got. My XSLT is a bit rusty. Could anyone give some direction? I don't need to do anything really complex, just support Platforms and Version information.

Thanks,
       -Steve
Aug 18, 2008 at 7:44 PM
Hi Steve,

You can use the Version management project option to add version information to topics.  (Look under the Build category in the DocProject Properties window.)

If you're using project references for your sources then simply register older versions of the assemblies in the Version Management dialog.  If you're using external sources, then make sure to reference the latest version as the source and add older versions to the Version Management dialog.

Enter any string values as version names, just be sure to specify the exact same string for the version name when applied to multiple sources otherwise they'll be interpreted as different versions.

I haven't really looked into the Platforms section so I'll have to take a look at how it's implemented now and get back to you.

- Dave
Aug 19, 2008 at 12:42 AM
Dave -

Thanks for your reply.

When I mentioned "Version information", I did not mean versions of my assemblies. I meant like this:

<h1 class="heading"><span onclick="ExpandCollapse(versionsTitleToggle)" style="cursor:default;" onkeypress="ExpandCollapse_CheckKey(versionsTitleToggle, event)" tabindex="0"><img id="versionsTitleToggle" onload="OnLoadImage(event)" class="toggle" name="toggleSwitch" src="../icons/collapse_all.gif" />Version Information</span></h1><div id="versionsTitleSection" class="section" name="collapseableSection" style=""><h4 class="subHeading">.NET Framework</h4>Supported in: 3.5, 3.0 SP1, 3.0, 2.0 SP1, 2.0, 1.1, 1.0<br /><h4 class="subHeading">.NET Compact Framework</h4>Supported in: 3.5, 2.0, 1.0<br /><h4 class="subHeading">XNA Framework</h4>Supported in: 1.0<br /></div>

which is rendered as:


Version Information

.NET Framework

Supported in: 3.5, 3.0 SP1, 3.0, 2.0 SP1, 2.0, 1.1, 1.0

.NET Compact Framework

Supported in: 3.5, 2.0, 1.0

XNA Framework

Supported in: 1.0


I'll wager whatever creates this section uses reference_content.netfw and friends.

        -Steve
Aug 19, 2008 at 5:04 AM
Hi Steve,

Version Information

Using the Version Management dialog will generate the Version Information section, but with version information for your own assemblies.  The reason why you see .NET Framework version information in MSDN topics is because the documentation is for the .NET Framework itself.  The information on MSDN is probably generated using the same tools that DocProject uses.

There's currently no way to stuff .NET Framework version information into that section of your own topics without some manual effort.

To see how it works, add one or more versions to the Version Management dialog (although first follow the instructions for a work-around to a bug that I just discovered).  Then after building help, open your project's buildhelp\reflection.org file.  You'll see the version information from the Version Management dialog contained in versions elements with data that corresponds to the IDs in the buildhelp\assembler\version_content.xml file.  The built-in Sandcastle XSLT files use this information to generate the Version Information section.  Now, to add .NET Framework version information currently requires some effort on your part.

One approach that may work is to inject a dynamic build step after the Generate versioned reflection data build step.  It should analyze the source assemblies and versioned references that have been added to the Version Management dialog to collect information about which versions of the .NET Framework are being used (or you can just hard-code that information in some XML file in the project and have the build step load it using XmlDocument or LINQ to XML).  Then have it update the reflection.org file (generated in the buildhelp folder) and the version_content.xml file (buildhelp\assembler folder) to insert the .NET Framework version information.

Platforms

This feature doesn't appear to be supported by the built-in Sandcastle transformations at this time.  Although the Hana and vs2005 styles actually do provide support for a Platforms section in the main_reference.xsl file, that file does not appear to be used at all by Sandcastle.  The main_utilities.xsl file defines the template for the Platforms section however it's never called.  You may be able to update the transformations yourself to get platform information or you may want to submit a feature request to Sandcastle and then I'll support it in a subsequent release of DocProject.

If you want to add platform information yourself you can either hard-code it into the XSLT or if it must change depending upon the topic, then use one or more custom tags in your XML documentation comments.  To support a custom tag you must create a new XSLT template in main_sandcastle.xsl that matches your tag.  Check the existing templates for examples of how common XML documentation tags are applied.

- Dave
Aug 19, 2008 at 4:18 PM
If "Platforms" is related to the "Frameworks" dropdown, there's an open work item for it (Item B):  http://www.codeplex.com/Sandcastle/WorkItem/View.aspx?WorkItemId=939

Eric
Aug 19, 2008 at 4:43 PM
Thanks Eric.

I do think they're related - we should look into this for the Sandcastle Styles project.

- Dave
Aug 22, 2008 at 6:39 PM
Dave & Eric -

Thanks much for your responses.

I want to avoid modifying the build scripts at all, just because this would essentially create a custom branch off of Sandcastle/DocProject, and this would require merging with updates on the public releases, etc. I'm a bit too busy with my other work to really tackle the learning curve this would necessitate. (I was hoping that these were supported already, and I was overlooking how to do it).

So, I'm thinking I'll just add some custom tags to my xml docs, and have a post-build step convert these into regular text before it gets fed into DocProject.

I won't get the "expand" functionality, but I'm not terribly concerned about that.

Thanks again - and thank you very much for putting so much time into this project!
     -Steve
Aug 22, 2008 at 8:48 PM
Hi Steve, 

A post-build step is a fine solution, although I'm not sure why you think a different source control branch would be required if you were to use my previous suggestions.

A dynamic build step can be added by updating your project's BuildProcess.cs (or .vb) file.  The XSL transformations are located in the project's Help\Presentation\Style\Transforms folder and can be modified freely by developers working on the project.  When you commit changes to the trunk all developers on the project will be able to get the latest version that has the updated build process since all of the updated files are already part of the project.  No changes to DocProject or Sandcastle are required.

This means that changes to those files will only apply to a single DocProject or DocSite.  However, if you want to apply the updates to multiple projects then you can create a custom Build Process Component in a standalone assembly and register it in place of the default BuildProcess.cs|.vb file, or you can create a custom build engine provider.  If you need to modify the XSLT then update the files in the Sandcastle installation folder to have an effect on all new DocProjects and DocSites that are created after you make the changes.

This is just FYI in case you find the time to take advantage of these features.

- Dave
Aug 23, 2008 at 1:16 PM
Dave -

Thanks for your suggestions. I'll definitely look into the custom build process component (reading the Wiki now).

Regarding trunk/branch, I didn't mean in my source control. I meant that whatever XSLT I change for my project would be different than what DocProject has. I could change it system-wide as well, as you suggested, but this still creates a different set of XSLT files than DocProject.

My concern is whenever Sandcastle/DocProject is updated, I would want to easily upgrade (i.e., without merging XSLT files from my "branch" and DocProject's "trunk").

The Build Process Component / Build Engine Provider approach may be a cleaner solution. This is really a very well-designed project! (The only suggestion I'd have is a brief "what's all this stuff in my DocProject project" document, explaining what the different files are used for, which ones should go in source control, and how changing them would affect upgrades).

Thanks for your patient guidance, Dave.

       -Steve
Aug 23, 2008 at 4:37 PM
Hi Steve,

I see what you mean now :)

Note that DocProject's New Project Wizard has an Import Topics and Settings step that will help you to upgrade DocProject's files between new releases.  All of the remaining files in your project such as the CSS, XSLT and Build Assembler .config files, are provided by Sandcastle.  Changing them locally will make them different than the versions that Sandcastle provides, although it seems new versions of Sandcastle aren't being released very often anyway, if that's any consolation.

> what's all this stuff in my DocProject project

Good question.  Much of the content is imported directly from Sandcastle, so really Sandcastle itself could use some documentation explaining its various files.  I'll look into writing it for the first Production release of DocProject (1.12.0) since I'm also documenting DocProject itself for that release.  Documentation will also include a description of DocProject and DocSite project layout and the purpose of the various files that are provided by DocProject.

Thanks for the feedback, 
Dave