Minor updates

- Added RequiresHtmlExtractBuildStep to the presentation style settings to allow a legacy presentation style to indicate that it still needs the HTML extract step for website output. - Updated documentation for publication.
EWSoftware · Mar 4, 2023 · e273564 · e273564
1 parent 223f078
commit e273564
Show file tree

Hide file tree

Showing 17 changed files with 142 additions and 52 deletions.
diff --git a/Deployment/InstallerConfiguration.xml b/Deployment/InstallerConfiguration.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="utf-8" ?>
 <configuration>
 	<!-- This indicates the tools version with which this installer is associated.-->
-	<tools version="2022.12.30.0" />
+	<tools version="2023.3.4.0" />
 
 	<!-- Define the installer pages.  Third-party build tool and component providers can add new pages that
 			 they have created to install their own products as well. -->
@@ -13,7 +13,7 @@
 		<page type="Sandcastle.Installer.InstallerPages.WelcomePage" />
 
 		<page type="Sandcastle.Installer.InstallerPages.WhatsNewPage">
-			<whatsNew url="https://EWSoftware.github.io/SHFB/html/14daa2da-119b-4b45-b24a-1c8010d0aa06.htm"
+			<whatsNew url="https://EWSoftware.github.io/SHFB/html/ed81b95f-c8d2-4d9e-9397-b50494fc0cc5.htm"
 				description="Current Version Release Notes" />
 			<whatsNew url="https://EWSoftware.github.io/SHFB/html/bc933f8f-e792-45bf-afec-62aa2c46aa3b.htm"
 				description="Third-Party Component Migration Support" />

diff --git a/Documentation/SandcastleBuilder/CommonTokens.tokens b/Documentation/SandcastleBuilder/CommonTokens.tokens
@@ -6,6 +6,6 @@
     <ddue:linkUri>https://GitHub.com/EWSoftware/SHFB</ddue:linkUri>
     <ddue:linkTarget>_blank</ddue:linkTarget>
 </ddue:externalLink></item>
-  <item id="SandcastleVersion">v2022.12.30.0</item>
+  <item id="SandcastleVersion">v2023.3.4.0</item>
   <item id="VisualStudioMinVersion">Visual Studio 2017</item>
 </content>
diff --git a/Documentation/SandcastleBuilder/Content/VersionHistory/VersionHistory.aml b/Documentation/SandcastleBuilder/Content/VersionHistory/VersionHistory.aml
@@ -20,6 +20,12 @@ updating third-party components, plug-ins, presentation styles, and syntax gener
 version of the help file builder.</para>
 
 				<list class="bullet">
+					<listItem>
+						<para>
+							<link xlink:href="ed81b95f-c8d2-4d9e-9397-b50494fc0cc5" />
+						</para>
+					</listItem>
+
 					<listItem>
 						<para>
 							<link xlink:href="14daa2da-119b-4b45-b24a-1c8010d0aa06" />

diff --git a/Documentation/SandcastleBuilder/Content/VersionHistory/v2023.3.4.0.aml b/Documentation/SandcastleBuilder/Content/VersionHistory/v2023.3.4.0.aml
@@ -0,0 +1,74 @@
+<?xml version="1.0" encoding="utf-8"?>
+<topic id="ed81b95f-c8d2-4d9e-9397-b50494fc0cc5" revisionNumber="1">
+	<developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">
+		<introduction>
+			<para>Release notes for version 2023.3.4.0.  See the prior version release notes for information on the
+breaking changes made to the presentation styles implementation.</para>
+		</introduction>
+
+		<section>
+			<title>Build Tools</title>
+			<content>
+				<list class="bullet">
+					<listItem>
+						<para>Updated the MSHC Component to add whitespace before and after the title element to work around
+an apparent bug in the help viewer that causes it to render a blank TOC.</para>
+					</listItem>
+
+					<listItem>
+						<para>Updated the Resolve Reference Links component to issue a better warning describing the issue of
+missing/empty <codeInline>cref</codeInline> attribute values.</para>
+					</listItem>
+
+					<listItem>
+						<para>Fixed some issues in MRefBuilder so that it handles some variations of the template argument
+comparisons when trying to match inherited members.</para>
+					</listItem>
+				</list>
+
+			</content>
+		</section>
+
+		<section>
+			<title>Sandcastle Help File Builder</title>
+			<content>
+				<list class="bullet">
+					<listItem>
+						<para>Removed wording about using the HTML website option if a local web server cannot be found to
+view the output.</para>
+					</listItem>
+
+					<listItem>
+						<para>Fixed an odd case where selecting the wrong framework type to document assemblies caused
+duplicate TOC entries.</para>
+					</listItem>
+				</list>
+			</content>
+		</section>
+
+		<section>
+			<title>Presentation Styles</title>
+			<content>
+				<list class="bullet">
+					<listItem>
+						<para>Fixed handling of section elements without a title when building the auto-outline.</para>
+					</listItem>
+
+					<listItem>
+						<para>Added handling of empty types and enumerations.</para>
+					</listItem>
+
+					<listItem>
+						<para>Updated the presentation styles to handle missing or blank <codeInline>cref</codeInline>
+attribute values.</para>
+					</listItem>
+				</list>
+			</content>
+		</section>
+
+		<relatedTopics>
+			<link xlink:href="078cc1c7-7995-431e-bf9c-8813becbe8df" />
+		</relatedTopics>
+
+	</developerConceptualDocument>
+</topic>
diff --git a/Documentation/SandcastleBuilder/SandcastleBuilder.content b/Documentation/SandcastleBuilder/SandcastleBuilder.content
@@ -1369,12 +1369,17 @@
       <HelpKeyword index="K" term="History" />
       <HelpKeyword index="K" term="Version History" />
     </HelpKeywords>
