Problem with help file compilation...

Topics: Bugs, General Questions
Jul 6, 2007 at 1:28 PM
Hi,
I`ve installed sandcastle, DocProject and HTML help workshop in my PC. Then I uninstalled them and again reinstalled all three programs. And when I tried to build a documentation project, the build process failed and the following error appeared:

Error 1 The "C:\Program Files\Html Help Workshop\hhc.exe" process failed with exit code: 1.

What I should do to fix that?
Coordinator
Jul 6, 2007 at 2:00 PM
Hi,

I need to see more information about the error. Try it again and when the build fails open the build output window. Near the bottom should be a more detailed error message. Also check the Application event log for other error events where the source is DocProject. You can post the information here or send it to me using my website's contact form.

Thanks,
Dave
Aug 24, 2007 at 7:48 PM
I too am having this problem. Here is the contents of the Output window from just before errors and warnings start appearing:

Step 8 of 13: Build Assembler {sandcastle.help1x.config}

Info: Instantiating component.
Info: Loading data file '..\..\Presentation\Style\Transforms\skeleton.xml'.
Info: Instantiating component.
Info: Searching for files that match 'reflection.xml'.
Info: Found 1 files.
Info: Searching for files that match 'C:\Program Files\Visual Studio 2005 SDK\2007.02\VisualStudioIntegration\Tools\Sandcastle\\Data\cpref_reflection\*.xml'.
Info: Found 1 files.
Info: Indexed 149234 elements.
Info: Instantiating component.
Info: Instantiating component.
Info: Loading subcomponents.
Info: Instantiating component.
Info: Loaded 1 subcomponents.
Info: Instantiating component.
Info: Instantiating component.
Info: Loaded 3 syntax generators.
Info: Instantiating component.
Info: Searching for files that match 'comments.xml'.
Info: Found 0 files.
Info: Searching for files that match 'C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\*.xml'.
Info: Found 65 files.
Info: Indexed 75461 elements.
Info: Instantiating component.
Info: Loading subcomponents.
Info: Instantiating component.
Info: Instantiating component.
Info: Instantiating component.
Info: Loaded 2 subcomponents.
Info: Instantiating component.
Info: Instantiating component.
Info: Loading shared content file '..\..\Presentation\Style\content\shared_content.xml'.
Info: Loading shared content file '..\..\Presentation\Style\content\reference_content.xml'.
Info: Loading shared content file '..\..\Presentation\Style\content\syntax_content.xml'.
Info: Loaded 199 shared content items.
Info: Instantiating component.
Info: Indexed 149234 reference link targets.
Info: Instantiating component.
Info: Building topic R:Project
Info: Preparing to query MSDN topic URL web service.
Info: Building topic N:
Info: Building topic T:<Module>
Info: Building topic N:Test1
Info: Building topic T:Test1.Class1
Info: Building topic T:Test1.Class1.Members
Warn: Missing shared content item 'membersTopicTitle'.
Warn: Missing shared content item 'membersTopicTitle'.
Warn: Missing shared content item 'Publicmethod'.
Warn: Missing shared content item 'Protectedmethod'.
Warn: Missing shared content item 'Publicconstructor'.
Warn: Missing shared content item 'Publicproperty'.
Warn: Missing shared content item 'membersTopicTitle'.
Warn: Missing shared content item 'membersTopicTitle'.
Info: Building topic T:Test1.Class1.Constructors
Warn: Missing shared content item 'constructorsTopicTitle'.
Warn: Missing shared content item 'constructorsTopicTitle'.
Warn: Missing shared content item 'Publicconstructor'.
Warn: Missing shared content item 'constructorsTopicTitle'.
Warn: Missing shared content item 'constructorsTopicTitle'.
Info: Building topic T:Test1.Class1.Properties
Warn: Missing shared content item 'propertiesTopicTitle'.
Warn: Missing shared content item 'propertiesTopicTitle'.
Warn: Missing shared content item 'Publicproperty'.
Warn: Missing shared content item 'propertiesTopicTitle'.
Warn: Missing shared content item 'propertiesTopicTitle'.
Info: Building topic T:Test1.Class1.Methods
Warn: Missing shared content item 'methodsTopicTitle'.
Warn: Missing shared content item 'methodsTopicTitle'.
Warn: Missing shared content item 'Publicmethod'.
Warn: Missing shared content item 'Protectedmethod'.
Warn: Missing shared content item 'methodsTopicTitle'.
Warn: Missing shared content item 'methodsTopicTitle'.
Info: Building topic M:Test1.Class1.#ctor
Info: Building topic P:Test1.Class1.FirstName
Info: Building topic M:Test1.Class1.GetFullName

Topics processed: 12

Step 8 Time Elapsed: 00:00:59.8228986

Step 9 of 13: Execute XslTransform

C:\Program Files\Visual Studio 2005 SDK\2007.02\VisualStudioIntegration\Tools\Sandcastle\\ProductionTools\XslTransform /xsl:"C:\Program Files\Visual Studio 2005 SDK\2007.02\VisualStudioIntegration\Tools\Sandcastle\\ProductionTransforms\ReflectionToChmProject.xsl" "C:\Documents and Settings\xxx.XXXCORP\My Documents\Visual Studio 2005\SandcastleTest\Test1\DocProject1\buildhelp\reflection.xml" /arg:"project=DocProject1" /out:"C:\Documents and Settings\xxx.XXXCORP\My Documents\Visual Studio 2005\SandcastleTest\Test1\DocProject1\DocProject1.hhp"

XslTransform (v1.0.0.0)
Copyright c Microsoft 2005-2006
Info: Applying XSL transformation 'C:\Program Files\Visual Studio 2005 SDK\2007.02\VisualStudioIntegration\Tools\Sandcastle\\ProductionTransforms\ReflectionToChmProject.xsl'.

Step 9 Time Elapsed: 00:00:08.7381762

Step 10 of 13: Execute XslTransform

C:\Program Files\Visual Studio 2005 SDK\2007.02\VisualStudioIntegration\Tools\Sandcastle\\ProductionTools\XslTransform /xsl:"C:\Program Files\Visual Studio 2005 SDK\2007.02\VisualStudioIntegration\Tools\Sandcastle\\ProductionTransforms\TocToChmContents.xsl" "C:\Documents and Settings\bworrall.AISCORP\My Documents\Visual Studio 2005\SandcastleTest\Test1\DocProject1\buildhelp\toc.xml" /out:"C:\Documents and Settings\bworrall.AISCORP\My Documents\Visual Studio 2005\SandcastleTest\Test1\DocProject1\DocProject1.hhc"

XslTransform (v1.0.0.0)
Copyright c Microsoft 2005-2006
Info: Applying XSL transformation 'C:\Program Files\Visual Studio 2005 SDK\2007.02\VisualStudioIntegration\Tools\Sandcastle\\ProductionTransforms\TocToChmContents.xsl'.

Step 10 Time Elapsed: 00:00:01.0160670

Step 11 of 13: Execute XslTransform

C:\Program Files\Visual Studio 2005 SDK\2007.02\VisualStudioIntegration\Tools\Sandcastle\\ProductionTools\XslTransform /xsl:"C:\Program Files\Visual Studio 2005 SDK\2007.02\VisualStudioIntegration\Tools\Sandcastle\\ProductionTransforms\ReflectionToChmIndex.xsl" "C:\Documents and Settings\xxx.XXXCORP\My Documents\Visual Studio 2005\SandcastleTest\Test1\DocProject1\buildhelp\reflection.xml" /out:"C:\Documents and Settings\xxx.XXXCORP\My Documents\Visual Studio 2005\SandcastleTest\Test1\DocProject1\DocProject1.hhk"

XslTransform (v1.0.0.0)
Copyright c Microsoft 2005-2006
Info: Applying XSL transformation 'C:\Program Files\Visual Studio 2005 SDK\2007.02\VisualStudioIntegration\Tools\Sandcastle\\ProductionTransforms\ReflectionToChmIndex.xsl'.

Step 11 Time Elapsed: 00:00:00.8284854

Step 12 of 13: Copy Directory

Deep move "C:\Documents and Settings\bworrall.AISCORP\My Documents\Visual Studio 2005\SandcastleTest\Test1\DocProject1\buildhelp\assembler\Output\html" to "C:\Documents and Settings\xxx.XXXCORP\My Documents\Visual Studio 2005\SandcastleTest\Test1\DocProject1\Html".

Step 12 Time Elapsed: 00:00:00.6252720

Step 13 of 13: Compile Help 1.x

C:\Program Files\Html Help Workshop\hhc.exe "C:\Documents and Settings\xxx.XXXCORP\My Documents\Visual Studio 2005\SandcastleTest\Test1\DocProject1\DocProject1.hhp"

Microsoft HTML Help Compiler 4.74.8702
Compiling c:\Documents and Settings\xxx.XXXCORP\My Documents\Visual Studio 2005\SandcastleTest\Test1\DocProject1\DocProject1.chm
HHC6000: Error: An internal file could not be created. Make certain there is enough disk space on the drive where you are compiling your file.
HHC5007: Error: Fatal navigational compilation error. This is likely the result of an invalid contents (.hhc) file.
The following files were not compiled:
Non-zero exit code: 1

Step 13 DaveSexton.DocProject.Engine.ExternalProcessException: Compile Help 1.x:
The "C:\Program Files\Html Help Workshop\hhc.exe" process failed with exit code: 1.

Build step execution complete.

Verifying output...
Done.

Total Time Elapsed: 00:01:20.2536612

Successful Steps: 12 of 13
Failed Steps: 1

DocProject1 help build failed.

Done executing task "BuildDocProject" -- FAILED.
Done building target "CoreBuildHelp" in project "DocProject1.csproj" -- FAILED.

Done building project "DocProject1.csproj" -- FAILED.

Build FAILED.

Time Elapsed 00:01:22.00
========== Rebuild All: 1 succeeded, 1 failed, 0 skipped ==========
Coordinator
Aug 24, 2007 at 9:38 PM
Hi,

A couple of things:

  • You should reinstall the latest version of Sandcastle since apparently you've installed the VS 2005 SDK after Sandcastle, which replaces the %DXROOT% environment variable (this is a known issue with the VS 2005 SDK).
  • Make sure that you are documenting at least one public type or else set the Documentation Scope property to Complete. For more information see How To Configure DocProject.
This is the line that tipped me off about the VS 2005 SDK being installed after Sandcastle:


Info: Searching for files that match 'C:\Program Files\Visual Studio 2005 SDK\2007.02\VisualStudioIntegration\Tools\Sandcastle\\Data\cpref_reflection\*.xml'.

As you can see the path is pointing to an older version of Sandcastle. The latest release notes warns of this issue.

I think people have also reported on the Microsoft forums that there is a bug in the Sandcastle June 2007 CTP that may produce an invalid TOC, but I can't seem to find that thread now. Try my first two suggestions and let me know if you need further assistance.

- Dave
Aug 27, 2007 at 3:50 PM
Dave

Thank you - you were right on the money.
I was also getting the invalid TOC issue but that was cleared up by this action. I would add that I un-installed Sandcastle, rebooted and installed it again only to have more issues. (Different errors but I soon linked these back to incorrect environment variables).
So I uninstalled Sandcastle again, did a repair on VS 2005 SDK, rebooted and then installed Sandcastle. I then created a brand new project (C# class library), added a brand new DocProject and all was fine apart from 2 warnings that always appear. They are

Step 8 of 13: Build Assembler {sandcastle.help1x.config}
......
Info: Instantiating component.
Info: Building topic N:Test2
Info: Building topic T:Test2.Person
Info: Building topic AllMembers.T:Test2.Person
Warn: Invalid referenceLink element.
Info: Building topic Properties.T:Test2.Person
Warn: Invalid referenceLink element.
Info: Building topic M:Test2.Person.#ctor(System.String)
Info: Building topic P:Test2.Person.FirstName

The class is defined as follows:

using System;
using System.Collections.Generic;
using System.Text;

namespace Test2
{
/// <summary>
/// This is my Person class which does amazing stuff
/// </summary>
public class Person
{
/// <summary>
/// Stores the christian name of the person.
/// </summary>
private string firstname;

/// <summary>
/// Allows controlled access to the persons first name value.
/// </summary>
public string FirstName
{
get {return firstname; }
set
{ if ((value.Length > 0) || (value != FirstName))
{
firstname = value;
}
}
}

/// <summary>
/// Constructor also sets the persons christian name.
/// </summary>
/// <param name="firstName"></param>
public Person(string firstName)
{
FirstName = firstName;
}
}
}

I am very new to Sandcastle and am still finding my feet. However if you have any ideas on why these warnings are appearing I would appreciate the help.

Thank you

Brian
Coordinator
Aug 27, 2007 at 4:52 PM
Hi Brian,

Glad to hear that you got things working.

The warnings that you see are generated by Sandcastle's ResolveReferenceLinksComponent2 build component, although it usually states that in the warning itself. Are you sure that %DXROOT% is pointing to the June 2007 CTP?

Anyway, these warnings are quite common and can usually be ignored. Hopefully the Sandcastle team will clean things up by the RTW or at least provide more information in the output as to what exactly is invalid.

- Dave
Aug 27, 2007 at 6:59 PM
Dave

Thanks again. I resolved the warnings issue - it would seem to be a hangover from the DocProject that I had already created when things were not installed and working fine. After posting my laat post on this issue I created a new DocProject on the same test class library and everything worked properly.

Still exploring this documentation tool but so far so good. Really great tool with simple tags and very professional output. Perfect for documenting API's.

Brian
Coordinator
Aug 27, 2007 at 9:00 PM
Cool :)

If you want some documentation and tutorials to follow checkout DocProject's Wikimap. Also check out Sandcastle's blog on MSDN.

Thanks for the feedback,
Dave