/// <summary>
/// This method is used to initialize the plug-in at the start of the build process
/// </summary>
/// <param name="buildProcess">A reference to the current build process</param>
/// <param name="configuration">The configuration data that the plug-in should use to initialize itself</param>
/// <exception cref="BuilderException">This is thrown if the plug-in configuration is not valid</exception>
public void Initialize(BuildProcess buildProcess, XPathNavigator configuration)
{
XPathNavigator root, msHelpViewer;
string value;
builder = buildProcess;
var metadata = (HelpFileBuilderPlugInExportAttribute)this.GetType().GetCustomAttributes(
typeof(HelpFileBuilderPlugInExportAttribute), false).First();
builder.ReportProgress("{0} Version {1}\r\n{2}", metadata.Id, metadata.Version, metadata.Copyright);
root = configuration.SelectSingleNode("configuration");
value = root.GetAttribute("deleteAfterDeploy", String.Empty);
if(!String.IsNullOrEmpty(value))
deleteAfterDeploy = Convert.ToBoolean(value, CultureInfo.InvariantCulture);
if(root.IsEmptyElement)
throw new BuilderException("ODP0001", "The Output Deployment plug-in has not been " +
"configured yet");
deployHelp1 = DeploymentLocation.FromXPathNavigator(root, "help1x");
deployHelp2 = DeploymentLocation.FromXPathNavigator(root, "help2x");
deployHelpViewer = DeploymentLocation.FromXPathNavigator(root, "helpViewer");
deployWebsite = DeploymentLocation.FromXPathNavigator(root, "website");
deployOpenXml = DeploymentLocation.FromXPathNavigator(root, "openXml");
msHelpViewer = root.SelectSingleNode("deploymentLocation[@id='helpViewer']");
if(msHelpViewer == null || !Boolean.TryParse(msHelpViewer.GetAttribute("renameMSHA",
String.Empty).Trim(), out renameMSHA))
renameMSHA = false;
// At least one deployment location must be defined
if(deployHelp1.Location == null && deployHelp2.Location == null &&
deployHelpViewer.Location == null && deployWebsite.Location == null && deployOpenXml.Location == null)
throw new BuilderException("ODP0002", "The output deployment plug-in must have at least " +
"one configured deployment location");
// Issue a warning if the deployment location is null and the associated help file format is active
if(deployHelp1.Location == null &&
(builder.CurrentProject.HelpFileFormat & HelpFileFormats.HtmlHelp1) != 0)
builder.ReportWarning("ODP0003", "HTML Help 1 will be generated but not deployed due to " +
"missing deployment location information");
if(deployHelp2.Location == null &&
(builder.CurrentProject.HelpFileFormat & HelpFileFormats.MSHelp2) != 0)
builder.ReportWarning("ODP0003", "MS Help 2 will be generated but not deployed due to " +
"missing deployment location information");
if(deployHelpViewer.Location == null &&
(builder.CurrentProject.HelpFileFormat & HelpFileFormats.MSHelpViewer) != 0)
builder.ReportWarning("ODP0003", "MS Help Viewer will be generated but not deployed due " +
"to missing deployment location information");
if(deployWebsite.Location == null &&
(builder.CurrentProject.HelpFileFormat & HelpFileFormats.Website) != 0)
builder.ReportWarning("ODP0003", "Website will be generated but not deployed due to " +
"missing deployment location information");
if(deployOpenXml.Location == null &&
(builder.CurrentProject.HelpFileFormat & HelpFileFormats.OpenXml) != 0)
builder.ReportWarning("ODP0003", "Open XML will be generated but not deployed due to " +
"missing deployment location information");
}
/// <summary>
/// This method is used to initialize the plug-in at the start of the build process
/// </summary>
/// <param name="buildProcess">A reference to the current build process</param>
/// <param name="configuration">The configuration data that the plug-in should use to initialize itself</param>
public void Initialize(BuildProcess buildProcess, XPathNavigator configuration)
{
XPathNavigator root, node;
builder = buildProcess;
var metadata = (HelpFileBuilderPlugInExportAttribute)this.GetType().GetCustomAttributes(
typeof(HelpFileBuilderPlugInExportAttribute), false).First();
builder.ReportProgress("{0} Version {1}\r\n{2}", metadata.Id, metadata.Version, metadata.Copyright);
root = configuration.SelectSingleNode("configuration");
if(root.IsEmptyElement)
throw new BuilderException("DFP0001", "The DBCS Fix plug-in has not been configured yet");
node = root.SelectSingleNode("sbAppLocale");
if(node != null)
sbAppLocalePath = node.GetAttribute("path", String.Empty).Trim();
if(String.IsNullOrWhiteSpace(sbAppLocalePath))
{
builder.ReportWarning("DFP0002", "A path to the Steel Bytes App Locale tool was not specified " +
"and it will not be used for this build.");
}
else
{
// If relative, the path is relative to the project folder
sbAppLocalePath = FilePath.RelativeToAbsolutePath(builder.ProjectFolder,
builder.TransformText(sbAppLocalePath));
if(!File.Exists(sbAppLocalePath))
throw new BuilderException("DFP0003", "Unable to locate SBAppLocale tool at " + sbAppLocalePath);
}
// If not building HTML Help 1, there's nothing to do
if((builder.CurrentProject.HelpFileFormat & HelpFileFormats.HtmlHelp1) == 0)
{
executionPoints.Clear();
builder.ReportWarning("DFP0007", "An HTML Help 1 file is not being built. This plug-in will " +
"not be ran.");
}
}
/// <summary>
/// Write the image reference collection to a map file ready for use by <strong>BuildAssembler</strong>
/// </summary>
/// <param name="filename">The file to which the image reference collection is saved</param>
/// <param name="imagePath">The path to which the image files should be copied</param>
/// <param name="builder">The build process</param>
/// <remarks>Images with their <see cref="ImageReference.CopyToMedia" /> property set to true are copied
/// to the media folder immediately.</remarks>
public void SaveImageSharedContent(string filename, string imagePath, BuildProcess builder)
{
XmlWriterSettings settings = new XmlWriterSettings();
XmlWriter writer = null;
string destFile;
builder.EnsureOutputFoldersExist("media");
try
{
settings.Indent = true;
settings.CloseOutput = true;
writer = XmlWriter.Create(filename, settings);
writer.WriteStartDocument();
// There are normally some attributes on this element but they aren't used by Sandcastle so we'll
// ignore them.
writer.WriteStartElement("stockSharedContentDefinitions");
foreach(var ir in imageFiles)
{
writer.WriteStartElement("item");
writer.WriteAttributeString("id", ir.Id);
writer.WriteStartElement("image");
// The art build component assumes everything is in a single, common folder. The build
// process will ensure that happens. As such, we only need the filename here.
writer.WriteAttributeString("file", ir.Filename);
if(!String.IsNullOrEmpty(ir.AlternateText))
{
writer.WriteStartElement("altText");
writer.WriteValue(ir.AlternateText);
writer.WriteEndElement();
}
writer.WriteEndElement(); // </image>
writer.WriteEndElement(); // </item>
destFile = Path.Combine(imagePath, ir.Filename);
if(File.Exists(destFile))
builder.ReportWarning("BE0010", "Image file '{0}' already exists. It will be replaced " +
"by '{1}'.", destFile, ir.FullPath);
builder.ReportProgress(" {0} -> {1}", ir.FullPath, destFile);
// The attributes are set to Normal so that it can be deleted after the build
File.Copy(ir.FullPath, destFile, true);
File.SetAttributes(destFile, FileAttributes.Normal);
// Copy it to the output media folders if CopyToMedia is true
if(ir.CopyToMedia)
foreach(string baseFolder in builder.HelpFormatOutputFolders)
{
destFile = Path.Combine(baseFolder + "media", ir.Filename);
builder.ReportProgress(" {0} -> {1} (Always copied)", ir.FullPath, destFile);
File.Copy(ir.FullPath, destFile, true);
File.SetAttributes(destFile, FileAttributes.Normal);
}
}
writer.WriteEndElement(); // </stockSharedContentDefinitions>
writer.WriteEndDocument();
}
finally
{
if(writer != null)
writer.Close();
}
}
/// <summary>
/// This method is used to initialize the plug-in at the start of the
/// build process.
/// </summary>
/// <param name="buildProcess">A reference to the current build
/// process.</param>
/// <param name="configuration">The configuration data that the plug-in
/// should use to initialize itself.</param>
public void Initialize(BuildProcess buildProcess, XPathNavigator configuration)
{
XPathNavigator root;
string option;
builder = buildProcess;
minParts = 2;
builder.ReportProgress("{0} Version {1}\r\n{2}", this.Name, this.Version, this.Copyright);
// The Hierarchical TOC plug-in is not compatible with MS Help Viewer output
// and there is currently no fix available. The problem is that the table of
// contents is generated off of the help topics when the help viewer file is
// installed and, since there are no physical topics for the namespace nodes
// added to the intermediate TOC file by the plug-in, they do not appear in the
// help file. Updating the plug-in to support help viewer output would have
// required more work than time would allow for this release. If building
// other output formats in which you want to use the plug-in, build them
// separately from the MS Help Viewer output.
if((builder.CurrentProject.HelpFileFormat & HelpFileFormat.MSHelpViewer) != 0)
{
this.ExecutionPoints.Clear();
builder.ReportWarning("HTP0002", "This build produces MS Help Viewer output with which the " +
"Hierarchical TOC Plug-In is not compatible. It will not be used in this build.");
}
else
{
// Load the configuration
root = configuration.SelectSingleNode("configuration/toc");
if(root != null)
{
option = root.GetAttribute("minParts", String.Empty);
if(!String.IsNullOrEmpty(option))
minParts = Convert.ToInt32(option, CultureInfo.InvariantCulture);
if(minParts < 1)
minParts = 1;
option = root.GetAttribute("insertBelow", String.Empty);
if(!String.IsNullOrEmpty(option))
insertBelow = Convert.ToBoolean(option, CultureInfo.InvariantCulture);
}
}
}
/// <summary>
/// This method is used to initialize the plug-in at the start of the build process
/// </summary>
/// <param name="buildProcess">A reference to the current build process</param>
/// <param name="configuration">The configuration data that the plug-in should use to initialize itself</param>
public void Initialize(BuildProcess buildProcess, XPathNavigator configuration)
{
XPathNavigator root, node;
builder = buildProcess;
var metadata = (HelpFileBuilderPlugInExportAttribute)this.GetType().GetCustomAttributes(
typeof(HelpFileBuilderPlugInExportAttribute), false).First();
builder.ReportProgress("{0} Version {1}\r\n{2}", metadata.Id, metadata.Version, metadata.Copyright);
// If the file format is Open XML, this plug-in is not supported and will not run
if((builder.CurrentProject.HelpFileFormat & HelpFileFormats.OpenXml) != 0)
{
builder.ReportWarning("BIP0005", "The bibliography plug-in is not supported in the Open XML " +
"file format and will not run.");
executionPoints = new List<ExecutionPoint>();
return;
}
root = configuration.SelectSingleNode("configuration");
if(root.IsEmptyElement)
throw new BuilderException("BIP0001", "The Bibliography support plug-in has not been " +
"configured yet");
node = root.SelectSingleNode("bibliography");
if(node != null)
bibliographyFile = node.GetAttribute("path", String.Empty).Trim();
if(String.IsNullOrEmpty(bibliographyFile))
throw new BuilderException("BIP0002", "A path to the bibliography file is required");
// If relative, the path is relative to the project folder
bibliographyFile = FilePath.RelativeToAbsolutePath(builder.ProjectFolder,
builder.SubstitutionTags.TransformText(bibliographyFile));
if(!File.Exists(bibliographyFile))
throw new BuilderException("BIP0003", "Unable to locate bibliography file at " + bibliographyFile);
}
/// <summary>
/// This method is used to initialize the plug-in at the start of the build process
/// </summary>
/// <param name="buildProcess">A reference to the current build process</param>
/// <param name="configuration">The configuration data that the plug-in should use to initialize itself</param>
public void Initialize(BuildProcess buildProcess, XPathNavigator configuration)
{
XPathNavigator root;
string option;
builder = buildProcess;
minParts = 2;
var metadata = (HelpFileBuilderPlugInExportAttribute)this.GetType().GetCustomAttributes(
typeof(HelpFileBuilderPlugInExportAttribute), false).First();
builder.ReportProgress("{0} Version {1}\r\n{2}", metadata.Id, metadata.Version, metadata.Copyright);
// This plug-in cannot be used if the namespace grouping option is enabled as that replaces this
// plug-in.
if(builder.CurrentProject.NamespaceGrouping)
{
if(executionPoints == null)
executionPoints = new List<ExecutionPoint>();
else
executionPoints.Clear();
builder.ReportWarning("HTP0001", "The project being built has namespace grouping enabled which " +
"supersedes the Hierarchical TOC Plug-In. The plug-in will not be used in this build.");
return;
}
// The Hierarchical TOC plug-in is not compatible with MS Help Viewer output. The problem is that
// the table of contents is generated off of the help topics when the help viewer file is installed
// and, since there are no physical topics for the namespace nodes added to the intermediate TOC file
// by the plug-in, they do not appear in the help file.
//
// The project namespace grouping options supersede this plug-in and fix the above issue as topics
// are generated for the namespace group entries. As such, this plug-in is deprecated and will not
// receive further changes. It will available for the time being to support the older presentation
// styles that do not support MS Help Viewer output or the namespace grouping project options.
if((builder.CurrentProject.HelpFileFormat & HelpFileFormats.MSHelpViewer) != 0)
{
if(executionPoints == null)
executionPoints = new List<ExecutionPoint>();
else
executionPoints.Clear();
builder.ReportWarning("HTP0002", "This build produces MS Help Viewer output with which the " +
"Hierarchical TOC Plug-In is not compatible. It will not be used in this build.");
return;
}
// Load the configuration
root = configuration.SelectSingleNode("configuration/toc");
if(root != null)
{
option = root.GetAttribute("minParts", String.Empty);
if(!String.IsNullOrEmpty(option))
minParts = Convert.ToInt32(option, CultureInfo.InvariantCulture);
if(minParts < 1)
minParts = 1;
option = root.GetAttribute("insertBelow", String.Empty);
if(!String.IsNullOrEmpty(option))
insertBelow = Convert.ToBoolean(option, CultureInfo.InvariantCulture);
}
}
/// <summary>
/// This method is used to initialize the plug-in at the start of the
/// build process.
/// </summary>
/// <param name="buildProcess">A reference to the current build
/// process.</param>
/// <param name="configuration">The configuration data that the plug-in
/// should use to initialize itself.</param>
public void Initialize(BuildProcess buildProcess, XPathNavigator configuration)
{
XPathNavigator root, node;
builder = buildProcess;
builder.ReportProgress("{0} Version {1}\r\n{2}", this.Name, this.Version, this.Copyright);
root = configuration.SelectSingleNode("configuration");
if(root.IsEmptyElement)
throw new BuilderException("DFP0001", "The DBCS Fix plug-in " +
"has not been configured yet");
node = root.SelectSingleNode("sbAppLocale");
if(node != null)
sbAppLocalePath = node.GetAttribute("path", String.Empty).Trim();
if(String.IsNullOrEmpty(sbAppLocalePath))
throw new BuilderException("DFP0002", "A path to the Steel " +
"Bytes App Locale tool is required");
// If relative, the path is relative to the project folder
sbAppLocalePath = FilePath.RelativeToAbsolutePath(
builder.ProjectFolder, builder.TransformText(sbAppLocalePath));
if(!File.Exists(sbAppLocalePath))
throw new BuilderException("DFP0003", "Unable to locate " +
"SBAppLocale tool at " + sbAppLocalePath);
// If not building HTML Help 1, there's nothing to do
if((builder.CurrentProject.HelpFileFormat & HelpFileFormat.HtmlHelp1) == 0)
{
executionPoints.Clear();
builder.ReportWarning("DFP0007", "An HTML Help 1 file is not " +
"being built. This plug-in will not be ran.");
}
}
/// <summary>
/// This method is used to initialize the plug-in at the start of the
/// build process.
/// </summary>
/// <param name="buildProcess">A reference to the current build
/// process.</param>
/// <param name="configuration">The configuration data that the plug-in
/// should use to initialize itself.</param>
/// <exception cref="BuilderException">This is thrown if the plug-in
/// configuration is not valid.</exception>
public void Initialize(BuildProcess buildProcess,
XPathNavigator configuration)
{
XPathNavigator root;
string value;
builder = buildProcess;
builder.ReportProgress("{0} Version {1}\r\n{2}",
this.Name, this.Version, this.Copyright);
root = configuration.SelectSingleNode("configuration");
value = root.GetAttribute("deleteAfterDeploy", String.Empty);
if(!String.IsNullOrEmpty(value))
deleteAfterDeploy = Convert.ToBoolean(value,
CultureInfo.InvariantCulture);
if(root.IsEmptyElement)
throw new BuilderException("ODP0001", "The Output Deployment " +
"plug-in has not been configured yet");
deployHelp1 = DeploymentLocation.FromXPathNavigator(root, "help1x");
deployHelp2 = DeploymentLocation.FromXPathNavigator(root, "help2x");
deployHelpViewer = DeploymentLocation.FromXPathNavigator(root, "helpViewer");
deployWebsite = DeploymentLocation.FromXPathNavigator(root, "website");
// At least one deployment location must be defined
if(deployHelp1.Location == null && deployHelp2.Location == null &&
deployHelpViewer.Location == null && deployWebsite.Location == null)
throw new BuilderException("ODP0002", "The output deployment " +
"plug-in must have at least one configured deployment " +
"location");
// Issue a warning if the deployment location is null and the
// associated help file format is active.
if(deployHelp1.Location == null &&
(builder.CurrentProject.HelpFileFormat & HelpFileFormat.HtmlHelp1) != 0)
builder.ReportWarning("ODP0003", "HTML Help 1 will be generated " +
"but not deployed due to missing deployment location " +
"information");
if(deployHelp2.Location == null &&
(builder.CurrentProject.HelpFileFormat & HelpFileFormat.MSHelp2) != 0)
builder.ReportWarning("ODP0003", "MS Help 2 will be generated " +
"but not deployed due to missing deployment location " +
"information");
if(deployHelpViewer.Location == null &&
(builder.CurrentProject.HelpFileFormat & HelpFileFormat.MSHelpViewer) != 0)
builder.ReportWarning("ODP0003", "MS Help Viewer will be generated " +
"but not deployed due to missing deployment location " +
"information");
if(deployWebsite.Location == null &&
(builder.CurrentProject.HelpFileFormat & HelpFileFormat.Website) != 0)
builder.ReportWarning("ODP0003", "Website will be generated " +
"but not deployed due to missing deployment location " +
"information");
}