+    <Topic id="ed81b95f-c8d2-4d9e-9397-b50494fc0cc5" visible="True" isSelected="true" title="Version 2023.3.4.0">
+      <HelpKeywords>
+        <HelpKeyword index="K" term="versions, 2023.3.4.0" />
+      </HelpKeywords>
+    </Topic>
     <Topic id="14daa2da-119b-4b45-b24a-1c8010d0aa06" visible="True" title="Version 2022.12.30.0">
       <HelpKeywords>
         <HelpKeyword index="K" term="versions, 2022.12.30.0" />
       </HelpKeywords>
     </Topic>
-    <Topic id="5e4cbd92-c668-4774-95ea-4e2032c2729c" visible="True" isSelected="true" title="Version 2022.10.15.0">
+    <Topic id="5e4cbd92-c668-4774-95ea-4e2032c2729c" visible="True" title="Version 2022.10.15.0">
       <HelpKeywords>
         <HelpKeyword index="K" term="versions 2022.10.15.0" />
       </HelpKeywords>

diff --git a/Documentation/SandcastleBuilder/SandcastleBuilder.shfbproj b/Documentation/SandcastleBuilder/SandcastleBuilder.shfbproj
@@ -31,11 +31,11 @@
     <FrameworkVersion>.NET Core/.NET Standard/.NET 5.0+</FrameworkVersion>
     <HelpTitle>Sandcastle Help File Builder Documentation</HelpTitle>
     <CopyrightHref>https://GitHub.com/EWSoftware/SHFB</CopyrightHref>
-    <CopyrightText>[v{%40HelpFileVersion}] Copyright \xA9 2006-2022, Eric Woodruff, All rights reserved</CopyrightText>
+    <CopyrightText>[v{%40HelpFileVersion}] Copyright \xA9 2006-2023, Eric Woodruff, All rights reserved</CopyrightText>
     <FeedbackEMailAddress>Eric%40EWoodruff.us</FeedbackEMailAddress>
     <PresentationStyle>Default2022</PresentationStyle>
     <SyntaxFilters>Standard</SyntaxFilters>
-    <HelpFileVersion>2022.12.30.0</HelpFileVersion>
+    <HelpFileVersion>2023.3.4.0</HelpFileVersion>
     <ComponentConfigurations>
     </ComponentConfigurations>
     <DocumentationSources>
@@ -404,6 +404,7 @@
     <None Include="Content\VersionHistory\v2022.12.30.0.aml" />
     <None Include="Content\VersionHistory\v2022.2.6.0.aml" />
     <None Include="Content\VersionHistory\v2022.8.14.0.aml" />
+    <None Include="Content\VersionHistory\v2023.3.4.0.aml" />
     <None Include="Content\VisualStudio\GoToDefinition.aml" />
     <None Include="Content\VisualStudio\ItemFileTemplates.aml" />
     <None Include="Content\VisualStudio\FeatureComparison.aml" />

