Merge pull request #51 from Excel-DNA/codex/add-utf-8-encoding-support

govert · web-flow · commit f83f4a76936d · 2025-08-17T13:51:01.000+02:00
Add optional UTF-8 output support
diff --git a/README.md b/README.md
@@ -134,12 +134,22 @@ that are exposed to Excel and documented using the ExcelFunctionAttribute and th
 
 If The ExcelDna.Documentation library has been referenced then the ExcelFunctionDocAttribute 
 is also available to include additional documentation fields that will not be exposed in the Excel Function 
-Wizard, but will be included in the HTML Help Workshop content.  
+Wizard, but will be included in the HTML Help Workshop content.
+
+Build Properties
+----------------
+ExcelDnaDoc runs automatically when referenced via NuGet. Additional options
+can be configured by defining MSBuild properties in your project file.
+To enable UTF-8 output, add the following property:
+
+```
+<ExcelDnaDocUseUtf8>true</ExcelDnaDocUseUtf8>
+```
 
 Dependencies
 ------------------
- NuGet Package Manager(http://nuget.codeplex.com/)  
- FAKE (F# MAKE) (http://fsharp.github.io/FAKE/)  
+ NuGet Package Manager(http://nuget.codeplex.com/)
+ FAKE (F# MAKE) (http://fsharp.github.io/FAKE/)
  Excel-DNA (http://exceldna.codeplex.com/)  
  RazorEngine(https://github.com/Antaris/RazorEngine)  
  HTML Help Workshop(http://msdn.microsoft.com/en-us/library/windows/desktop/ms669985(v=vs.85).aspx / https://web.archive.org/web/20200918004813/https://download.microsoft.com/download/0/A/9/0A939EF6-E31C-430F-A3DF-DFAE7960D564/htmlhelp.exe)  
diff --git a/docs/content/index.md b/docs/content/index.md
@@ -134,11 +134,21 @@ that are exposed to Excel and documented using the ExcelFunctionAttribute and th
 
 If The ExcelDna.Documentation library has been referenced then the ExcelFunctionDocAttribute 
 is also available to include additional documentation fields that will not be exposed in the Excel Function 
-Wizard, but will be included in the HTML Help Workshop content.  
+Wizard, but will be included in the HTML Help Workshop content.
+
+Build Properties
+----------------
+ExcelDnaDoc runs automatically when referenced via NuGet. Additional options
+can be set through MSBuild properties in your project file. To generate
+UTF-8 encoded documentation add:
+
+```
+<ExcelDnaDocUseUtf8>true</ExcelDnaDocUseUtf8>
+```
 
 This Project Uses
 -----------------
- [Excel-DNA](http://exceldna.codeplex.com/)  
+ [Excel-DNA](http://exceldna.codeplex.com/)
  [FAKE (F# MAKE)](http://fsharp.github.io/FAKE/)  
  [HTML Help Workshop ](http://msdn.microsoft.com/en-us/library/windows/desktop/ms669985(v=vs.85).aspx)  
  [NuGet Package Manager](http://nuget.codeplex.com/)  
diff --git a/src/ExcelDnaDoc.Html/HelpContent/CategoryTemplate.cshtml b/src/ExcelDnaDoc.Html/HelpContent/CategoryTemplate.cshtml
@@ -1,8 +1,10 @@
 ﻿@model ExcelDna.Documentation.Models.CategoryModel
+@using ExcelDnaDoc
 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
 
 <html>
 <head>
+    @if (HtmlHelp.UseUtf8Encoding) { <meta charset="utf-8"> }
     <link rel="stylesheet" type="text/css" href="helpstyle.css">
     <title></title>
 </head>
diff --git a/src/ExcelDnaDoc.Html/HelpContent/CommandListTemplate.cshtml b/src/ExcelDnaDoc.Html/HelpContent/CommandListTemplate.cshtml
@@ -1,8 +1,10 @@
 ﻿@model ExcelDna.Documentation.Models.AddInModel
+@using ExcelDnaDoc
 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
 
 <html>
 <head>
+    @if (HtmlHelp.UseUtf8Encoding) { <meta charset="utf-8"> }
     <link rel="stylesheet" type="text/css" href="helpstyle.css">
     <title></title>
 </head>
diff --git a/src/ExcelDnaDoc.Html/HelpContent/CommandTemplate.cshtml b/src/ExcelDnaDoc.Html/HelpContent/CommandTemplate.cshtml
@@ -1,8 +1,10 @@
 ﻿@model ExcelDna.Documentation.Models.CommandModel
+@using ExcelDnaDoc
 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
 
 <html>
 <head>
+    @if (HtmlHelp.UseUtf8Encoding) { <meta charset="utf-8"> }
     <link rel="stylesheet" type="text/css" href="helpstyle.css">
     <title></title>
 </head>
diff --git a/src/ExcelDnaDoc.Html/HelpContent/FunctionTemplate.cshtml b/src/ExcelDnaDoc.Html/HelpContent/FunctionTemplate.cshtml
@@ -1,4 +1,5 @@
 ﻿@model ExcelDna.Documentation.Models.FunctionModel
+@using ExcelDnaDoc
 @{
     var parameters = new List<string>();
     foreach (var p in Model.Parameters)
@@ -12,6 +13,7 @@
 
 <html>
 <head>
+    @if (HtmlHelp.UseUtf8Encoding) { <meta charset="utf-8"> }
     <link rel="stylesheet" type="text/css" href="helpstyle.css">
     <title></title>
 </head>
diff --git a/src/ExcelDnaDoc.Html/HelpContent/MethodListTemplate.cshtml b/src/ExcelDnaDoc.Html/HelpContent/MethodListTemplate.cshtml
@@ -1,8 +1,10 @@
 ﻿@model ExcelDna.Documentation.Models.AddInModel
+@using ExcelDnaDoc
 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
 
 <html>
 <head>
+    @if (HtmlHelp.UseUtf8Encoding) { <meta charset="utf-8"> }
     <link rel="stylesheet" type="text/css" href="helpstyle.css">
     <title></title>
 </head>
diff --git a/src/ExcelDnaDoc.Html/HelpContent/ProjectFileTemplate.cshtml b/src/ExcelDnaDoc.Html/HelpContent/ProjectFileTemplate.cshtml
@@ -1,5 +1,6 @@
 ﻿@model ExcelDna.Documentation.Models.AddInModel
 @using System.Text;
+@using ExcelDnaDoc
 @using System.Linq;
 @{ var functions = Model.Functions.Where(f => f.TopicId != string.Empty);
    var commands = Model.Commands.Where(c => c.TopicId != string.Empty);
@@ -22,7 +23,7 @@ Compiled file="@(Model.DnaFileName).chm"
 Contents file=Table of Contents.hhc
 Default topic=index.htm
 Display compile progress=No
-Language=0x409 English (United States)
+@if (HtmlHelp.UseUtf8Encoding) { "Code page=65001" } else { "Language=0x409 English (United States)" }
 
 [INFOTYPES]
 
diff --git a/src/ExcelDnaDoc.Html/HelpContent/TableOfContentsTemplate.cshtml b/src/ExcelDnaDoc.Html/HelpContent/TableOfContentsTemplate.cshtml
@@ -1,7 +1,9 @@
 ﻿@model ExcelDna.Documentation.Models.AddInModel
+@using ExcelDnaDoc
 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
 <html>
 <head>
+    @if (HtmlHelp.UseUtf8Encoding) { <meta charset="utf-8"> }
 <meta name="GENERATOR" content="Microsoft&reg; HTML Help Workshop 4.1">
 <!-- Sitemap 1.0 -->
 </head>
diff --git a/src/ExcelDnaDoc.Html/HtmlHelp.cs b/src/ExcelDnaDoc.Html/HtmlHelp.cs
@@ -5,6 +5,7 @@
     using System.Collections.Generic;
     using System.IO;
     using System.Linq;
+    using System.Text;
     using System.Threading.Tasks;
     using ExcelDna.Documentation.Models;
     using ExcelDnaDoc.Templates;
@@ -14,11 +15,13 @@ public static class HtmlHelp
         public static string BuildFolderPath { get; set; }
         public static string HelpContentSourcePath { get; set; }
         public static string HelpContentFolderPath { get; set; }
+        public static bool UseUtf8Encoding { get; private set; }
         public static ConcurrentDictionary<string, string> TemplateCache = new ConcurrentDictionary<string, string>();
 
-        public static void Create(AddInModel addin, string buildFolderPath, string outputFileName, string helpContentSourcePath = null, string hhcPath = null, string helpSubfolder = "HelpContent", bool excludeHidden = false, bool skipCompile = false, bool runAsync = false)
+        public static void Create(AddInModel addin, string buildFolderPath, string outputFileName, string helpContentSourcePath = null, string hhcPath = null, string helpSubfolder = "HelpContent", bool excludeHidden = false, bool skipCompile = false, bool runAsync = false, bool useUtf8Encoding = false)
         {
             BuildFolderPath = buildFolderPath;
+            UseUtf8Encoding = useUtf8Encoding;
             HelpContentFolderPath = Path.Combine(HtmlHelp.BuildFolderPath, helpSubfolder);
             HelpContentSourcePath = helpContentSourcePath ?? HelpContentFolderPath;
 
@@ -80,7 +83,10 @@ public static void Create(AddInModel addin, string buildFolderPath, string outpu
             }
             if (!File.Exists(stylePath))
             {
-                File.WriteAllText(stylePath, Properties.Resources.helpstyle);
+                if (UseUtf8Encoding)
+                    File.WriteAllText(stylePath, Properties.Resources.helpstyle, Encoding.UTF8);
+                else
+                    File.WriteAllText(stylePath, Properties.Resources.helpstyle);
             }
             else
             {
diff --git a/src/ExcelDnaDoc.Html/Views/ViewBase.cs b/src/ExcelDnaDoc.Html/Views/ViewBase.cs
@@ -65,11 +65,18 @@ public void Publish()
                 instance.Model = Model;
             });
 #endif
-            // strip non ANSI characters from result
-            content = Regex.Replace(content, @"[^\u0000-\u007F]", string.Empty);
-            content = content.TrimStart(new char[] { '\r', '\n' });
+            if (!HtmlHelp.UseUtf8Encoding)
+            {
+                // strip non ANSI characters from result
+                content = Regex.Replace(content, @"[^\u0000-\u007F]", string.Empty);
+                content = content.TrimStart(new char[] { '\r', '\n' });
+            }
 
-            File.WriteAllText(Path.Combine(HtmlHelp.HelpContentFolderPath, this.PageName), content);
+            string filePath = Path.Combine(HtmlHelp.HelpContentFolderPath, this.PageName);
+            if (HtmlHelp.UseUtf8Encoding)
+                File.WriteAllText(filePath, content, Encoding.UTF8);
+            else
+                File.WriteAllText(filePath, content);
         }
 
         private string LoadTemplate()
diff --git a/src/ExcelDnaDoc.Tasks/CreateDocumentation.cs b/src/ExcelDnaDoc.Tasks/CreateDocumentation.cs
@@ -41,7 +41,7 @@ public bool Execute()
                 string dnaFileName = AddInFileName ?? ProjectName + "-AddIn";
                 string docProjectName = DocProject ?? ProjectName + " Add-In";
                 var addin = Utility.ModelHelper.CreateAddInModel(libraries, defaultCategory, dnaFileName, docProjectName, ExcludeHidden);
-                HtmlHelp.Create(addin, targetDir, dnaFileName, helpContentSourcePath: helpContentSourcePath, hhcPath: HHCPath, excludeHidden: ExcludeHidden, skipCompile: false);
+                HtmlHelp.Create(addin, targetDir, dnaFileName, helpContentSourcePath: helpContentSourcePath, hhcPath: HHCPath, excludeHidden: ExcludeHidden, skipCompile: false, useUtf8Encoding: UseUtf8);
                 return true;
             }
             catch (Exception e)
@@ -71,5 +71,6 @@ public bool Execute()
         public string HHCPath { get; set; }
         public string DefaultCategory { get; set; }
         public string DocProject { get; set; }
+        public bool UseUtf8 { get; set; }
     }
 }
diff --git a/src/ExcelDnaDoc.Tasks/ExcelDnaDoc.targets b/src/ExcelDnaDoc.Tasks/ExcelDnaDoc.targets
@@ -1,9 +1,10 @@
 ﻿<?xml version="1.0" encoding="utf-8"?>
 <Project ToolsVersion="4.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
 
-	<PropertyGroup>
-		<ExcelDnaDocToolsPath Condition="$(ExcelDnaDocToolsPath) == '' Or $(ExcelDnaDocToolsPath) == '*Undefined*'">$(MSBuildThisFileDirectory)..\tools\</ExcelDnaDocToolsPath>
-	</PropertyGroup>
+        <PropertyGroup>
+                <ExcelDnaDocToolsPath Condition="$(ExcelDnaDocToolsPath) == '' Or $(ExcelDnaDocToolsPath) == '*Undefined*'">$(MSBuildThisFileDirectory)..\tools\</ExcelDnaDocToolsPath>
+                <ExcelDnaDocUseUtf8 Condition="'$(ExcelDnaDocUseUtf8)' == ''">false</ExcelDnaDocUseUtf8>
+        </PropertyGroup>
 
 	<PropertyGroup Condition="'$(MSBuildRuntimeType)' == 'Core'">
 		<ExcelDnaDocTasksPath>$(ExcelDnaDocToolsPath)\net6.0-windows7.0\</ExcelDnaDocTasksPath>
@@ -33,9 +34,10 @@
 			ExcludeHidden="$(ExcelDnaDocExcludeHidden)"
 			HHCPath="$(ExcelDnaDocHtmlHelpWorkshopCompilerPath)"
 			DefaultCategory="$(ExcelDnaDocDefaultCategory)"
-			DocProject="$(ExcelDnaDocProject)"
-			>
-		</CreateDocumentation>
+                        DocProject="$(ExcelDnaDocProject)"
+                        UseUtf8="$(ExcelDnaDocUseUtf8)"
+                        >
+                </CreateDocumentation>
 	</Target>
 	
 </Project>
diff --git a/src/ExcelDnaDoc/Program.cs b/src/ExcelDnaDoc/Program.cs
@@ -17,6 +17,7 @@ internal class Program
   /ExcludeHidden or /X    Optional. Excludes hidden functions from being documented if provided.
   /SkipCompile or /S      Optional. Skips compiling the HTML Help file (.chm) if provided.
   /Async or /A            Optional. Runs in async mode, consuming more cpu, but taking less time to run.
+  /Utf8 or /U             Optional. Writes help files using UTF-8 encoding.
 
 Example: ExcelDnaDoc.exe <build folder>\SampleLib-AddIn.dna
          The HTML Help Workshop content will be created in <build folder>\HelpContent\.
@@ -65,8 +66,13 @@ private static void Main(string[] args)
                         @"/Async", StringComparison.OrdinalIgnoreCase) ||
                         x.Equals(@"/A", StringComparison.OrdinalIgnoreCase));
 
+                bool useUtf8Encoding = args.Any(
+                    x => x.Equals(
+                        @"/Utf8", StringComparison.OrdinalIgnoreCase) ||
+                        x.Equals(@"/U", StringComparison.OrdinalIgnoreCase));
+
                 var addin = Utility.ModelHelper.CreateAddInModel(dnaPath, excludeHidden);
-                HtmlHelp.Create(addin, Path.GetDirectoryName(dnaPath), Path.GetFileNameWithoutExtension(dnaPath), excludeHidden: excludeHidden, skipCompile: skipCompile);
+                HtmlHelp.Create(addin, Path.GetDirectoryName(dnaPath), Path.GetFileNameWithoutExtension(dnaPath), excludeHidden: excludeHidden, skipCompile: skipCompile, useUtf8Encoding: useUtf8Encoding);
                 Console.WriteLine("Successful");
             }
         }
diff --git a/src/samples/EncodeHTML/EncodeHTML.csproj b/src/samples/EncodeHTML/EncodeHTML.csproj
@@ -1,10 +1,11 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
-	<PropertyGroup>
-		<TargetFramework>net6.0-windows</TargetFramework>
-		<ImplicitUsings>enable</ImplicitUsings>
-		<Nullable>enable</Nullable>
-	</PropertyGroup>
+        <PropertyGroup>
+                <TargetFramework>net6.0-windows</TargetFramework>
+                <ImplicitUsings>enable</ImplicitUsings>
+                <Nullable>enable</Nullable>
+                <ExcelDnaDocUseUtf8>True</ExcelDnaDocUseUtf8>
+        </PropertyGroup>
 
 	<ItemGroup>
 		<Reference Include="ExcelDna.Integration">
diff --git a/src/samples/LocalHelpContent/HelpContent/ProjectFileTemplate.cshtml b/src/samples/LocalHelpContent/HelpContent/ProjectFileTemplate.cshtml
@@ -1,5 +1,6 @@
 ﻿@model ExcelDna.Documentation.Models.AddInModel
 @using System.Text;
+@using ExcelDnaDoc
 @using System.Linq;
 @{ var functions = Model.Functions.Where(f => f.TopicId != string.Empty);
    var commands = Model.Commands.Where(c => c.TopicId != string.Empty);
@@ -22,7 +23,7 @@ Compiled file="@(Model.DnaFileName).chm"
 Contents file=Table of Contents.hhc
 Default topic=index.htm
 Display compile progress=No
-Language=0x409 English (United States)
+@if (HtmlHelp.UseUtf8Encoding) { "Code page=65001" } else { "Language=0x409 English (United States)" }
 
 [INFOTYPES]
 
