Paths Category Properties
The Paths category properties define the location of the tools and the output location of the help file.
This property lets you specify the path to the HTML Help 1 compiler (HHC.EXE).
By default, the builder will try to locate it automatically by searching the Program Files
special folder on all fixed hard drives. As such, you only need to specify the path if the build fails with a
message stating that it could not be found.
This property lets you specify the path where the help file builder can find custom build
components, plug-ins, syntax generators, and presentation styles specific to the project. If left blank, the
project's folder is searched instead. This is useful for XCOPY deployments or when developing build components
so that they don't have to be installed in the standard location (the common application data folder).
If specified and your source code is hosted online such as at a GitHub project site, links to it
will be included via a View Source link in the Syntax section of topics in presentation styles that
support it (specifically the baseSourceCodeUrl argument in the Transform Args
property category). Specify the local file system path to the root source code folder here, not a URL.
An up-to-date program database (PDB) file is required for each documented assembly in order to find
source code locations for types and members. Visual Studio will typically generate this automatically unless
you have turned the option off in the assembly's project properties. By default the debug info option is set
to "pdb-only" which is sufficient. The MRefBuilder tool will determine source code
locations for the members by looking for sequence point information in the PDB file. These sequence points
define the starting locations of executable code that you write within the source files. Since the first
sequence point is always the first executable line of code within the member, the link will go there and not
necessarily to the actual member declaration.
In addition, not all types and members have sequence points defined in PDB files and thus the
actual source code location cannot be determined. Such items include:
Empty types that contain no members.
Interfaces as they do not contain any concrete implementations for their members.
Events since their add/remove methods are compiler generated.
Auto-implemented properties as their get/set methods are compiler generated.
Fields and constants.
Enumerations.
In order to enable links to such types and members as listed above, MRefBuilder
will perform a search of the given source code folder to try and locate a source code file with a name that
matches the given type name. If it finds a match, it will use it as the link target. If multiple matches are
found, it tries to disambiguate them by adding containing folder names as namespace parts starting with the
containing folder in order to find a match. As such, if your code is structured in the common way such that
folders represent namespaces and each source code file represents a type, it should be successful in finding a
match. For nested types, the link will be to the containing type's source code page.
Informational messages will be displayed in the Generate Reflection Information
section of the build log indicating which PDB files were found. Warnings will be issues if a PDB file could
not be found or if it was out of date.
If the source location could not be found for any types, an informational message will also be
written to the log file to identify them. To report these issues as warnings instead so that MSBuild picks them
up and reports them, turn this option on. This is helpful if you want to ensure that all API topics in your
help file generate links to the online source code as it will help you identify source code that may need
adjustments in order to be located. Common issues are multiple types stored in a single source file, source
code folder names that don't match the namespaces, source code filenames that don't match the name of the type
within them, and multiple source code files with the same name and folder structure such as copies of the same
code shared between multiple projects.
This property lets you specify where the compiled help file should be placed. The default is to
store it in a folder called .\Help\ relative to the project folder. It is also the location
of the temporary .\Working\ folder used to store the generated build files unless it is
changed with the Working Path property. This property cannot be set to the same value
as the Working Path property as the working path folder is cleared prior to the build.
Be aware that if an option is selected that produces a website or markdown content, the output
folder specified by the 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 try to take
steps to ensure this does not happen. When producing Help 1, MS Help Viewer, and/or Open XML files, the output
folder is not cleared.
This property lets you specify an alternate location with a shorter path in which to perform the
build if it fails due to long file path names. If not specified, the working folder will be placed under the
output path and will be called .\Working. This property cannot be set to the same value as
the Output Path property as the working path folder is cleared prior to the build.
Be aware that the working folder specified by the Working Path property
will be cleared of all of its current content without any prompting before the build begins. 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 try to take steps to ensure this does not happen.
