Click or drag to resize
Sandcastle Help File BuilderRelative and Absolute Paths

With a few exceptions, all file and folder path properties in the project options allow you to specify either a relative or an absolute path. All paths default to relative when first entered. This allows you to move the project folder and the paths in the properties will be still be correct when the project is opened again.

You can change this behavior for a particular property by checking the Fixed Path option below the path text box on the related project property page. The path is then displayed as an absolute path and will be saved as such in the project.

In addition, environment variables such as %SHFBROOT%, %WINDIR%, etc. can be specified in the paths and they will be expanded at build time to the value of the specified environment variable. The display area below the related path property's text box will show you the expanded form based on the current system's settings. The MSBuild-format for environment variables is also supported ($(SHFBROOT), $(WINDIR), etc.).

The key point to remember is that help file builder projects built either from the standalone GUI, from within Visual Studio, or from the command line always expect that relative paths are relative to either the folder in which the project file is located or to the working folder used for the build. The expected relative location is noted in the description of each affected property. A typical folder layout is shown below:

Copy
C:\HelpTest\        Solution folder.
  |
  +-TestAssembly    Application project folder.
  | |
  | +-Bin
  |   |
  |   +-Release     Location of assembly and comment files.
  |
  +-Doc             Help file builder project location.
    |
    +-Content       Other optional content folders (i.e. conceptual topics).
    |
    +-Media         Image files used in conceptual content.
    |
    +-Icons         Optional folder used to contain a logo image.
    |
    +-Help          The output folder for the help file.
      |
      +-Working     The intermediate working folder used during the build.
        |
        +-Output    Help file project compilation folder.
          |
          +-HtmlHelp1        Root help file format folder.
            |
            +-html           Content folders for the given help file format.
            +-images
            +-media
            +-scripts
            +-styles

The example above places the help file builder project in the C:\HelpTest\Doc\ folder. As such, the relative path to the assembly that will be documented and its comment file is ..\TestAssembly\Bin\Release\. The default output folder for a project is always .\Help\. If you would prefer the help file to end up in a different location, you can modify it using the Help Content Output Path property.

Caution note Caution

Be aware that if an option is selected that produces a website, the output folder specified by the Help Content Output Path property will be cleared of all of its current content without any prompting before the web site content is copied to it. In other words, don't do something stupid like set it to the root of your C: drive or your desktop folder. The help file builder will check for common special folders to prevent this from happening but always be sure to confirm the folder name that you enter. When producing a Help 1 (.chm), Help 2 (.HxS), and/or MS Help Viewer (.mshc) file without the website output format, the output folder is not cleared.

A similar warning applies to the Working Path property. Its content is always cleared unconditionally prior to a build regardless of the help file format selected.

See Also