Special Folder Locations
The help file builder has the ability to utilize third-party custom build components, plug-ins, syntax generators, and presentation styles. In addition, the project system allows you to add files based on user-defined template files. Build components and plug-ins can also create configuration or cache files to use across builds if needed. In order to work correctly, each type of file must be located in the correct place.
- Root Application Data Folders
- Third-Party Build Components and Syntax Filter Generators
- Third-Party Build Process Plug-Ins
- Third-Party Presentation Styles
- User Configuration Settings and Cache Files
- User-Defined File Templates
Note
None of the folders mentioned below exist by default so you will need to create them yourself. The exception is the root local application data folder. It will be created on first use by the help file builder if referenced by a build component or a plug-in configuration.
Project-specific build components, plug-ins, syntax generators, and presentation styles are also supported. To utilize project-specific components either place the components in the project folder or a subfolder beneath it or point to the component location using the project's Component Path property.
If third-party components are available as NuGet packages, they can be added to the project using the Component Packages node in the project explorer tool window.
Root Application Data Folders
There are two root application data folders (Common Application Data and Local Application Data). These equate to one of the following folders based on your operating system:
Operating System | Folder Location |
|---|---|
Windows Vista or later | Common Application Data: %ProgramData%\EWSoftware\Sandcastle Help File Builder Local Application Data: %LOCALAPPDATA%\EWSoftware\Sandcastle Help File Builder |
Windows XP | Common Application Data: %ALLUSERSPROFILE%\Application Data\EWSoftware\Sandcastle Help File Builder Local Application Data Folder: %USERPROFILE%\Local Settings\Application Data\EWSoftware\Sandcastle Help File Builder |
Tip
The {@AppDataFolder} substitution tag will resolve to the root common application data folder for the help file builder. The {@LocalDataFolder} substitution tag will resolve to the root local application data folder for the help file builder.
Third-Party Build Components and Syntax Filter Generators
Third-party build components that you want to use from within the help file builder via the ComponentConfigurations project property and custom syntax filter generators accessible via the SyntaxFilters project property must be placed in the Common Application Data folder. This equates to one of the following folders based on your operating system:
Operating System | Folder Location |
|---|---|
Windows Vista or later | %ProgramData%\EWSoftware\Sandcastle Help File Builder\Components and Plug-Ins |
Windows XP | %ALLUSERSPROFILE%\Application Data\EWSoftware\Sandcastle Help File Builder\Components and Plug-Ins |
Put the build components and any of their required configuration and supporting files within the noted folder or a subfolder beneath it. These will be shared by all users on the same computer.
Third-Party Build Process Plug-Ins
Third-party build process plug-ins that you want to use from within the help file builder via the PlugInConfigurations project property must be placed in the Common Application Data folder. This equates to one of the following folders based on your operating system:
Operating System | Folder Location |
|---|---|
Windows Vista or later | %ProgramData%\EWSoftware\Sandcastle Help File Builder\Components and Plug-Ins |
Windows XP | %ALLUSERSPROFILE%\Application Data\EWSoftware\Sandcastle Help File Builder\Components and Plug-Ins |
Put the plug-ins and any of their required configuration and supporting files within the noted folder or a subfolder beneath it. These will be shared by all users on the same computer.
Third-Party Presentation Styles
Third-party presentation styles that you want to use from within the help file builder via the PresentationStyle project property must be placed in the Common Application Data folder. This equates to one of the following folders based on your operating system:
Operating System | Folder Location |
|---|---|
Windows Vista or later | %ProgramData%\EWSoftware\Sandcastle Help File Builder\Components and Plug-Ins |
Windows XP | %ALLUSERSPROFILE%\Application Data\EWSoftware\Sandcastle Help File Builder\Components and Plug-Ins |
Put the presentation styles and any of their required configuration and supporting files within the noted folder or a subfolder beneath it. These will be shared by all users on the same computer.
User Configuration Settings and Cache Files
Due to various folder/file permission issues and in order to allow multiple users on the same computer to have their own custom settings and cache files used by build components and plug-ins, these types of files must be stored in the Local Application Data folder (see the Root Application Data Folders section above).
As an example, the cached build components supplied with the help file builder create their cache files in the following location based on the operating system:
Operating System | Folder Location |
|---|---|
Windows Vista or later | %LOCALAPPDATA%\EWSoftware\Sandcastle Help File Builder\Cache |
Windows XP | %USERPROFILE%\Local Settings\Application Data\EWSoftware\Sandcastle Help File Builder\Cache |
Each user is free to delete such files to get back to a default state without affecting other users on the same computer. Likewise, they can give copies of their settings files to other users for them to place in a like named folder in their settings area to make use of them as well.
User-Defined File Templates
Due to various folder/file permission issues and in order to allow multiple users on the same computer to have their own custom file templates, these types of files must be stored in the Local Application Data folder. This equates to one of the following folders based on your operating system:
Operating System | Folder Location |
|---|---|
Windows Vista or later | %LOCALAPPDATA%\EWSoftware\Sandcastle Help File Builder\Item Templates %LOCALAPPDATA%\EWSoftware\Sandcastle Help File Builder\Conceptual Templates |
Windows XP | %USERPROFILE%\Local Settings\Application Data\EWSoftware\Sandcastle Help File Builder\Item Templates %USERPROFILE%\Local Settings\Application Data\EWSoftware\Sandcastle Help File Builder\Conceptual Templates |
Use the Item Templates folder to store custom templates for project files such as images, HTML files, style sheets, script files, tokens, code snippets, or XML files. Use the Conceptual Templates folder to store custom MAML topic template files. These template files appear on the Custom Templates submenus within the project explorer, site map editor, and content layout file editor.
Each user is free to delete such files to get back to a default state without affecting other users on the same computer. Likewise, they can give copies of their template files to other users for them to place in the templates folder in their settings area to make use of them as well.
Note
This only applies to the standalone GUI. To define custom file templates for the Visual Studio package, see the Item File Templates topic.