Installing SandCastle - Where to start?

Nov 10, 2010 at 7:37 PM

Hi,

  I currently have VS2010 and VS2008 installed.  I would like to install SandCastle to generate help/documentation files.  Where do I start?

  For what I could read so far, I should need to download and install the following:

    - Sandcastle-June 2010 Release Version 2.6.1062.1 (Sandcastle.msi)  http://sandcastle.codeplex.com/releases/view/47665#DownloadId=128770

    - Latest Source Code (Sandcastle-54478.zip) http://sandcastle.codeplex.com/SourceControl/changeset/view/54478#

   - Sandcastle June 2010 (2.6.10621.1) Patch - Rev 1 (SCPatch_Jun2010_2_6_10621_1_Rev1.zip) http://sandcastlestyles.codeplex.com/

   - Change Set 61048 (SandcastleStyles-61048.zip) http://sandcastlestyles.codeplex.com/SourceControl/changeset/changes/61048

   - DocProject for SandCastle 1.11.0 Release Candidate (DocProject-1110RC.exe) http://docproject.codeplex.com/releases/10744/download/36424

My questions:

   1.  From the items listed here, is there any I should not install? If so which one(s) and why?

   2.  Is there any other parts I should download and install?  If so which one(s)?  Any weblink from where to download?

   3. Will this setup works fine along with Visual Studio 2008 and Visual Studio 2010?

Thanks in advance for your help.

Editor
Nov 11, 2010 at 4:29 PM

