Modifying the Documentation
This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies.
You can modify the existing documentation, or add new documentation, as you extend the Smart Client Software Factory. For example, if you change a guidance package recipe, you can update the existing How-to topics and recipe topics to reflect your modifications. Or, if you add new recipes, you can add new topics to describe your additions.
The Smart Client Software Factory provides documentation as compiled Help files. It delivers both Help formats, Help 1.0 (CHM) and Help 2.0 (HxS). Both formats are generated from the same HTML files. This means that you can use either format to view the same content. You follow the same process to modify the documentation in either format.
To modify the Smart Client Software Factory documentation
- Decompile the existing content to create the original source files.
- Modify existing content (or add new content).
- Recompile the Help project.
You use different tools for each format as you follow the preceding process. The Help 2.0 format requires additional steps to create a Windows Installer. The following sections describe the tools and procedures that you can use to extend the software factory documentation.
The Help 1.0 format includes a viewer with the content in a single .chm file. This means you can redistribute a single file that architects and developers can open and view; users do not have to install the Help content or a separate viewer.
To modify the Help 1.0 documentation, you must have HTML Help Workshop installed.
To decompile the software factory .chm file
- Launch HTML Help Workshop.
- On the File menu, click Decompile. The Decompile .CHM File dialog box appears.
- Enter the name of an empty folder in the Destination folder text box. HTML Help Workshop creates the source files in this directory.
- Use SCSF.chm as the name of the compiled Help file.
- Click OK. HTML Help Workshop decompiles the .chm file.
You can edit the existing HTML files to modify the existing content. You can also create new HTML files for new content. The software factory documentation uses specific HTML for the header and footer of each topic. To create a new topic, it is recommended that you copy an existing HTML file, and then edit the copy. After you prepare your content, you must create a new Help 1.0 project and compile your .chm file.
To create and build a new Help 1.0 project
- Launch HTML Help Workshop.
- On the File menu, click New. The New dialog box appears.
- In the list of items, click Project, and then click OK. The New Project Wizard appears.
- Make sure the Convert WinHelp project check box s not selected, and then click Next.
- Enter the name and location of your new project file, and then click Next.
- Select all three options for existing content (HTML Help table of contents, HTML Help index, and HTML files), and then click Next.
- Enter the name and location of the file SCSF.hhc, and then click Next.
- Enter the name and location of the file SCSF.hhk, and then click Next.
- Click Add. In the Open dialog box, browse to the folder named Html that is a subdirectory of the destination folder for the decompiled .chm file. Select all the files, and then click OK.
- Click Next, and then click Finish. HTML Help Workshop creates the project file.
- On the File menu, click Compile.
- In the Create a compiled file dialog box, enter the location and name of the file that you specified in step 5. Click Compile.
Help 2.0 (HxS)
You can use Help 2.0 to author, build, and deploy Help content that integrates with the Visual Studio Help collection. To do this, you create Help topics that are stored in a Help collection. You must install your Help collection before you can view its contents. You view Help collections with Document Explorer.
To modify the Help 2.0 documentation, the following must be installed:
For links to the SDK and Help Integration Wizard, see the Visual Studio Extensibility Center site.
The following steps describe the process to modify the Help 2.0 content:
- Decompile the integrated Help modules to create the source HTML and Help 2.0 project.
- (Optional) Import the Help 2.0 project into Help Studio Lite.
- Modify the existing HTML topics and/or add new HTML topics.
- Compile the Help 2.0 project to create an integrated Help module.
- Create a merge module that contains the integrated Help module.
- Consume the merge module in your setup project.
To decompile Help file
- Create an empty folder. You will specify this folder as the output folder for the decompiled Help 2.0 project.
- Use the HxComp command line program to decompile the Help 2.0 project. The Visual Studio SDK includes HxComp.exe. Enter the following command from a command prompt (specify the folder you created in step 1 as the output folder):
hxcomp -u <SCSF install folder>\docs\SCSF.HxS –d <output folder>
After you decompile the Help 2.0 file, you can edit the HTML topics. You can use the HxComp command line program to compile the project and create a new HxS file. You can also use HelpStudio Lite to edit and manage the content. HelpStudio Lite is offered with the Visual Studio SDK as an installed component that integrates with Visual Studio. HelpStudio Lite provides a set of authoring tools you use to author and build Help content, create and manage Help projects, and compile Help files that can be integrated with the Visual Studio Help collection. You can import an existing Microsoft Help 2.x project into HelpStudio Lite.
To import the Help 2.0 project
- Launch HelpStudio Lite.
- Create a new project in HelpStudio Lite. Select 2005 Style as the new project type.
- On the File menu, point to Import, and then click Help 2.0 Project. The Open dialog box appears.
- Select the Help 2.0 project file SCSF.HxC (this file is located in the output folder you used to decompile the SCSF.HxS file).
- Accept the defaults in the Help 2.0 Import dialog box, and then click OK. HelpStudio Lite imports the content into the project.
- Remove the header HTML from the topics. The content files contain HTML for the header and footer that are not necessary when you use HelpStudio Lite. Edit each HTML topic and remove all content before the following tag.
- Remove the footer HTML from the topics. To do this, edit each HTML topic and remove the div element that has the ID property "footer."
After you import the Help 2.0 project, you can use HelpStudio Lite to modify the content and create an .hxs file. For information about how to use HelpStudio Lite, see the HelpStudio Lite system. You can find this documentation on the Help menu of the HelpStudio Lite development environment.
You must install Help 2.0 content before you can view it. This means you must create a merge module that contains your Help 2.0 content and then consume that merge module in your installation. You can use the Help Integration Wizard to create a merge module for your content. For documentation, use the Help Authoring and Integration Guide section of the Visual Studio SDK documentation. This supplemental documentation explains how to interact with new features of Visual Studio Help, such as how to use either Help Integration Wizard or Help merge modules and Microsoft Windows Installer to deploy, register, and integrate your Help content.