feat(developer): introduce WelcomeFile property to packages

Fixes #9478.

This adds a property WelcomeFile to .kps and kmp.json, which allows us
to move away from the hardcoded welcome.htm filename in the future, and
makes transform from Markdown (#9477) a simpler operation, and just
generally starts the cleanup of the messiness of hard-coded filenames.

The package compiler will fallback to injecting welcome.htm into this
property if (a) welcome.htm is present, and (b) the property does not
already have a value. This doesn't buy us much because we still need to
support welcome.htm for existing legacy packages, but does mean that
our .kmp package metadata will be more consistent for packages compiled
with 17.0+ compilers.

common/schemas/kps/kps.xsd

@@ -32,6 +32,7 @@
             <xs:element minOccurs="0" maxOccurs="1" name="ReadMeFile" type="xs:string" />
             <xs:element minOccurs="0" maxOccurs="1" name="GraphicFile" type="xs:string" />
             <xs:element minOccurs="0" maxOccurs="1" name="LicenseFile" type="xs:string" />
+            <xs:element minOccurs="0" maxOccurs="1" name="WelcomeFile" type="xs:string" />
             <xs:element minOccurs="0" maxOccurs="1" name="MSIFileName" type="xs:string" />
             <xs:element minOccurs="0" maxOccurs="1" name="MSIOptions" type="xs:string" />
             <xs:element minOccurs="0" maxOccurs="1" name="FollowKeyboardVersion" type="km-empty" />

common/web/types/src/package/kmp-json-file.ts

@@ -18,6 +18,7 @@ export interface KmpJsonFileOptions {
   readmeFile?: string;
   graphicFile?: string;
   licenseFile?: string;
+  welcomeFile?: string;
   executeProgram?: string;
   msiFilename?: string;
   msiOptions?: string;

common/web/types/src/package/kps-file.ts

@@ -42,6 +42,7 @@ export interface KpsFileOptions {
   readMeFile?: string;
   graphicFile?: string;
   licenseFile?: string;
+  welcomeFile?: string;
   executeProgram?: string;
   msiFileName?: string;
   msiOptions?: string;

common/windows/delphi/packages/PackageInfo.pas

@@ -150,6 +150,7 @@   TPackageOptions = class(TPackageBaseObject)
     FReadmeFile: TPackageContentFile;
     FGraphicFile: TPackageContentFile;
     FLicenseFile: TPackageContentFile;
+    FWelcomeFile: TPackageContentFile;
     FLoadLegacy: Boolean;
     procedure SetReadmeFile(const Value: TPackageContentFile);
     procedure SetExecuteProgram(Value: WideString);
@@ -162,6 +163,9 @@   TPackageOptions = class(TPackageBaseObject)
     procedure SetLicenseFile(const Value: TPackageContentFile);
     procedure LicenseRemoved(Sender: TObject;
       EventType: TPackageNotifyEventType; var FAllow: Boolean);
+    procedure SetWelcomeFile(const Value: TPackageContentFile);
+    procedure WelcomeRemoved(Sender: TObject;
+      EventType: TPackageNotifyEventType; var FAllow: Boolean);
   public
     constructor Create(APackage: TPackage); override;
     destructor Destroy; override;
@@ -178,6 +182,7 @@   TPackageOptions = class(TPackageBaseObject)
     property ReadmeFile: TPackageContentFile read FReadmeFile write SetReadmeFile;
     property GraphicFile: TPackageContentFile read FGraphicFile write SetGraphicFile;
     property LicenseFile: TPackageContentFile read FLicenseFile write SetLicenseFile;
+    property WelcomeFile: TPackageContentFile read FWelcomeFile write SetWelcomeFile;
   end;
 
   { Package Information }
@@ -515,6 +520,7 @@ implementation
   SReadmeNotOwnedCorrectly = 'The readme file ''%s'' referred to is not part of the package.';
   SGraphicNotOwnedCorrectly = 'The graphic file ''%s'' referred to is not part of the package.';
   SLicenseNotOwnedCorrectly = 'The license file ''%s'' referred to is not part of the package.';
+  SWelcomeNotOwnedCorrectly = 'The welcome file ''%s'' referred to is not part of the package.';
   SFileNotOwnedCorrectly = 'The file ''%s'' referred to is not part of the package.';
   SDisplayFontNotOwnedCorrectly = 'The display font file ''%s'' referred to is not part of the package.';
   SOSKFontNotOwnedCorrectly = 'The OSK font file ''%s'' referred to is not part of the package.';
@@ -568,6 +574,7 @@ implementation
   SJSON_Options_ReadMeFile = 'readmeFile';
   SJSON_Options_GraphicFile = 'graphicFile';
   SJSON_Options_LicenseFile = 'licenseFile';
+  SJSON_Options_WelcomeFile = 'welcomeFile';
 
   SJSON_Registry = 'registry';
   SJSON_Registry_Root = 'root';
@@ -665,6 +672,9 @@ procedure TPackageOptions.Assign(Source: TPackageOptions);
   if Assigned(Source.LicenseFile)
     then LicenseFile := Package.Files.FromFileName(Source.LicenseFile.FileName)
     else LicenseFile := nil;
+  if Assigned(Source.WelcomeFile)
+    then WelcomeFile := Package.Files.FromFileName(Source.WelcomeFile.FileName)
+    else WelcomeFile := nil;
 end;
 
 constructor TPackageOptions.Create(APackage: TPackage);
@@ -679,6 +689,7 @@ destructor TPackageOptions.Destroy;
   ReadmeFile := nil;
   GraphicFile := nil;
   LicenseFile := nil;
+  WelcomeFile := nil;
   inherited Destroy;
 end;
 
@@ -697,16 +708,23 @@ procedure TPackageOptions.LicenseRemoved(Sender: TObject; EventType: TPackageNot
   FLicenseFile := nil;
 end;
 
+procedure TPackageOptions.WelcomeRemoved(Sender: TObject; EventType: TPackageNotifyEventType; var FAllow: Boolean);
+begin
+  FWelcomeFile := nil;
+end;
+
 procedure TPackageOptions.LoadXML(ARoot: IXMLNode);
 begin
   FileVersion :=                XmlVarToStr(ARoot.ChildNodes['System'].ChildNodes['FileVersion'].NodeValue);
   ExecuteProgram :=             XmlVarToStr(ARoot.ChildNodes['Options'].ChildNodes['ExecuteProgram'].NodeValue);
   ReadmeFile :=                 Package.Files.FromFileName(XmlVarToStr(ARoot.ChildNodes['Options'].ChildNodes['ReadMeFile'].NodeValue));
   GraphicFile :=                Package.Files.FromFileName(XmlVarToStr(ARoot.ChildNodes['Options'].ChildNodes['GraphicFile'].NodeValue));
   LicenseFile :=                Package.Files.FromFileName(XmlVarToStr(ARoot.ChildNodes['Options'].ChildNodes['LicenseFile'].NodeValue));
+  WelcomeFile :=                Package.Files.FromFileName(XmlVarToStr(ARoot.ChildNodes['Options'].ChildNodes['WelcomeFile'].NodeValue));
   if Assigned(ReadmeFile) then ReadmeFile.AddNotifyObject(ReadmeRemoved);
   if Assigned(GraphicFile) then GraphicFile.AddNotifyObject(GraphicRemoved);
   if Assigned(LicenseFile) then LicenseFile.AddNotifyObject(LicenseRemoved);
+  if Assigned(WelcomeFile) then WelcomeFile.AddNotifyObject(WelcomeRemoved);
 end;
 
 procedure TPackageOptions.SaveXML(ARoot: IXMLNode);
@@ -719,6 +737,8 @@ procedure TPackageOptions.SaveXML(ARoot: IXMLNode);
     ARoot.ChildNodes['Options'].ChildNodes['GraphicFile'].NodeValue := GraphicFile.RelativeFileName;
   if Assigned(LicenseFile) then
     ARoot.ChildNodes['Options'].ChildNodes['LicenseFile'].NodeValue := LicenseFile.RelativeFileName;
+  if Assigned(WelcomeFile) then
+    ARoot.ChildNodes['Options'].ChildNodes['WelcomeFile'].NodeValue := WelcomeFile.RelativeFileName;
 end;
 
 procedure TPackageOptions.LoadIni(AIni: TIniFile);
@@ -730,6 +750,7 @@ procedure TPackageOptions.LoadIni(AIni: TIniFile);
   if Assigned(ReadmeFile) then ReadmeFile.AddNotifyObject(ReadmeRemoved);
   if Assigned(GraphicFile) then GraphicFile.AddNotifyObject(GraphicRemoved);
   // LicenseFile not supported in ini
+  // WelcomeFile not supported in ini
 end;
 
 procedure TPackageOptions.LoadJSON(ARoot: TJSONObject);
@@ -744,9 +765,11 @@ procedure TPackageOptions.LoadJSON(ARoot: TJSONObject);
   ReadmeFile :=                 Package.Files.FromFileName(GetJsonValueString(FOptions, SJSON_Options_ReadMeFile));
   GraphicFile :=                Package.Files.FromFileName(GetJsonValueString(FOptions, SJSON_Options_GraphicFile));
   LicenseFile :=                Package.Files.FromFileName(GetJsonValueString(FOptions, SJSON_Options_LicenseFile));
+  WelcomeFile :=                Package.Files.FromFileName(GetJsonValueString(FOptions, SJSON_Options_WelcomeFile));
   if Assigned(ReadmeFile) then ReadmeFile.AddNotifyObject(ReadmeRemoved);
   if Assigned(GraphicFile) then GraphicFile.AddNotifyObject(GraphicRemoved);
   if Assigned(LicenseFile) then LicenseFile.AddNotifyObject(LicenseRemoved);
+  if Assigned(WelcomeFile) then WelcomeFile.AddNotifyObject(WelcomeRemoved);
 end;
 
 procedure TPackageOptions.SaveIni(AIni: TIniFile);
@@ -758,6 +781,7 @@ procedure TPackageOptions.SaveIni(AIni: TIniFile);
   if Assigned(GraphicFile) then
     AIni.WriteString('Package', 'GraphicFile', GraphicFile.RelativeFileName);
   // licenseFile not supported in ini
+  // welcomeFile not supported in ini
 end;
 
 procedure TPackageOptions.SaveJSON(ARoot: TJSONObject);
@@ -779,6 +803,8 @@ procedure TPackageOptions.SaveJSON(ARoot: TJSONObject);
     FOptions.AddPair(SJSON_Options_GraphicFile, GraphicFile.RelativeFileName);
   if Assigned(LicenseFile) then
     FOptions.AddPair(SJSON_Options_LicenseFile, LicenseFile.RelativeFileName);
+  if Assigned(WelcomeFile) then
+    FOptions.AddPair(SJSON_Options_WelcomeFile, WelcomeFile.RelativeFileName);
 end;
 
 procedure TPackageOptions.SetExecuteProgram(Value: WideString);
@@ -819,6 +845,19 @@ procedure TPackageOptions.SetLicenseFile(const Value: TPackageContentFile);
   end;
 end;
 
+procedure TPackageOptions.SetWelcomeFile(const Value: TPackageContentFile);
+begin
+  if Assigned(FWelcomeFile) then FWelcomeFile.RemoveNotifyObject(WelcomeRemoved);
+  if not Assigned(Value) then
+    FWelcomeFile := nil
+  else
+  begin
+    if Value.Package <> Package then raise EPackageInfo.CreateFmt(SWelcomeNotOwnedCorrectly, [Value]);
+    FWelcomeFile := Value;
+    FWelcomeFile.AddNotifyObject(WelcomeRemoved);
+  end;
+end;
+
 procedure TPackageOptions.SetReadmeFile(const Value: TPackageContentFile);
 begin
   if Assigned(FReadmeFile) then FReadmeFile.RemoveNotifyObject(ReadmeRemoved);

developer/src/kmc-package/src/compiler/kmp-compiler.ts

@@ -16,6 +16,11 @@ import { markdownToHTML } from './markdown.js';
 const KMP_JSON_FILENAME = 'kmp.json';
 const KMP_INF_FILENAME = 'kmp.inf';
 
+// welcome.htm: this is a legacy filename, as of 17.0 the welcome
+// (documentation) filename can be any file, but we will fallback to detecting
+// this filename for existing keyboard packages.
+const WELCOME_HTM_FILENAME = 'welcome.htm';
+
 export class KmpCompiler {
 
   constructor(private callbacks: CompilerCallbacks) {
@@ -84,6 +89,7 @@ export class KmpCompiler {
       kmp.options.msiOptions = kps.options.msiOptions || undefined;
       kmp.options.readmeFile = kps.options.readMeFile || undefined;
       kmp.options.licenseFile = kps.options.licenseFile || undefined;
+      kmp.options.welcomeFile = kps.options.welcomeFile || undefined;
     }
 
     //
@@ -373,6 +379,8 @@ export class KmpCompiler {
       return null;
     }
 
+    // TODO #9477: transform .md to .htm
+
     // Remove path data from file references in options
 
     if(data.options.graphicFile) {
@@ -384,6 +392,16 @@ export class KmpCompiler {
     if(data.options.licenseFile) {
       data.options.licenseFile = this.callbacks.path.basename(data.options.licenseFile);
     }
+    if(data.options.welcomeFile) {
+      data.options.welcomeFile = this.callbacks.path.basename(data.options.welcomeFile);
+    } else if(data.files.find(file => file.name == WELCOME_HTM_FILENAME)) {
+      // We will, for improved backward-compatibility with existing packages, add a
+      // reference to the file welcome.htm is it is present in the package. This allows
+      // newer tools to avoid knowing about welcome.htm, if we assume that they work with
+      // packages compiled with kmc-package (17.0+) and not kmcomp (5.x-16.x).
+      data.options.welcomeFile = WELCOME_HTM_FILENAME;
+    }
+
     if(data.options.msiFilename) {
       data.options.msiFilename = this.callbacks.path.basename(data.options.msiFilename);
     }

developer/src/kmc-package/test/fixtures/khmer_angkor/ref/kmp.json

@@ -5,7 +5,8 @@
   },
   "options": {
     "readmeFile": "readme.htm",
-    "graphicFile": "splash.gif"
+    "graphicFile": "splash.gif",
+    "welcomeFile": "welcome.htm"
   },
   "info": {
     "name": {

developer/src/kmc-package/test/fixtures/khmer_angkor/source/khmer_angkor.kps

@@ -8,6 +8,7 @@
     <ExecuteProgram></ExecuteProgram>
     <ReadMeFile>readme.htm</ReadMeFile>
     <GraphicFile>splash.gif</GraphicFile>
+    <WelcomeFile>welcome.htm</WelcomeFile>
     <MSIFileName></MSIFileName>
     <MSIOptions></MSIOptions>
     <FollowKeyboardVersion/>