diff --git a/NuGet/SHFB.nuspec b/NuGet/SHFB.nuspec
@@ -2,7 +2,7 @@
 <package xmlns="http://schemas.microsoft.com/packaging/2011/08/nuspec.xsd">
 	<metadata>
 		<id>EWSoftware.SHFB</id>
-		<version>2022.12.30.0</version>
+		<version>2023.3.4.0</version>
 		<title>Sandcastle Help File Builder</title>
 		<authors>Eric Woodruff</authors>
 		<owners>Eric Woodruff</owners>
@@ -13,7 +13,7 @@
 		<iconUrl>https://raw.githubusercontent.com/EWSoftware/SHFB/master/NuGet/SHFB.png</iconUrl>
 		<requireLicenseAcceptance>false</requireLicenseAcceptance>
 		<description>This package allows you to deploy the Sandcastle Help File Builder tools inside of a project to build help files without installing the tools manually such as on a build server.  Some limitations apply.  You will also need to install the reflection data set packages that you need for your projects.</description>
-		<copyright>Eric Woodruff (c) 2006-2022</copyright>
+		<copyright>Eric Woodruff (c) 2006-2023</copyright>
 		<tags>SHFB documentation sandcastle help XML comments</tags>
 		<!-- Note that we do not add dependencies on the reflection data set packages.  The idea here is that you
 				 only need to install the packages that you actually need. -->

diff --git a/SHFB/Source/PresentationStyles/VS2013/VisualStudio2013PresentationStyle.cs b/SHFB/Source/PresentationStyles/VS2013/VisualStudio2013PresentationStyle.cs
@@ -2,8 +2,8 @@
 // System  : Sandcastle Tools Standard Presentation Styles
 // File    : VisualStudio2013PresentationStyle.cs
 // Author  : Eric Woodruff  (Eric@EWoodruff.us)
-// Updated : 08/06/2022
-// Note    : Copyright 2014-2022, Eric Woodruff, All rights reserved
+// Updated : 03/03/2023
+// Note    : Copyright 2014-2023, Eric Woodruff, All rights reserved
 //
 // This file contains the presentation style definition for the Visual Studio 2013 presentation style.
 //
@@ -20,7 +20,6 @@
 using System;
 using System.Collections.Generic;
 using System.IO;
-using System.Linq;
 using System.Reflection;
 
 using Sandcastle.Core;
@@ -52,6 +51,9 @@ public VisualStudio2013PresentationStyle()
 
             this.SupportsNamespaceGrouping = this.SupportsCodeSnippetGrouping = true;
 
+            // This is the legacy format and requires the HTML extract build step for website output
+            this.RequiresHtmlExtractBuildStep = true;
+
             this.DocumentModelApplicator = new StandardDocumentModel();
             this.ApiTableOfContentsGenerator = new StandardApiTocGenerator();
             this.TopicTransformation = new VisualStudio2013Transformation(this.SupportedFormats, this.ResolvePath);

diff --git a/SHFB/Source/SandcastleBuilderUtils/BuildEngine/BuildProcess.cs b/SHFB/Source/SandcastleBuilderUtils/BuildEngine/BuildProcess.cs
@@ -1,9 +1,9 @@
-//===============================================================================================================
+//=============================================================================================================== 
 // System  : Sandcastle Help File Builder Utilities
 // File    : BuildProcess.cs
 // Author  : Eric Woodruff  (Eric@EWoodruff.us)
-// Updated : 10/07/2022
-// Note    : Copyright 2006-2022, Eric Woodruff, All rights reserved
+// Updated : 03/03/2023
+// Note    : Copyright 2006-2023, Eric Woodruff, All rights reserved
 //
 // This file contains the thread class that handles all aspects of the build process.
 //
@@ -1324,7 +1324,7 @@ public void Build()
                 //       to be ran for website output anymore.
                 if((project.HelpFileFormat & HelpFileFormats.HtmlHelp1) != 0 ||
                   ((project.HelpFileFormat & HelpFileFormats.Website) != 0 &&
-                    presentationStyle.BasePath == "VS2013"))
+                    presentationStyle.RequiresHtmlExtractBuildStep))
                 {
                     this.ReportProgress(BuildStep.ExtractingHtmlInfo,
                         "Extracting HTML info for HTML Help 1 and/or website...");
@@ -1345,7 +1345,7 @@ public void Build()
 
                         this.ExecutePlugIns(ExecutionBehaviors.After);
 
-                        // Keep the HTML extract tool around until after the help file is build as plug-ins
+                        // Keep the HTML extract tool around until after the help 1 file is built as plug-ins
                         // may rely on it for values such as the localized file folder.
                     }
                 }
