Latest version feedback

Topics: Developer Forum, Project Management Forum, User Forum
May 19, 2012 at 1:38 PM
Edited May 19, 2012 at 2:12 PM


just installed the new version of Sandcastle (first uninstalled the previous one). Then I installed the latest version of SHFB (without uninstalling the previous one). Here are a few things that I would like to ask/share:

- In my project I have two folders one with about 1000 files (contextual topics), another with 2400 images (png's), the toc file and about 10 assemblies added as documentation sources. Initially opening the solution takes quite a while. Trying to expand either of the folders also takes a while. Expanding the folder with 2400 images took about two minutes, and in this time VS was Not Responding. After the initial opening there is just a 2-3 seconds delay to expand these folders. Opening a context menu on the project or files is also delayed with  a couple of seconds. FYI the project takes about 200 MB in memory (from 8gb available).

1. Opened the toc file and double clicked a topic - the first time it took 10 seconds to open the file for edit.

2. Opening my project and trying to preview a conceptual file errors with: "A copy of the file does not appear to exist yet. It may need to be built."

3. I tried to build a chm (since this seems to be the reason for the above error) and this ended up with "  Could not find the path the the HTML Help 1 compiler.". The compiler is installed (I checked and the guided installation confirmed). However, I am on x64 machine and I noticed wrong paths in the project properties - see this image for details:

4. I have manually added the correct path in the project properties and I built the chm. Then when I opened a conceptual file and clicked "View Help File" it opened the whole CHM, while I want to see just this topic in the topic previewer.

5. The intellisense contains only some of the possible tags. For example <externalImage> is not there, <section> is not there. When <section> is manually typed in and hovered it seems it does not like the namespace - see image:

6. My opinion is that it will be useful to have the same menu as in SHFB: Especially the drop down with the possible tags, the html encoding, etc.

7. Most of the conceptual files, when selected in the topic previewer have this error:

Unable to convert topic file.  Reason(s):Unknown parent block element encountered for new block elementParsed content up to the point of failure follows.

8. It will be very convenient to have the F5 key to opening the preview of the currently edited conceptual file.


Q1. How can I add some tags to intelisense? I am particulary interested in <link>, <externalLink>.

Q2. How can I improve the performance while using VS?

That is all for now.

May 19, 2012 at 8:31 PM

Regarding #1, I doubt there's much I can do about the speed of Visual Studio.  The VSPackage relies on the MPF project which was not developed by me.  There may be some improvements that could be made to it to help with the project load time but I'd have to dig into it further to see.  Editing MAML topics is done using the standard XML file editor so that's entirely on Visual Studio and there's nothing I could do to speed that up.  My guess is you'd probably see a similar pause on first use if the topic was opened from the Solution Explorer as Visual Studio is most likely loading the compenents needed to instantiate the editor itself.

Regarding #2, that error will occur if you choose the View Help File option or just click the button on the SHFB toolbar for the default action and the help file has not been built.  You need to chose the Topic Previewer Window option to preview topics (View | Other Windows | Topic Previewer Window or select it off the Other Windows toolbar button dropdown).

Regarding #3, clear the path properties in the project and let the build engine find the tools for itself.  That should work on any system unless they are installed in a non-standard location such that you need to specify them.  Note that ProgramFiles32 is not, as far as I know, a standard environment variable.  If it's a project variable, it's most likely not set correctly due to the doubled "(x86)" in the value.  Correcting it's value would let it be used.

Regarding #4, as noted above, "View Help File" is not the same as "Topic Previewer" so use the Topic Previewer Window option not the View Help File option.

Regarding #5, externalImage is not a valid MAML element so I assume you mean externalLink.  If IntelliSense is not working, you probably haven't installed the IntelliSense XML schema files.  Try running the guided installer again and installing them in the given step.  If you installed the schemas manually instead of using the installer, they may not be in there correctly.  The installer may have seen the files and not overwritten them.  You can manually delete the files and the related catalog file from the schema cache and try installing them again.

Regaring #6, with IntelliSense in place, the use of a menu to insert the elements is redundant.  The HTML encoding option would be good to add but I haven't gotten around to seeing how that can be integrated into the standard XML editor.

Regarding #7, the topic previewer is less forgiving of ill-formed topics.  You are most likely missing the required <para> elements in such things as <listItem> and <entry> elements.  The MAML guide has been updated to reflect the proper structure with the required elements.  Refer to it for information.  Older versions of SHFB did not insert some of the elements in the proper format so they may need fixing if you want to preview them.  Sandcastle doesn't care about them missing at build time but the parser used to generate the topic for preview does.  The topics are rendered up to the point of failure so that should help you find the location of the invalid element.  With the MAML IntelliSense files property installed, that also helps as it will flag the invalid elements.

Regarding #8, I make no assumptions about hot keys and assign none to the SHFB commands to avoid potential conflicts.  They are left to the user to define.  You can use Visual Studio's options to define hot keys for any of the SHFB menu commands as you see fit just as you would for the standard Visual Studio commands.  See the Visual Studio topics in the SHFB help file for more information.

Regarding Q1, see #5 above regarding MAML IntelliSense as those elements are there once the schemas are properly installed.

Regarding Q2, see #1 above.  If you're building Help 2 or MS Help Viewer output, one option would be to break the project up into smaller more manageable pieces.  Unfortunately, that wouldn't be an option for Help 1 or website output.



Nov 7, 2012 at 9:18 AM

I am getting back to this one after my tests of 1.9.5 with VS2012 - overall the performance is much better and one can use VS2012 to actually build documentation.

Almost all of the above notes are no longer present. 

Still it will be nice if we can have a toobar in VS just like the one in SHFB - with buttons for bold, italic, etc (

Another useful think is to show the code when previewing the content of a conceptual topic instead of showing just a reference to it:

[VB.NET] Some Description

Import code from ..\MyFile.cs limited to the region named 'RegionName'