//=====================================================================
/// <summary>
/// This is used to copy the additional content token, image, and topic files to the build folder
/// </summary>
/// <param name="builder">The build process</param>
/// <remarks>This will copy the code snippet file if specified, save token information to a shared
/// content file called <strong>_Tokens_.xml</strong> in the build process's working folder, copy the
/// image files to the <strong>.\media</strong> folder in the build process's working folder, save the
/// media map to a file called <strong>_MediaContent_.xml</strong> in the build process's working folder,
/// and save the topic files to the <strong>.\ddueXml</strong> folder in the build process's working
/// folder. The topic files will have their content wrapped in a <c><topic></c> tag if needed and
/// will be named using their <see cref="Topic.Id" /> value.</remarks>
public void CopyContentFiles(BuildProcess builder)
{
string folder;
bool missingFile = false;
builder.ReportProgress("Copying standard token shared content file...");
builder.SubstitutionTags.TransformTemplate("HelpFileBuilderTokens.tokens", builder.TemplateFolder,
builder.WorkingFolder);
builder.ReportProgress("Checking for other token files...");
foreach(var tokenFile in this.tokenFiles)
if(!File.Exists(tokenFile.FullPath))
{
missingFile = true;
builder.ReportProgress(" Missing token file: {0}", tokenFile.FullPath);
}
else
{
builder.ReportProgress(" {0} -> {1}", tokenFile.FullPath,
Path.Combine(builder.WorkingFolder, Path.GetFileName(tokenFile.FullPath)));
builder.SubstitutionTags.TransformTemplate(Path.GetFileName(tokenFile.FullPath),
Path.GetDirectoryName(tokenFile.FullPath), builder.WorkingFolder);
}
if(missingFile)
throw new BuilderException("BE0052", "One or more token files could not be found");
builder.ReportProgress("Checking for code snippets files...");
foreach(var snippetsFile in this.codeSnippetFiles)
if(!File.Exists(snippetsFile.FullPath))
{
missingFile = true;
builder.ReportProgress(" Missing code snippets file: {0}", snippetsFile.FullPath);
}
else
builder.ReportProgress(" Found {0}", snippetsFile.FullPath);
if(missingFile)
throw new BuilderException("BE0053", "One or more code snippets files could not be found");
// Save the image info to a shared content file and copy the image files to the working folder
folder = builder.WorkingFolder + "media";
if(!Directory.Exists(folder))
Directory.CreateDirectory(folder);
// Create the build process's help format output folders too if needed
builder.EnsureOutputFoldersExist("media");
builder.ReportProgress("Copying images and creating the media map file...");
// Copy all image project items and create the content file
this.SaveImageSharedContent(builder.WorkingFolder + "_MediaContent_.xml", folder, builder);
// Copy the topic files
folder = builder.WorkingFolder + "ddueXml";
if(!Directory.Exists(folder))
Directory.CreateDirectory(folder);
builder.ReportProgress("Generating conceptual topic files");
// Get the list of valid framework namespaces for the referenced namespace search in each topic
HashSet<string> validNamespaces = new HashSet<string>(Directory.EnumerateFiles(builder.FrameworkReflectionDataFolder,
"*.xml", SearchOption.AllDirectories).Select(f => Path.GetFileNameWithoutExtension(f)));
// Create topic files
foreach(TopicCollection tc in topics)
{
tc.Load();
tc.GenerateConceptualTopics(folder, builder, validNamespaces);
}
}
/// <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 is used to copy the additional content token, image, and
/// topic files to the build folder.
/// </summary>
/// <param name="builder">The build process</param>
/// <remarks>This will copy the code snippet file if specified, save
/// token information to a shared content file called <b>_Tokens_.xml</b>
/// in the build process's working folder, copy the image files to the
/// <b>.\media</b> folder in the build process's working folder, save
/// the media map to a file called <b>_MediaContent_.xml</b> in the
/// build process's working folder, and save the topic files to the
/// <b>.\ddueXml</b> folder in the build process's working folder.
/// The topic files will have their content wrapped in a
/// <c><topic></c> tag if needed and will be named using their
/// <see cref="Topic.Id" /> value.</remarks>
public void CopyContentFiles(BuildProcess builder)
{
string folder;
bool missingFile = false;
builder.ReportProgress("Copying standard token shared content file...");
builder.TransformTemplate("HelpFileBuilderTokens.tokens",
builder.TemplateFolder, builder.WorkingFolder);
builder.ReportProgress("Checking for other token files...");
foreach(FileItem tokenFile in this.tokenFiles)
if(!File.Exists(tokenFile.FullPath))
{
missingFile = true;
builder.ReportProgress(" Missing token file: {0}", tokenFile.FullPath);
}
else
{
builder.ReportProgress(" {0} -> {1}", tokenFile.FullPath,
Path.Combine(builder.WorkingFolder, Path.GetFileName(tokenFile.FullPath)));
builder.TransformTemplate(Path.GetFileName(tokenFile.FullPath),
Path.GetDirectoryName(tokenFile.FullPath), builder.WorkingFolder);
}
if(missingFile)
throw new BuilderException("BE0052", "One or more token files could not be found");
builder.ReportProgress("Checking for code snippets files...");
foreach(FileItem snippetsFile in this.codeSnippetFiles)
if(!File.Exists(snippetsFile.FullPath))
{
missingFile = true;
builder.ReportProgress(" Missing code snippets file: {0}", snippetsFile.FullPath);
}
else
builder.ReportProgress(" Found {0}", snippetsFile.FullPath);
if(missingFile)
throw new BuilderException("BE0053", "One or more code snippets files could not be found");
// Save the image info to a shared content file and copy the
// image files to the working folder.
folder = builder.WorkingFolder + "Media";
if(!Directory.Exists(folder))
Directory.CreateDirectory(folder);
// Create the build process's help format output folders too if needed
builder.EnsureOutputFoldersExist("media");
builder.ReportProgress("Copying images and creating the media map file...");
// Copy all image project items and create the content file
imageFiles.SaveAsSharedContent(builder.WorkingFolder + "_MediaContent_.xml", folder, builder);
// Copy the topic files
folder = builder.WorkingFolder + "ddueXml";
if(!Directory.Exists(folder))
Directory.CreateDirectory(folder);
builder.ReportProgress("Generating conceptual topic files");
// Create topic files
foreach(TopicCollection tc in topics)
{
tc.Load();
tc.GenerateConceptualTopics(folder, builder);
}
}
