SHFB 1.9.6 and Custom Presentation Style problem

Topics: Developer Forum, Project Management Forum, User Forum
Dec 21, 2012 at 9:10 AM
Edited Dec 21, 2012 at 9:14 AM

 Hi!

We have a custom presentation style that is a copy of vs2005 with only a few changes in two files; utilities_reference.xsl and Presentation.css. In the old version this was easy and worked very well; just have the new style in a folder in the Sandcastle path.

Now with this release it has been totally changed, and I must say that I can't get it to work. I have tried to follow the walkthrough at http://www.ewoodruff.us/shfbdocs/?topic=html/4bc61ac3-ac19-4c8b-9ff9-95aaefa0b18e.htm without success and the information about the different elements in the configuration file is not that clear.

This is what I did:

  1. Copied vs2005 from the upgraded Sandcastle presentation folder to %ProgramData%\EWSoftware\Sandcastle Help File Builder\Presentation Styles.
  2. Renamed the folder to a custom name.
  3. Changed the above two files as per my requirements.
  4. Created a SharedContent folder and copied the required files (started to get worried here. Why are they needed?).
  5. Created a .presentation file. Modified this as per my new style.
  6. Compiled.

Even though I finally got the help to compile successfully, the result is not at all as expected. The style does not look like the old style, icons are missing and I get script problems.

My guess is that there is some problem with the ReferenceBuildConfiguration element. I have changed this to %SHFBROOT%\Templates\VS2005.config. But again, it's not clear what this should be.

How can I get this to work? It's just two simple files that have changed, but it seems very complicated now. Note that when I compile the help file with the default vs2005 style, it works perfect.

This is part of my .presentation file:

<PresentationStyles>
  <PresentationStyle ID="vs2005_Wcf"
                     Title="vs2005 Wcf Style"
                     BasePath="">
 
    <Description>Presentation style used for documenting Wcf projects in chm format.</Description>
 
    <SupportedFormats>
      <Format Type="HtmlHelp1" />
    </SupportedFormats>
 
    <HelpContent>
      <Files Source="Icons\*.*" Destination="Icons" />
    </HelpContent>
 
    <ResourceItems Path="Content">
      <ToolResourceItems Path="SharedContent" />
    </ResourceItems>
 
    <DocumentModelTransformation File="%DXROOT%\ProductionTransforms\ApplyVSDocModel.xsl">
      <Parameter Name="IncludeAllMembersTopic" Value="true" />
      <Parameter Name="IncludeInheritedOverloadTopics" Value="false" />
      <Parameter Name="project" Value="{@ProjectNodeIDOptional}" />
    </DocumentModelTransformation>
 
    <IntermediateTOCTransformation File="%DXROOT%\ProductionTransforms\CreateVSToc.xsl" /> 
    <!--NOTE: This example assumes you have made a copy of the SHFBconfiguration file. If not change the path to "%SHFBROOT%\Templates\Conceptual.config"-->
    <!--<ConceptualBuildConfiguration File="Configuration\CustomConceptualBuild.config" />-->
    <ConceptualBuildConfiguration File="%SHFBROOT%\Templates\conceptual.config" />
 
    <!-- NOTE: Thisexample assumesyou havemade acopy ofthe SHFBconfiguration fileIf notchange thepath too"%SHFBROOT%\Templates\VS2005.config" -->
    <!--<ReferenceBuildConfiguration File="Configuration\CustomAPIBuild.config" />-->
    <ReferenceBuildConfiguration File="%SHFBROOT%\Templates\VS2005.config" />

/Staffan

Coordinator
Dec 21, 2012 at 3:11 PM
Edited Dec 21, 2012 at 3:12 PM

When you copied the shared content files, did you rename them as indicated in the walkthrough by changing the "VS2005" prefix to your custom style ID?  If not, that is one error.  They are required by SHFB to override the standard presentation style elements with items that import values from the SHFB project and need to be matched to the custom style.

The second error and the most likely cause of your problems is that you didn't specify all of the HelpContent items as in the example:

<HelpContent>
  <Files Source="icons\*.*" Destination="icons" />
  <Files Source="scripts\*.*" />
  <Files Source="styles\*.*" />
</HelpContent>

Using the standard conceptual and reference VS2005 build configuration files should be fine since you haven't changed them.

Eric

 

Jan 2, 2013 at 1:44 PM

Great! The two elements for "scripts" and "styles" in the HelpContent element helped.

/Staffan