Baffling problem with <code lang="vbnet"> and a folder called doc.

Topics: Developer Forum
Sep 5, 2012 at 5:25 PM

I have a documentation project that uses <code> in a conceptual help file. I found that setting lang="vbnet" (or cpp - I didn't try any others) prevented the code blocks from appearing in the result. Omitting lang or using lang="none" worked fine.

If I rename the folder containing the .shfbproj file from "doc" to "documentation" (or "doc_reduce", or a number of other things), the problem disappears.

I tried disabling CleanIntermediates, then "diff -r"ing the failed build in "doc" and the successful build in "doc_reduce", but I could only see trivial differences (eg where the full path was included in a file). The least trivial seeming differences were

diff -ru doc/Help/Working/conceptual.config doc_reduce/Help/Working/conceptual.config
--- doc/Help/Working/conceptual.config  2012-09-05 16:37:05.274680500 +0100
+++ doc_reduce/Help/Working/conceptual.config   2012-09-05 16:33:50.627286000 +0100
@@ -31,12 +31,29 @@
         <!-- Resolve code snippets -->
         <!-- Code block component configuration.  This must appear before the TransformComponent.
                                                 See also: PostTransformComponent. -->
-        <component id="Code Block Component" type="SandcastleBuilder.Components.CodeBlockComponent" assembly="C:\Program Files\EWSoftware\Sandcastle Help File Builder\SandcastleBuilder.Components.dll">
-          <basePath value="C:\svn\p1318\trunk\pc\KeystoneClient\KeystoneClient\doc\" />
+        <component type="SandcastleBuilder.Components.CodeBlockComponent" assembly="C:\Program Files\EWSoftware\Sandcastle Help File Builder\SandcastleBuilder.Components.dll" id="Code Block Component">
+          <!-- Base path for relative filenames in source attributes (optional) -->
+          <basePath value="C:\svn\p1318\trunk\pc\KeystoneClient\KeystoneClient\doc_reduce\" />
+          <!-- Connect to language filter (optional).  If omitted, language filtering is enabled by default. -->
           <languageFilter value="true" />
+          <!-- Allow missing source files (Optional).  If omitted, it will generate errors if referenced source
+                                                        files are missing. -->
           <allowMissingSource value="false" />
+          <!-- Remove region markers from imported code blocks.  If omitted, region markers in imported code
+                                                        blocks are left alone. -->
           <removeRegionMarkers value="false" />
-          <colorizer syntaxFile="C:\Program Files\EWSoftware\Sandcastle Help File Builder\Colorizer\highlight.xml" styleFile="C:\Program Files\EWSoftware\Sandcastle Help File Builder\Colorizer\highlight.xsl" copyImageUrl="../icons/CopyCode.gif" language="cs" tabSize="0" numberLines="false" outlining="false" keepSeeTags="false" defaultTitle="true" />
+          <!-- Code colorizer options (required).
+               Attributes:
+                                                                       Language syntax configuration file (required)
+                                                                       XSLT style file (required)
+                                                                       "Copy" image file URL (required)
+                                                                       Default language (optional)
+                                                                       Enable line numbering (optional)
+                                                                       Enable outlining (optional)
+                                                                       Keep XML comment "see" tags within the code (optional)
+                                                                       Tab size override (optional, 0 = Use syntax file setting)
+                                                                       Use language name as default title (optional) -->
+          <colorizer syntaxFile="C:\Program Files\EWSoftware\Sandcastle Help File Builder\Colorizer\highlight.xml" styleFile="C:\Program Files\EWSoftware\Sandcastle Help File Builder\Colorizer\highlight.xsl" copyImageUrl="../icons/CopyCode.gif" language="cs" numberLines="false" outlining="false" keepSeeTags="false" tabSize="0" defaultTitle="true" />
         </component>
         <!-- Transform -->
         <component type="Microsoft.Ddue.Tools.TransformComponent" assembly="C:\Program Files\Sandcastle\ProductionTools\BuildComponents.dll">

However, this is just comment presence and attribute ordering...

Do you have any idea why this could be? Currently I'm just happy that after ~2 hours of trying I can continue with the renamed directory...

Unfortunately I can't post the project file, and I haven't been able to recreate the problem with a minimal project yet, although I'm trying.

Sep 5, 2012 at 6:15 PM

OK, the problem appears to be with the help viewer. If I place the file: http://dl.dropbox.com/u/6650756/Documentation.chm

In C:\svn\p1318\trunk\pc\KeystoneClient\KeystoneClient\doc\Help, then when I open it I cannot see the code entry. If I put it in another directory, or rename any part of the path (including Documentation.chm) then I can see the code entry.

Could anyone try this out on their PC?

One theory I have for why it happens is that when the file has the non-working name, the help viewer also knows to open the window in the size/position it was last closed at, so maybe some registry entry or similar is causing the problem.

Coordinator
Sep 5, 2012 at 8:17 PM

I tried your example and it opened fine for me and I was able to see the code block.  I did have to unblock it first but that's normal as it wasn't built on my system.  I do know that the help viewer has issues when the path contains a "#" but that's not the case here.  I can't think of any other known issues with naming that cause issues like that.

Eric

 

Sep 6, 2012 at 9:22 AM

Hi Eric, thanks for replying.

I guess that confirms that something in hh.exe's settings on my machine is screwy. I tried deleting user\Application Data\Microsoft\HTML Help\hh.dat but it had no effect. Couldn't see any other potential source in Process Monitor's output.

I do know that switching to the vs2010 style avoided the problem, so it's possibly something that could be worked around from your end, but I think for now I'm just going to hope whatever happened to get into this state doesn't happen again.