While significantly different, the new project file format still has all of the same features and project options as the old file format. The main difference that you will notice is that additional content and conceptual content files are now exposed and managed via the Project Explorer. This makes it much easier to manage the files and add new ones. The following are the main differences and some issues that you may encounter with the converted project file:

• Review all path related properties to ensure that they are still accurate in the new project.

• 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.

• Review the configurations for all build components added via the ComponentConfigurations property and the configurations for all plug-ins added via the PlugInConfigurations property. It may be necessary to adjust the paths on file-related options.

• Not all files can be detected and added to the project (i.e. files referenced in topics such as example code files, the logo file in the Post-Transform component, 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, you may need to adjust the path to external source files in the source attribute on the <code> elements.

• Conceptual content media files are added as project file 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.

• Conceptual content tokens are stored in a file that is added to the project and its BuildAction is set to Tokens to indicate that it should be treated as such in the build. The extension on the filename is set to .tokens.

• If a conceptual content code snippets files is defined, it is added to the project and its BuildAction is set to CodeSnippets to indicate that it should be treated as such in the build. The extension on the filename is changed to .snippets.

• All additional content files and subfolders are added to the project recursively as file items with default build actions based on the file extensions. If it does not already contain one, you can add a site map to the project and edit it to set the order and layout of the additional content items.

  Tip
  The help file builder contains full support for conceptual content that uses Microsoft Assistance Markup Language (MAML) to create additional non-API topics such as How-Tos, walkthroughs, etc. You may want to consider switching any additional HTML content to conceptual content to take advantage of its features. See the Conceptual Content topic for more information.

• Wildcard additional content items are expanded into individual file entries in the new project. As such, you may find that unwanted files have been added to the project (i.e. source control files) that you were not aware of before as they were copied as part of build and may not have been noticed. The extra files can be deleted from the new project.

• Because the additional content files actually become part of the project and are copied to the project folder, their base path may be different than the destination path specified in the old project. The file's location within the project is used to determine its destination path in the compiled help file. Files at the root end up in the root folder of the compiled help file. Files in subfolders end up in like-named subfolders in the compiled help file. These paths may differ from the old project and you may need to adjust the file locations within the project after conversion to get them where they need to be when the project is built.

• Conceptual content topics are copied to the project and will have their filename extension changed from .xml to .aml to reflect their actual purpose. Note that the BuildAction on topics files is set to None. This is correct as the content layout file determines which topics are included in the help file at build time.

• In addition to the filename extension change, the topic ID and revision number are embedded in each converted MAML topic file. Going forward, all conceptual topic files must contain a root <topic> element with id and revisionNumber attributes. This is done to allow the content layout file to reference topics by ID alone and lets topic files move around without you having to update their physical location in the layout files.

• Any HTML or .topic files found in the conceptual content layout will be modified to include <meta> elements that contain the ID and revision number for the same reason the ID and revision number are added to the conceptual content MAML topic files.

Other Resources