Tips: Introducing CloneComponent

Aug 6, 2008 at 3:09 PM
Edited Jul 20, 2009 at 8:29 PM

Hello All,
This is a simple but useful tip to enhance your build experience. While working on a simple builder library, originally meant for testing our work at Sandcastle Assist, I needed a better means of handling multiple output formats in a single build run and found the CloneComponent, which is part of the default Sandcastle distribution useful and designed for exactly this type of build requirements - branches.

Using It
The configuration is simple, it introduces only a single tag, branch:



      <component type="Microsoft.Ddue.Tools.CloneComponent"
                 assembly="%DXROOT%\ProductionTools\BuildComponents.dll">
          <branch>
              <!-- Create a branch here ...-->
          </branch>
      </component>



Now, the default build assembler steps (for the Vs2005 are shown below)


 

              <!-- resolve reference links -->
            <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>

            <!-- save the result -->
            <component type="Microsoft.Ddue.Tools.SaveComponent"
                       assembly="%DXROOT%\ProductionTools\BuildComponents.dll">
              <save base =".\Output\html" path="concat(/html/head/meta[@name='file']/@content,'.htm')" indent="true" omit-xml-declaration="true" />
            </component>



Using the clone component we could rewrite this for multiple outputs as,


      <component type="Microsoft.Ddue.Tools.CloneComponent"
                 assembly="%DXROOT%\ProductionTools\BuildComponents.dll">
          <branch>
              <!-- resolve reference links -->
            <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>

            <!-- save the result -->
            <component type="Microsoft.Ddue.Tools.SaveComponent"
                       assembly="%DXROOT%\ProductionTools\BuildComponents.dll">
              <save base =".\Output\html" path="concat(/html/head/meta[@name='file']/@content,'.htm')" indent="true" omit-xml-declaration="true" />
            </component>
          </branch>
          <branch>
              <!-- resolve reference links -->
            <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="index" />
            </component>

            <!-- save the result -->
            <component type="Microsoft.Ddue.Tools.SaveComponent"
                       assembly="%DXROOT%\ProductionTools\BuildComponents.dll">
              <save base =".\Output\html2" path="concat(/html/head/meta[@name='file']/@content,'.htm')" indent="true" omit-xml-declaration="true" />
            </component>
          </branch>
      </component>


 
Applications In Current Tools
Sandcastle Help File Builder:  This is the NDoc clone for Sandcastle. One part of the NDoc that is not implementated in the SHFB is the ability to configure the outputs individually, and I think it was done to make it possible to build multiple outputs in one run. However, there is this issue of links. For Help 2.x, you will normally  use "index" option and for Help 1.x, you will normally use the "local". With the use of the CloneComponent, the SHFB can allow the links of both output to be set differently and still achieve multiple outputs in single build.

DocProject: To make it possible to set the different links for Help 1.x and Help 2.x, the DocProject creates multiple configuration files "sandcastle.help1x.config" for Help 1.x and "sandcastle.help2x.config" for Help 2.x, the difference between them is just the link. The result is, DocProject runs the build assembler twice, and the user could pay the price in speed. 

Conclusion
The CloneComponent could be a useful component for this and related purpose, the only issue/problem in this particular case is that the data stored in the ResolveReferenceLinksComponent2 component is not static and having two or three of them will consume more memory. A better link component, which may use database for storage of the targets is planned for Sandcastle Assist's LinkComponent.

Best regards,
Paul.

Editor
Aug 6, 2008 at 4:11 PM

Thanks for the information Paul.  I'll see about supporting it in a future release of SHFB.

Eric

 

Aug 6, 2008 at 4:47 PM
Nice find, thanks.

- Dave