@@ -1622,8 +1622,7 @@ public void Build()
 
                     this.ExecutePlugIns(ExecutionBehaviors.After);
 
-                    if(componentContainer != null)
-                        componentContainer.Dispose();
+                    componentContainer?.Dispose();
                 }
                 catch(Exception ex)
                 {
@@ -1642,8 +1641,7 @@ public void Build()
                     if(this.CurrentBuildStep == BuildStep.Completed && !project.KeepLogFile)
                         File.Delete(this.LogFilename);
 
-                    if(resolver != null)
-                        resolver.Dispose();
+                    resolver?.Dispose();
                 }
             }
         }
@@ -1723,33 +1721,27 @@ protected void ReportProgress(BuildStep step, string message, params object[] ar
                         "{0:00}:{1:00}:{2:00.0000}", Math.Floor(runtime.TotalSeconds / 3600),
                         Math.Floor((runtime.TotalSeconds % 3600) / 60), (runtime.TotalSeconds % 60)));
 
-                    if(swLog != null)
-                        swLog.WriteLine(pa.Message);
+                    swLog?.WriteLine(pa.Message);
 
-                    if(this.ProgressReportProvider != null)
-                        this.ProgressReportProvider.Report(pa);
+                    this.ProgressReportProvider?.Report(pa);
                 }
 
-                if(this.ProgressReportProvider != null)
-                    this.ProgressReportProvider.Report(new BuildProgressEventArgs(this.CurrentBuildStep, false,
-                        "-------------------------------"));
+                this.ProgressReportProvider?.Report(new BuildProgressEventArgs(this.CurrentBuildStep, false,
+                    "-------------------------------"));
 
                 stepStart = DateTime.Now;
                 this.CurrentBuildStep = step;
 
-                if(swLog != null)
-                    swLog.WriteLine("</buildStep>\r\n<buildStep step=\"{0}\">", step);
+                swLog?.WriteLine("</buildStep>\r\n<buildStep step=\"{0}\">", step);
             }
 
             pa = new BuildProgressEventArgs(this.CurrentBuildStep, stepChanged,
                 args == null || args.Length == 0 ? message : String.Format(CultureInfo.CurrentCulture, message, args));
 
             // Save the message to the log file
-            if(swLog != null)
-                swLog.WriteLine(HttpUtility.HtmlEncode(pa.Message));
+            swLog?.WriteLine(HttpUtility.HtmlEncode(pa.Message));
 
-            if(this.ProgressReportProvider != null)
-                this.ProgressReportProvider.Report(pa);
+            this.ProgressReportProvider?.Report(pa);
         }
         #endregion
 

diff --git a/SHFB/Source/SandcastleBuilderUtils/GlobalSuppressions.cs b/SHFB/Source/SandcastleBuilderUtils/GlobalSuppressions.cs
@@ -54,3 +54,4 @@
 [assembly: SuppressMessage("Design", "CA1031:Do not catch general exception types", Justification = "<Pending>", Scope = "member", Target = "~M:SandcastleBuilder.Utils.BuildEngine.MarkdownContentGenerator.Execute~System.Boolean")]
 [assembly: SuppressMessage("Globalization", "CA1308:Normalize strings to uppercase", Justification = "<Pending>", Scope = "member", Target = "~M:SandcastleBuilder.Utils.BuildEngine.MarkdownContentGenerator.ApplyChanges(System.String,System.Xml.Linq.XDocument)~System.String")]
 [assembly: SuppressMessage("Maintainability", "CA1508:Avoid dead conditional code", Justification = "<Pending>", Scope = "member", Target = "~M:SandcastleBuilder.Utils.BuildEngine.BuildProcess.ReportProgress(SandcastleBuilder.Utils.BuildEngine.BuildStep,System.String,System.Object[])")]
+[assembly: SuppressMessage("Style", "IDE0270:Use coalesce expression", Justification = "<Pending>", Scope = "member", Target = "~M:SandcastleBuilder.Utils.BuildEngine.BuildProcess.Build")]
diff --git a/SHFB/Source/SandcastleBuilderUtils/Properties/AssemblyInfoShared.cs b/SHFB/Source/SandcastleBuilderUtils/Properties/AssemblyInfoShared.cs
@@ -2,8 +2,8 @@
 // System  : Sandcastle Help File Builder
 // File    : AssemblyInfoShared.cs
 // Author  : Eric Woodruff  (Eric@EWoodruff.us)
