The following user preferences allow you to customize the behavior of certain options in the help file builder that apply to all projects and the environment in general. Most are common to both the standalone GUI and the Visual Studio extension package. Options that only apply to one or the other are noted in that option's comments.

The User Preferences option can be found in the standalone GUI on the File menu. The dialog box that it opens contains two tabs. The first is for general preferences and the second is for defining custom content editors for project files. In the Visual Studio extension package, only the general options apply and they can be found by opening the Tools | Options dialog and selecting the Sandcastle Help File Builder category. The Visual Studio shell handles opening files with an appropriate editor. Custom editors are defined using the Open With context menu item on project files in the Solution Explorer should any be needed.

General Preferences

The general preferences are as follows:

  • MS Help 2 (.HxS) Viewer Path - This allows you to specify the path to an external application that can be used to view MS Help 2 (.HxS) files. If you need one, see the Installation Instructions for the download location of the H2 Viewer.

  • Alternate MS Help Viewer (.mshc) Viewer Path - This allows you to specify the path to an external application that can be used to view MS Help Viewer (.mshc) files. If you need one, see the Installation Instructions for the download location of the H3 Viewer. If not specified, the default browser will be used to open MS Help Viewer content.

  • ASP.NET Development Web Server Port - This allows you to specify the port number to use when starting the built-in .NET development web server to view website output using the Index.aspx page. By default, it is set to port 12345. You can alter this if it conflicts with something on your system.

  • Save window state per project for each user - (Standalone GUI only) This allows you to save the current window layout and currently open file editors when a project is closed. The window state is saved to the same folder as the project using the project filename with a "_[USERNAME]" suffix where USERNAME is the user ID of the currently logged in user. If turned off, only the location of the Project Explorer and Project Properties window are saved in the general user preferences. The Visual Studio shell handles this automatically for the extension package.

  • Before Building - (Standalone GUI only) This lets you specify whether or not the help file builder should save the project and/or modified document windows prior to performing a build or previewing a topic. The options are:

    • Save all changes - Save the project and any modified document editors.

    • Save changes to open documents only - Only open, modified document editors are saved. Changes to the project file are not saved.

    • Prompt to save all changes - You will be asked to save all changes. If documents are not saved, the resulting help file may not contain current information.

    • Don't save any changes - Nothing is saved. The resulting help file may not contain current information if there are unsaved documents.

    Note

    When opening the topic preview window, the previewed document is always saved regardless of this setting so that it shows current information.

    The Visual Studio shell will save files for the extension package according to the Before building option in the Tools | Options | Projects and Solutions | Build and Run category.

  • Build output verbose logging enabled - This allows you to specify whether or not full logging information is displayed in the output window during a build. In the standalone GUI, it is checked by default. In the Visual Studio extension package, it is unchecked by default. When unchecked, only build step messages are reported during the build. All messages are still written to the log file. This is useful for very large projects where the generated output can consume large quantities of memory.

  • Open build log viewer on failed build - (Visual Studio extension package only) If enabled, the build log viewer tool window will be opened after a failed build to display the full log content so that you can diagnose the problem.

  • Open help file after successful build - If enabled, the help file will be opened after a successful build. The format opened will depend on the format chosen in the HelpFileFormat project property. Preference is given to Help 1, then Help 2, then MS Help Viewer, and finally website output. In the standalone GUI, this option can also be toggled on and off via the Documentation | View Help File menu.

  • Use external browser to view help websites - (Visual Studio extension package only) If checked, the default external web browser will be used to open help website output. If left unchecked, help website output will be opened in a tabbed document window within Visual Studio.

  • Build Output Background/Foreground/Font - (Standalone GUI only) These options let you specify the background color, foreground color, and font used in the output window for the build output (the text shown during the build).

  • Text Editor Font - (Standalone GUI only) This option lets you set the font used in the text editor windows. The syntax highlighter controls the colors and they are not editable.

  • Show line numbers in text editor - (Standalone GUI only) If enabled, all text editor windows will show line numbers down the left side. If not enabled, no line numbers are shown within the text editor windows.

  • Enter matching brackets, parentheses, and quotes - (Standalone GUI only) If enabled, all editor windows will automatically insert the matching closing character when an opening bracket, parentheses, or double quote is entered. If not enabled, the matching character is not entered automatically.

Content File Editors

(Standalone GUI only) This tab allows you to define custom editors for project files that are not recognized by the standalone GUI as being editable text files based on their filename extension. In such cases, the standalone GUI will look for a custom editor definition and, if found, will launch the associated application. If no custom editor definition is found, the GUI attempts to launch the file using the shell to let it decide how the file should be edited.

To add a new content file editor, click the Add button located next to the upper right corner of the editor list. Select the new entry in the list and use the property grid at the bottom of the tab to alter its settings.

  • Description - Enter a description for the editor.

  • Extensions - Enter a list of filename extensions with which this editor will be associated. If specifying multiple extensions, separate them with a space, semi-colon, period, or a comma.

  • ApplicationPath - Enter the path to the editor application. As with other project properties, this can be an absolute or a relative path and can contain environment variable references for expansion when actually invoked.

  • Arguments - Specify any necessary command line arguments. At the minimum, the $ContentItem macro should be specified so that the file to edit is passed to the application. Enclose arguments in quote marks if the value will contain spaces. Macros that you can use are as follows:

    • $ContentItem - This expands to the full path and filename of the item to be edited.

    • $ProjectFile - This expands to the full path and filename of the current project.

    • $ProjectFolder - This expands to the full path of the current project without the filename.

    Macro names are case-insensitive.

  • StartupFolder - An optional folder name in which the application is started. If left blank, the current project's folder is used. As with the application path, this can be an absolute or relative path and can contain environment variable references for expansion when actually invoked.

To delete an editor definition, select it in the list and click the Delete button located next to the bottom right corner of the editor list.

See Also