Hi Foks,
First let me say, GREAT product. I can't wait to see it develop further.
Second, I'm having a problem. Every help file I create with Sandcastle results in a CHM file that has a blank opening page. The Namespaces node is selected, but the Namespaces help page isn't displayed unless the user clicks on the root node again.
Any ideas?
Thanks!
George
George,
You can get Sandcastle to include information on the opening page by providing a "project" description. The easiest way to accomplish this that I've found is to create a project summary XML file that has the following format:
<?xml version="1.0" ?>
<doc>
<members>
<!-- Description about the project. -->
<member name="R:Project">
<summary>
A description of your project goes here. This will appear
on the opening page.
</summary>
</member><!-- Description of a namespace, "SomeNameSpace". -->
<member name="N:SomeNameSpace">
<summary>
Description of namespace, SomeNameSpace.
</summary>
</member>
</members>
</doc>
Note that the above also provides a summary for a namespace, SomeNameSpace. Use <para> and <code> tags within the <summary> as required.
Get Sandcastle to include this information by adding a line similar to
<data files="D:\Projects\MyProject\project_summary.xml" />
to the section in sandcastle.config that copies in comments. Look for the XML comment, <!-- Copy in comments -->, and add the <data> element to the others already present in the corresponding <input> element.
All this presumes you're using the August CTP, of course.
— Eric —
It sounds like you might be using the July CTP. Be sure to download and install the August CTP as it fixes that issue. If you are looking for a more flexible solution to creating help files with Sandcastle and/or have used NDoc in the past, you might like to check out my help file builder which has a GUI and console mode front end to Sandcastle. It can be found at http://www.codeproject.com/useritems/SandcastleBuilder.asp . I'll have a new version out in a day or so with some bug fixes, enhancements, and new features.
Eric
Hi and thanks for the replies.
First off, I have created an additional namespace/project summary XML file as you described. My descriptions ARE visible in the resulting CHM file, but only if the user activly clicks on the Namespaces root node in the tree. By default that page isnt displayed, but the Namespaces node IS selected... it's rather weird..
EWoodruf, due to some draconic download policies at my company, it is rather difficult to (Read almost impossible) to get the green light for utilities/code downloaded from third parties. I'd *Love* to use your slick GUI implementation, but can't so it's all cmd files for me :(
Eric, I thought that I had downloaded the august release, but to be honest I'm not totally sure. I'll have to check again on Monday when I get back to the office.
Thanks a million guys.
Ok I couldnt wait to find out, so I remoted in to check... the version of sandcastle.msi appears to be the August CTP version. The file size matches exactly at 6858kb.
Is it possibly something with my HTML Help compiler verion? I'm using the one that was pre-installed on my PC at the office, so I have no clue if it is dated.
The version of hhc.exe is 4.74.8702.0
The version of MRefBuilder.exe is 2.0.2424.18753
The version of XSLTransform.exe is 2.0.2428.25985
The version of BuildAssembler.exe is 2.0.2426.28539
Oh and I"m using .NET 2.0.
Thanks!!!
Edit: just to be sure, I unistalled sandcastle and redownloaded it from microsoft... no dice.
It certainly appears you're using the August CTP. All the versions you mentioned above (include hhc.exe) are exactly what I'm using. I'm also using .NET 2.0 and do my builds via the command-line tools. [I've been planning on trying out Eric Woodruff's GUI front-end.]
It may be a bit of a wild goose chase, but what version of hh.exe are you using to display the resuling CHM file - my version is 5.2.3790.2453 (WinXP SP2). I doubt this is the cause, but since you've been checking file versions, it's a quick check (look in your C:\WINDOWS directory).
A much more likely possibility is that the Default Topic in the help project file (.hhp) is empty or missing. When that happens, you get exactly the behavior you describe. Look for a line like this:
Default Topic=html/d4648875-d41a-783b-d5f4-638df39ee413.htm
in the [OPTIONS] section of the .hhp file. Note that the actually file name may differ from what's shown.
— Eric —
It certainly appears you're using the August CTP. All the versions you mentioned above (include hhc.exe) are exactly what I'm using. I'm also using .NET 2.0 and do my builds via the command-line tools. [I've been planning on trying out Eric Woodruff's GUI front-end.]
It may be a bit of a wild goose chase, but what version of hh.exe are you using to display the resuling CHM file - my version is 5.2.3790.2453 (WinXP SP2). I doubt this is the cause, but since you've been checking file versions, it's a quick check (look in your C:\WINDOWS directory).
A much more likely possibility is that the Default Topic in the help project file (.hhp) is empty or missing. When that happens, you get exactly the behavior you describe. Look for a line like this:
Default Topic=html/d4648875-d41a-783b-d5f4-638df39ee413.htm
in the [OPTIONS] section of the .hhp file. Note that the actually file name may differ from what's shown.
— Eric —
The only other possibility that I can think of is that you haven't updated your scripts to include the two new transformations that create the help compiler project file (ReflectionToChmProject.xsl) which sets the default topic and the other that creates the index page (ReflectionToChmIndex.xsl). Check steps 9 through 12 at http://blogs.msdn.com/sandcastle/archive/2006/07/29/682398.aspx to see if you've missed one of the new steps.
Eric
Hi George,
The reason that the first page is displaying an icon is because that icon was the first file in the list of files that
was included in the html-help-builder process. I've fixed this problem in my SandcastleGUI-program.
I manually add an index.htm as the first file (so this will be displayed automatically when the chm opens).
This index.htm is an copy of the file that I presonally prefer as the start page.
(see http://www.inchl.nl)
Kind regards,
Stephan
Eric!!
That was it. I was using someone's buld batch file that must have been created prior to the release with those new xsl transforms. I've added that information to my batch file, and now I have the Namespace page coming up first and ALSO I have a slick new index!!!! TY!
Stephan,
You are also correct. In the vaccume created by the missing xforms, It appears that the first file linked in becomes the default page. You might want to double check your build scripts for the presence of these transformations as well.
Thank you all for you kind help.
-G