Unless you want to rebuild the projects, you can pretty much ignore all of the source code downloads.  If you want to use DocProject, you'll need the prior release of Sandcastle (May 2008) since it hasn't been updated to support the latest release of Sandcastle and the Sandcastle Styles patch yet.  You can find more information and ask question about it at its project site (http://DocProject.CodePlex.com).  The Sandcastle Help File Builder is also available.  It's a standalone GUI that provides a front-end for Sandcastle and works with the latest release.  If you want to use it, see the topics in the Getting Started section of its help file as they will guide you through what to install and creating your first project.  For a more indepth walkthrough see this article on Simple Talk.

Eric

 

Nov 11, 2010 at 6:37 PM

Hi Eric,

  Thanks for reply.  I appreciate.

  For what I understand, I should first install the following:

    - Sandcastle-June 2010 Release Version 2.6.1062.1 (Sandcastle.msi)  http://sandcastle.codeplex.com/releases/view/47665#DownloadId=128770
    - Sandcastle June 2010 (2.6.10621.1) Patch - Rev 1 (SCPatch_Jun2010_2_6_10621_1_Rev1.zip) http://sandcastlestyles.codeplex.com/
    - Change Set 61048 (SandcastleStyles-61048.zip) http://sandcastlestyles.codeplex.com/SourceControl/changeset/changes/61048

  Next, concerning wrapper application, I read your article and should finally go with:

   - SandCastle Help File Builder (which should replace DocProject I chose in first place)

  I also read something about GhostDoc and would appreciate your opinion:
       Is it doing anything similar to previous items I will install or does it bring more "meat" to the table?  If so what?
       Would you recommend installing it?

  Finally, any other items you would recommend to install before closing the loop?

Thanks again for helping,

Stéphane

Editor
Nov 12, 2010 at 4:40 PM

You don't need the change set 61048 since it's the same as the Rev 1 Sandcastle Styles patch.  If you will be building Help 1 (CHM) files, you'll need to install the HTML Help Workshop.  If you will be building Help 2 (HxS) files, you'll need to install one of the Visual Studio SDKs to get the Help 2 compiler stuff.  See the SHFB installation instructions for download locations.  One update though, for the VS2008 SDK, you need to download the v1.0 version from http://www.microsoft.com/downloads/details.aspx?familyid=30402623-93ca-479a-867c-04dc45164f5b&displaylang=en since the v1.1 SDK doesn't contain the Help 2 compiler anymore.  If you install the SDK, it contains an outdated version of Sandcastle and you'll need to fix the DXROOT environment variable.  The SHFB installation instructions contain info on how to fix it.

Regarding GhostDoc, I've never used it but some people like it.  As I recall, it's mainly for use while coding to automatically insert boilerplate XML comments for class members.  The H2Viewer and H3Viewer are handy for viewer Help 2 and MS Help Viewer output if you are producing them.

Eric

 

Nov 12, 2010 at 5:26 PM

Hi Eric,

  Thanks again for reply. 

  1. "You don't need the change set 61048"

OK will remove this item from install list!

  2. Visual Studio SDKs... 

I actually have VS2008 SDK v1.1 as well as VS2010 SDK installed.  You recommend to download VS2008 SDK v1.0.  Is there a way to get the Help2 compiler without installing the whole SDK?  If not, can SDK v1.0 be installed "aside" SDK v1.1?

  3.  Outdated version of SandCastle...

While installing both VS2008 and VS2010 SDKs, I honestly do not remember anything about SandCastle or if so, I probably didn't select anything accordingly at that moment.  Is there a way I can check the presence or not of SandCastle (or maybe setup files for eventual installs)?

  4. H2Viewer/H3Viewer

I actually have H3Viewer installed.  Very handy indeed as it helps me see help files the good old way!

  5. Eventual updates

How does SandCastle manage updates?  Will I eventually have to uninstall and then reinstall in case of new version of SandCastle?

 

Thanks again for helping,

Stéphane

Editor
Nov 12, 2010 at 8:00 PM

I don't know whether the Help 2 compiler is available separately.  That's a better question for the MSDN Dev Doc forum.  I'm not sure about installing the earlier SDK side-by-side either.  You can check the DXROOT environment variable to see if it's pointing to the correct location for Sandcastle.  There should only be a system enviroment variable for DXROOT and it should point to C:\Program Files\Sandcastle or C:\Program Files (x86)\Sandcastle depending on whether you are using a 32-bit or 64-bit version Windows.  When a new release of Sandcastle is issued, you uninstall the current version, install the new one and, if using a community tool such as SHFB, download and install the new version of it too.  The Sandcastle Styles patch is usually updated and published shortly after the new Sandcastle release.  Not much appears to be happening right now and the last update took 2 years so it may be a while before we see anything new.

Eric

 

Nov 13, 2010 at 7:17 PM
Edited Nov 13, 2010 at 7:19 PM

Hi Eric,

  Thanks again for follow-up. 

  I've done a search for the DXROOT environment variable and it doesn't exist actually.  Which makes sense considering the fact that SandCastle is not installed on my machine yet.

  Now regarding the version of Help (help 1/help 2/...), as I'm quite new to this, I'm questionning what is the standard actually used?  Does it depend on the O/S platform the help file is installed?  The .NET Framework targetted?  I don't have a clue.  Can you explain? 

  1. Help 2 Compiler

I've done a little research on my own regarding Help2 Compiler.  Search the NET for some hints.  Considering the fact that I have VS2008 SDK installed on my machine, even if it is version 1.1, I took the chance to search my computer for it.  I finally found it under "C:\Program Files\Common Files\microsoft shared\Help 2.0 Compiler".   In that directory, the following items are listed:

  • 1033 (directory)
  • Redist (directory)
  • hxcomp.exe (version 2.7.61224.0)
  • hxcsrv.exe (version 2.7.61224.0)
  • hxreg.exe (version 2.7.61224.0)
  • ITCC55.dll, Resources.HxS.  

Now is there any other things I should validate so I can conclude it is well configured, registered (or else...) and I can finally use it properly?

Any good articles you would recommend on how to work with it?

2. My install list should now look like:

  1. Sandcastle-June 2010 Release Version 2.6.1062.1 (Sandcastle.msi)  http://sandcastle.codeplex.com/releases/view/47665#DownloadId=128770
  2. Sandcastle June 2010 (2.6.10621.1) Patch - Rev 1 (SCPatch_Jun2010_2_6_10621_1_Rev1.zip) http://sandcastlestyles.codeplex.com/
  3. SandCastle Help File Builder  (any specific link / version you would recommend?)
  4. GhostDoc  (or... any other tool you would recommend instead?)

     Any other items, you would add to this list?  BTW, I expect to use VS2008 as well as VS2010 in my development.    Mainly C# and C++.

Thanks again for helping,

Stéphane

Editor
Nov 13, 2010 at 8:30 PM

What help format you choose depends on how you want to let users view the resulting help.  Help 1 produces standalone .CHM files.  Although it's a rather old format and has some limitations with regard to Unicode support for foreign languages, it's fairly convenient as they are completely standalone and you can open them on any PC without any special software.  Help 2 produces .HxS files which need to be integrated into a Visual Studio help collection (VS2005 and VS2008).  You can't view these standalone unless you use the H2Viewer.  Typically, they are integrated into the Visual Studio help collection (a topic all of its own and covered in the SHFB help file if you are interested).  Once integrated, you can view it using the Document Explorer tool that comes with VS2005 and VS2008.  MS Help Viewer is the latest help format and is used in VS2010.  There is no standalone viewer for it so it must be registered with the help library manager before you can view it with the H3Viewer or the web browser/help agent.  Website output is convenient if you want to upload a copy of the help to a web server for online viewing.  The other factors such as OS and .NET Framework version don't play much of a role unless you want access from with Visual Studio.  In that case for .NET 3.5 or earlier you'd use the Help 2 format and for VS2010 and .NET 4.0 you'd use the MS Help Viewer format.

Regarding whether or not the copy of the Help 2 compiler you found will work, I can only assume that it will.  If you do a build, SHFB finds it, and it runs without failing (i.e. it's registered correctly), you'll know it's good.  Since it's under the shared folder, you're probably okay and perhaps it was installed by a prior release of the SDK.  As I recall, that's the location that the v1.0 SDK puts it so perhaps you installed or had that installed at some point.

The latest version of SHFB which is compatible with the latest version of Sandcastle is always available from http://SHFB.CodePlex.com.  Also, just so you know, Sandcastle can only document managed code.  As such, if you are looking to document a native C++ library (i.e. MFC or ATL), you'll need to use another tool such as Doxygen.

Eric

 

Nov 15, 2010 at 12:01 AM
Edited Nov 15, 2010 at 12:25 AM

Hi again Eric,

Thanks for comments and link provided.

I would like to get back to the different Help formats. From SHFB webpage, I could read the following infos:

"The builder can produce an HTML Help 1 (.chm) file, an MS Help 2 (.HxS) file, MS Help Viewer (.mshc), and/or a website."

My questions:

  1. To build "Help 1 (.chm)" file, you stated in an earlier post that I needed HTML Help Workshop. The download is in form of a file "Htmlhelp.exe". Is this an install program or a single exe file? Any recommandation while installing it?
  2. To build "Help 2 (.HxS)" file, we talked about MS Help2 Compiler which seems to be actually installed on my machine. Anything else I need?
  3. To build "MS Help Viewer" file, it is mentionned in SHFB documentation, that I need the Help Library Manager and Help Library Agent. VS2010 is actually installed on my machine. I could find the Help Library manager menu link easily and have also seen many times the Help Library Agent being activated while accessing VS2010 help system. So nothing to do regarding those two items. Any other recommandations?
  • Regarding SHFB, what kind of interface should I expect? Command-Line or GUI? On webpage, there are contradictory statements about it:

"The current version is the May 2008 release. It is command line based and has no GUI front-end"

"The GUI interface provides an NDoc-like properties window so anyone familiar with NDoc should be quite comfortable using it."

  • Finally, regarding GhostDoc, I could read that the only languages supported were C# and VB. As I'm also targetting C++/CLI, what options do I have? If none, any equivalent tools I can use instead of GhostDoc that could support both C# and C++/CLI?

For the note about managed code, it shouldn't be an issue for me as I actually target C++/CLI and C# which are both managed code. In fact, this form of language is what resemble the most to the programming languages I've been using so far.

So my final install list should look like:

  • 1. Sandcastle-June 2010 Release Version 2.6.1062.1 (Sandcastle.msi)  http://sandcastle.codeplex.com/releases/view/47665#DownloadId=128770

    2. Sandcastle June 2010 (2.6.10621.1) Patch - Rev 1 (SCPatch_Jun2010_2_6_10621_1_Rev1.zip) http://sandcastlestyles.codeplex.com/

    3. SandCastle Help File Builder (1.9.1.0)  (http://shfb.codeplex.com/)

    4. HTML Help WorkShop (ver 1.3) (http://msdn.microsoft.com/en-us/library/ms669985.aspx)
            - Htmlhelp.exe  (is this a somekind of an install/setup program?)
            - HelpDocx.zip (HTML help documentation)

    5. GhostDoc ver 2.5.09166 (http://submain.com/products/ghostdoc.aspx)  (only support c# and VB...)
            - Any other similar product that can support both C++/CLI and C#?
            - If not, what equivalent can be used with C++/CLI?

    Thanks again for helping,

    Stéphane

  • Editor
    Nov 15, 2010 at 7:09 PM

    The HTML Help Workshop is in the form of an installer, run it to install it.  There isn't much else to say about it, nor the Help 2 compiler.  If you can access VS2010 help, there's nothing else to do with regard to MS Help Viewer either.  The reference to "no GUI front end" is for Sandcastle itself which is just a set of command line tools.  SHFB itself provides the GUI and a project management system and will control the build process that invokes the Sandcastle tools.  I don't use GhostDoc and I don't code in C++ anymore so I can't comment on alternatives for it.

    Eric

     

    Nov 16, 2010 at 6:11 PM

    Hi again,

      Thanks for reply.  I'm installing SandCastle today.  I would like to leave you the following link about a program, which seems equivalent to GhostDOC, but that could work not only with C# but with C++/CLI as well.

    AtomineerUtils add-in for VS2008-VS2010-VS2005:   http://www.atomineerutils.com/products.php

      Seems to be a more versatile tool than GhostDOC.  I would certainly like to have your opinion about this tool.  Does it worth the try?

    Thanks again for your help,

    Stéphane

    Nov 17, 2010 at 9:00 PM

    Hi again,

      Probably unlike many others... ;-), I read documentation before proceeding with install.

      For "Sandcastle June 2010 (2.6.10621.1) Patch - Rev 1", I could read (from file FixList.txt) the following :

                        "This is not an official patch from Microsoft so use at your own risk."

      Considering that this patch has been issued on June 30th 2010 and that nothing official has been offered since, can I consider it as safe or should rather wait for something more official?

      Also, if I do not abuse, I would still like to have your opinion on "AtomineerUtils add-in for VS2008-VS2010-VS2005", mentionned in my earlier post.

    Thanks again for your help,

    Stéphane

     

     

    Nov 18, 2010 at 8:22 PM

    Hi again,

      I've read some stuff regarding SandCastle so to learn more about it.  In an article, I picked up the following infos:

    "Three languages get special treatment in Sandcastle: C#, Visual Basic, and C++...   Each of these appears in the language selector at the top of each page of your documentation set...  You can filter the page to include any subset of these three languages using this dropdown button...  Unfortunately (unlike MSDN) this language selection does not carry over from page to page!  That  is  apparently  a  lot  more  challenging  to  fix  than  it  might  appear... I believe it is also connected to this defect that includes, among other Firefox issues,  failure  of  the  Code  all  button  to  render  properly  in  Firefox  with  the  latest Sandcastle/SHFB release from June 2010. Because of this I am sticking with the prior release for the time being."

      Has there been any fix in Sandcastle/SHFB for this or maybe any workaround?

    Thanks for helping and hope to hear from someone...

    Stéphane

    Nov 18, 2010 at 10:03 PM

    >>StéphaneHas there been any fix in Sandcastle/SHFB for this or maybe any workaround?

    This is not an issue in Help 2.x. For the Help 1.x, there is a fix provided here for this problem...

    http://sandcastlestyles.codeplex.com/workitem/5362

    Note that only the VS2005 style is supported, since the other styles are not complete. Web helps
    are tools like DocProject, SHFB implementations and these would have to take care of this issue. 

    Best regards,
    Paul. 

    Nov 18, 2010 at 10:18 PM

    >>Stéphane: "This is not an official patch from Microsoft so use at your own risk."

    If you think using style sheets involve risk, then that statement is for you. 

    >>Stéphane: I would still like to have your opinion on "AtomineerUtils add-in for VS2008-VS2010-VS2005"

    This tool and GhostDoc have nothing to do with Sandcastle, so keep it minimum.

    Best regards,
    Paul. 

    Editor
    Nov 19, 2010 at 1:19 AM

    Consider the warning about it not being an official patch the standard disclaimer boilerplate.  Some companies have policies where they won't allow the use of tools or patches not officially produced or sanctioned by the original source (i.e. Microsoft) so it covers that too and make it clear that they didn't produce it if that's an issue.  Since it's only generating help files, there's nothing potentially harmful in its use.  Most of the bugs are well over 2 years old so I'll let you draw your own conclusions about waiting for a fix.  Regarding the AtomiteerUtils tool, I haven't had enough interest personally to try them so I can't really offer an opinion on their worth.  You'll have to try it out to see if it makes documenting the code any easier for you.  Some people do, some people don't.

    Eric

     

    Nov 25, 2010 at 1:35 PM

    Hi Eric,

      Thanks for the infos.  One last thing.  Once SandCastle is installed:

    1. Sandcastle-June 2010 Release Version 2.6.1062.1 (Sandcastle.msi)  http://sandcastle.codeplex.com/releases/view/47665#DownloadId=128770

    2. Sandcastle June 2010 (2.6.10621.1) Patch - Rev 1 (SCPatch_Jun2010_2_6_10621_1_Rev1.zip) http://sandcastlestyles.codeplex.com/

    3. SandCastle Help File Builder (1.9.1.0)  (http://shfb.codeplex.com/)

    4. HTML Help WorkShop (ver 1.3) (http://msdn.microsoft.com/en-us/library/ms669985.aspx)
            - Htmlhelp.exe  (is this a somekind of an install/setup program?)
            - HelpDocx.zip (HTML help documentation)

      Is there anything I should expect being loaded at computer startup?  If so, what?

    Thanks again for helping,

    Stéphane

    Editor
    Nov 27, 2010 at 6:21 PM

    There are no device drivers or services so nothing is loaded for Sandcastle or SHFB at startup.  The same applies to the help compilers as far as I know.

    Eric

     

    Nov 30, 2010 at 8:52 PM
    Edited Dec 1, 2010 at 6:30 PM

    Hi Eric,

     

    SandCastle is now installed. I encountered a few problems with the HTML Help workshop but I could complete install anyway. A few check points I would like to make with you:

     

    1- Is it normal that, after installing SandCastle itself (sandcastle.msi), there was no menu item available in Vista?

    2- Regarding now SHFB, I would like to make a suggestion. In VS2010, whenever I select/open windows, they remain opened the next time I start VS2010. Would certainly be a nice improvement in SHFB if I could set the “ProcessExplorer”, ”Project properties”, “Entity References” and “Build output” windows to show permanently.

    3- For my global install, starting from the fact that I’m a total beginner in documentation, Is there a quick way you could suggest so I can test my Sandcastle environment?

     

    Thanks again for your help,

     

    Stéphane

    Dec 1, 2010 at 4:55 AM
    Edited Dec 1, 2010 at 6:32 PM

    Hi again Eric,

     

    An other point I would like to understand about the need for HTML Help Workshop.

     

    From SHFB webpage (http://www.ewoodruff.us/shfbdocs/Index.aspx?topic=html/8c0c97d0-c968-4c15-9fe9-e8f3a443c50a.htm), we can read the following statement within “Benefits and Features” section:

    The builder can produce an HTML Help 1 (.chm) file, an MS Help 2 (.HxS) file, MS Help Viewer (.mshc), and/or a website. “

     Why do I need to install HTML Help Workshop if SHFB can product HTML Help 1 (.chm) file as well?

     

    Thanks again for your help,

     

    Stéphane

    Editor
    Dec 1, 2010 at 7:39 PM

    Sandcastle is a set of command line tools and it installs no shortcuts in the Program Files/All Programs menu on any OS.  It probably should install a shortcut to a Read Me file or something to be a bit more user friendly and to say where the stuff is located.

    I think it's possible to remember the open window state in SHFB, I'll look into it.  It just remembers their last docked positions right now.

    Regarding testing the Sandcastle environment.  I'm not sure what to suggest other than trying a build.  If it fails, the error should tell you what went wrong and what might be missing.

    SHFB is just a front-end for the various tools.  It uses them during the build process to produce the help file in the given format.  It doesn't replace them.

    Eric

     

    Dec 3, 2010 at 2:30 AM

    Hi Eric,

      Thanks for follow-up.  I appreciate. 

      I would like to get back to HTML Help Workshop.  Must I understand that SHFB is in fact using it in the background when producing HTML Help 1 (.chm) file?  If so, I presume that I can't set SHFB to use any other software instead? 

    Thanks again for helping,

    Stéphane

    Editor
    Dec 3, 2010 at 7:08 PM

    Yes, SHFB is running the tools in the background to perform their related tasks.  SHFB is extensible via plug-ins so, should you want to alter or replace parts of the build such as how the help is compiled, you can do so by writing a plug-in.  There's a section in the SHFB help file that covers the available plug-ins and how to write your own if you are interested.

    Eric

     

    Dec 3, 2010 at 7:57 PM
    Edited Dec 3, 2010 at 7:57 PM

    Hi again,

      Thanks Eric for follow-up.  I appreciate.  When you mentionned that I could alter or replace parts,  I would like to have your opinion on these two other questions if you don't mind.  Considering the setup I actually have, as a recall:

    • SandCastle
    • SHFB
    • HTML Help WorkShop (ver 1.3)
    1. Would you recommend using something else than HTML Help WorkShop?   
    2. Any other plugins you think I should have a look?

    Thanks again for helping,

    Stéphane 

     

    Editor
    Dec 4, 2010 at 2:12 AM

    As far as I know, there isn't any other tool that will compile Help 1 files so Help Workshop is it.  As for the other plug-ins, you'll have to evaluate them, see if you have need of them, and make your own decision.

    Eric

     

    Dec 5, 2010 at 2:20 PM

    Hi Eric,

      Thanks for bearing with me along this thread.  As my last request, is there any newsletter I can suscribe so I can get last updates about SandCastle?

    Thanks again,

    Stéphane