-// Updated : 12/30/2022
-// Note    : Copyright 2006-2022, Eric Woodruff, All rights reserved
+// Updated : 03/04/2023
+// Note    : Copyright 2006-2023, Eric Woodruff, All rights reserved
 //
 // Sandcastle Help File Builder common assembly attributes.
 //
@@ -90,14 +90,14 @@ internal static partial class AssemblyInfo
     //
     // This is used to set the assembly file version.  This will change with each new release.  MSIs only
     // support a Major value between 0 and 255 so we drop the century from the year on this one.
-    public const string FileVersion = "22.12.30.0";
+    public const string FileVersion = "23.3.4.0";
 
     // Common product version
     //
     // This may contain additional text to indicate Alpha or Beta states.  The version number will always match
     // the file version above but includes the century on the year.
-    public const string ProductVersion = "2022.12.30.0";
+    public const string ProductVersion = "2023.3.4.0";
 
     // Assembly copyright information
-    public const string Copyright = "Copyright \xA9 2006-2022, Eric Woodruff, All Rights Reserved";
+    public const string Copyright = "Copyright \xA9 2006-2023, Eric Woodruff, All Rights Reserved";
 }
diff --git a/SHFB/Source/SandcastleCore/PresentationStyle/PresentationStyleSettings.cs b/SHFB/Source/SandcastleCore/PresentationStyle/PresentationStyleSettings.cs
@@ -2,8 +2,8 @@
 // System  : Sandcastle Tools - Sandcastle Tools Core Class Library
 // File    : PresentationStyleSettings.cs
 // Author  : Eric Woodruff  (Eric@EWoodruff.us)
-// Updated : 11/11/2022
-// Note    : Copyright 2012-2022, Eric Woodruff, All rights reserved
+// Updated : 03/03/2023
+// Note    : Copyright 2012-2023, Eric Woodruff, All rights reserved
 //
 // This file contains a class that is used to contain settings information for a specific presentation style
 //
@@ -87,6 +87,13 @@ public abstract class PresentationStyleSettings
         /// in the project.</remarks>
         public bool SupportsCodeSnippetGrouping { get; protected set; }
 
+        /// <summary>
+        /// This is used to get or set whether or not the presentation style requires the HTML extract build step
+        /// for website output.
+        /// </summary>
+        /// <value>This is false by default and is currently only used by the legacy VS2013 presentation style</value>
+        public bool RequiresHtmlExtractBuildStep { get; protected set; }
+
         /// <summary>
         /// This read-only property returns the list of help content file locations
         /// </summary>

diff --git a/SHFB/Source/SandcastleCore/Properties/AssemblyInfoShared.cs b/SHFB/Source/SandcastleCore/Properties/AssemblyInfoShared.cs
@@ -1,8 +1,8 @@
 //===============================================================================================================
 // System  : Sandcastle Tools
 // File    : AssemblyInfoShared.cs
-// Updated : 12/30/2022
-// Note    : Copyright 2006-2022, Microsoft Corporation, All rights reserved
+// Updated : 03/04/2023
+// Note    : Copyright 2006-2023, Microsoft Corporation, All rights reserved
 //
 // Sandcastle tools common assembly attributes.
 //
@@ -73,15 +73,15 @@ internal static partial class AssemblyInfo
     //
     // This is used to set the assembly file version.  This will change with each new release.  MSIs only
     // support a Major value between 0 and 255 so we drop the century from the year on this one.
-    public const string FileVersion = "22.12.30.0";
+    public const string FileVersion = "23.3.4.0";
 
     // Common product version
     //
     // This may contain additional text to indicate Alpha or Beta states.  The version number will always match
     // the file version above but includes the century on the year.
-    public const string ProductVersion = "2022.12.30.0";
+    public const string ProductVersion = "2023.3.4.0";
 
     // Assembly copyright information
-    public const string Copyright = "Copyright \xA9 2006-2022, Microsoft Corporation, All Rights Reserved.\r\n" +
-        "Portions Copyright \xA9 2006-2021, Eric Woodruff, All Rights Reserved.";
+    public const string Copyright = "Copyright \xA9 2006-2023, Microsoft Corporation, All Rights Reserved.\r\n" +
+        "Portions Copyright \xA9 2006-2023, Eric Woodruff, All Rights Reserved.";
 }