There are several significant differences between DocProject and help file builder project files. However, the conversion process should give you a jump start and get you on your way to producing a help file with the new project. The following are some issues that you may encounter:

• The first thing that you will notice is that there are significantly fewer files and folders in the converted project. This is because the help file builder uses the default set of presentation style files installed with Sandcastle rather than importing them into each project. If you made no changes to those files, you will not see any differences. If you did customize the presentation style files, it is possible that you may see differences in the layout and style of help files built with the converted project. Note that the help file builder contains many project properties that map to the equivalent resource file items that you might have changed in the DocProject version (i.e. the help file title, e-mail address, copyright information, etc.). Such items are not imported so review the project properties and set the equivalent items accordingly.

  If you do need to create a customized version of a presentation style, see the Creating a Presentation Style Component topic. It provides details on cloning an existing style for your own use.

• All other project files will be converted to matching file items with an appropriate build action. However, since the converter cannot determine whether or not some files are actually used, the project may contain some leftovers that can be removed during the review.

• While it does provide a website output format, the help file builder does not currently have an equivalent that matches all of the functionality from the DocProject DocSite project option.

• The API filtering methods differs significantly and those settings are not converted. Instead, review the options in the help file builder's Visibility Category Properties. These can be used to exclude groups of items and the API Filter Property can be used for finer control over which items are excluded.

• Review the Documentation Sources and References project nodes to see that the required items were imported correctly and make any necessary adjustments.

  Tip
  Given that solutions and projects are supported as documentation sources, you may find it easier to add them as documentation sources instead of the assemblies, comments, and references that they contain. When a solution or project is used, these items are imported from them automatically at build time.

• Conceptual content topics are imported as-is. However the properties from the related companion files are imported and stored in a content layout file. This file can be edited to arrange the topics in the table of contents and specify their properties such as the title, help index keywords, and additional topic-specific help attributes. The file has a .content extension and the BuildAction is set to ContentLayout to indicate that it should be treated as such in the build.

• If a media content file is found, its content is imported and the images are added as project items. Their BuildAction is set to Image and the additional properties such as the ID and alternate text are stored in the file item properties.

• Token files are added to the project and their BuildAction is set to Tokens to indicate that they should be treated as such in the build. The extension on the filename is changed to .tokens.

• Code snippets files are added to the project and their BuildAction is set to CodeSnippets to indicate that they should be treated as such in the build. The extension on the filename is changed to .snippets.

• If you were using the standalone custom build components that are distributed at the Sandcastle Help File Builder CodePlex project site, you will need to add them to the project. Open the Project Properties window and select the Components category. The build components can be added and configured from there.

  Note
  The help file builder includes the Code Block Component in every project by default via the template configuration files used during the build. You will only need to add it to your projects if you want to override the default configurations.

• Not all files can be detected and added to the project (i.e. files referenced in topics such as example code files, etc.). If build errors result from missing files, simply add them to the project or adjust the paths and/or filenames as needed.

• If you were using the Code Block Component in DocProject, you may need to adjust the path to external source files in the source attribute on the <code> elements.

Other Resources