<code> lang and title attributes not being recognized

Sep 25, 2008 at 6:29 AM
I'm frustrated with this problem -- I am tagging my code with <code lang="cs"></code>, as well as using the title attribute, but when I run Sandcastle, the .chm files that it is generating do not have the code sample tagged with either the language or the title at the beginning of the sample.  Also, the code sample is not colored accordingly.  In addition, when I filter the .chm by language, it doesn't recognize the code as C#.

Any ideas what I might be doing wrong?  I am running sandcastle by using the scbuild.ps1 powershell script which is in the ProductionTools subfolder.  Should I be running it a different way, or can anyone suggest anything else?  It almost seems like it is only recognizing the very basic tags and none of the attributes.

Thanks very much,
-Steve
Coordinator
Sep 25, 2008 at 2:58 PM
Edited Sep 25, 2008 at 2:58 PM

Code colorization is handled by the Code Block and Post Transform components which are custom components not supplied in the default Sandcastle installation.  In order to use them, you need to merge their configurations into the sandcastle.config file (used by BuildAssembler) in the correct locations.  If you want to do this manually, download the standalone build components and follow the instructions in its help file to merge the configuration info.

The easiest way to use them is just to use the help file builder as it contains those two components in its configuration file by default.  You can override their settings using the ComponentConfigurations property if necessary.  In addition, it handles all of the other configuration and management tasks and hides all of the details of using the Sandcastle tools.  There's a console mode version of the builder as well so you can integrate that into custom build scripts, project post-build events, etc.

Eric

Sep 25, 2008 at 5:49 PM
Thanks Eric!  That helped a lot.  I have it working now.

One question, the title of my CHM file is "A Sandcastle Documented Class Library".  What parameter do I pass in to the commandline tool to change this name.

I am using -HTMLHelpName already, but that seems to only override the file name..

Thanks
Sep 25, 2008 at 6:10 PM
Actually I found this parameter by digging through the help.

Another one -- I have some missing summary warnings being generated:
[Missing <summary> documentation for N:]

How can I either suppress these through command line options, or where in the code should I be doing the <summary> for my Namespaces?

Thanks
Coordinator
Sep 25, 2008 at 7:25 PM
Edited Sep 25, 2008 at 7:25 PM
If you just want to suppress the warnings, you can pass -ShowMissingNamespaces=false to the console mode builder or set the matching project property to false in the GUI.  The same applies to any other "missing documentation" warnings in the help file for such things as parameters, return values, etc.  In order to supply namespace summaries, you have several options:

  • You can add them to the project using the GUI via the Namespaces button to the right of the Assemblies to Document list.
  • You can add them using an XML comments file.  Add the comments file to the project and set its CommentsOnly property to true (use the -comments option if passing it to the console mode builder without a project).  See the Sharing Summary and Namespace Settings Between Projects topic in the help file for info on the file format.
  • You can add a class called NamespaceDoc to each namespace and apply the comments to it.  See the Using a NamespaceDoc Class section of the Project and Namespace Summaries topic in the help file for details.

Eric

Oct 26, 2009 at 8:57 PM

Hi Eric!

This solution apparently is not working for me.

My sandcastle.config file looks fine, but i still can't coloring the syntax of my sample code.

Those are the sections that i looked:

<!-- 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:'))" />
          <then>
            <component type="Microsoft.Ddue.Tools.SyntaxComponent" assembly="%DXROOT%\ProductionTools\BuildComponents.dll">
              <syntax input="/document/reference" output="/document/syntax" />
              <generators>
                 <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" />
              </generators>
            </component>
          </then>
        </component>

<!-- transform -->
        <component type="Microsoft.Ddue.Tools.TransformComponent" assembly="%DXROOT%\ProductionTools\BuildComponents.dll">
          <transform file="%DXROOT%\Presentation\vs2005\Transforms\main_sandcastle.xsl">
            <argument key="metadata" value="true" />
             <argument key="languages">
              <language label="VisualBasic" name="VisualBasic" style="vb" />
              <language label="CSharp" name="CSharp" style="cs" />
              <language label="ManagedCPlusPlus" name="ManagedCPlusPlus" style="cpp" />
      <!--<language label="JSharp" name="JSharp" style="cs" />
              <language label="JScript" name="JScript" style="cs" />-->
          <language label="JavaScript" name="JavaScript" style="cs" />
            </argument>
          </transform>
        </component>

I have more than one language with the "style" attribute equals to "cs".. I tried change my "code lang" to "vb" and "cpp", but it still not works.

Thanks!

Coordinator
Oct 27, 2009 at 3:13 PM

Are you using SHFB or just the standalone build components with your own build script or another community tool?  If it's the latter, you need to manually add the CodeBlockComponent and PostTransformComponent configurations into your Sandcastle.config file.  See the supplied help file for details.

Eric

 

Oct 27, 2009 at 4:51 PM

Hi Eric!

Actuality, i was using DocProject...
I made a try with SHFB and it works fine!

So, to continue using DocProject i need put the CodeBlockComponent and PostTransformComponent in the Sandcastle.config file, right?

Thanks for your help!

Coordinator
Oct 27, 2009 at 7:40 PM

Yes.  You can copy the example configurations from the help file.  You'll just need to supply absolute paths to the component assemblies and the other files that they reference.

Eric