Merge branch 'release/4.25.0'

Release v4.25.0

Author: delphidabbler

Diff for: CHANGELOG.md

@@ -6,6 +6,23 @@ Releases are listed in reverse version number order.
 
 > Note that _CodeSnip_ v4 was developed in parallel with v3 for a while. As a consequence some v3 releases have later release dates than early v4 releases.
 
+## Release v4.25.0 of 19 April 2025
+
+* Added new feature to save snippet information to file in RTF format using the new _File | Save Snippet Information_ menu option [issue #140].
+* Added the option to save optionally highlighted annotated source code and units in HTML 5 format [issue #87]. 
+* Fixed malformed bullet character(s) in the list of imported snippets on the last page of the Snippets Import Wizard dialogue box [issue #147].
+* Improved the solution to the crash after hibernation bug, initially fixed in v4.24.1 and v4.24.2, with much improved and more stable code [issue #158]. Implemented by [@SirRufo](https://github.com/SirRufo). 
+* Overhauled rich text format processing:
+  * Fixed bug where Unicode characters that don't exist in the system code page were not being displayed correctly [issue #157].
+  * Fixed potential bug where some reserved ASCII characters may not be escaped properly [issue #159].
+  * Refactored and improved the rich text handling code [issue #100].
+* Corrected the copyright date displayed in the About Box to include 2025 [issue #149].
+* Documentation changes:
+  * Fixed error in the export file formation documentation and related help topic [issue #151].
+  * Corrected erroneous comments for the _TREMLEntities.MapToEntity_ method [issue #84].
+  * Updated file format documentation with details the changes introduced when implementing issues #87 and #140.
+  * Updated the help file with details of the new features added in this release.
+
 ## Release v4.24.2 of 14 April 2025
 
 Hotfix release.
@@ -16,7 +33,7 @@ Hotfix release.
 ## Release v4.24.1 of 13 April 2025
 
 * Fixed bug where CodeSnip occasionally crashes after a computer resumes from hibernation [issue #70].
-* Bumped some copyright dates for 2025.
+* Updated license copyright dates for 2025.
 
 ## Release v4.24.0 of 23 October 2024
 

Diff for: Docs/Design/FileFormats/export.html

@@ -5,7 +5,7 @@
  * v. 2.0. If a copy of the MPL was not distributed with this file, You can
  * obtain one at https://mozilla.org/MPL/2.0/
  *
- * Copyright (C) 2012-2024, Peter Johnson (gravatar.com/delphidabbler).
+ * Copyright (C) 2012-2025, Peter Johnson (gravatar.com/delphidabbler).
  *
  * CodeSnip File Format Documentation: Export
 -->
@@ -57,6 +57,9 @@ <h2>
   <li>
     <a href="#file-format">File Format</a>
   </li>
+  <li>
+    <a href="#erratum">Erratum</a>
+  </li>
   <li>
     <a href="#changelog">Change Log</a>
   </li>
@@ -114,8 +117,8 @@ <h2>
 </h2>
 
 <p>
-  There have been seven different versions of the XML export file format &ndash; v1 to
-  v7. Tags used by all versions are explained below, with notes describing
+  There have been eight different versions of the XML export file format &ndash; v1 to
+  v8. Tags used by all versions are explained below, with notes describing
   which versions a tag applies to. Where there is no note the tag is valid in
   all versions.
 </p>
@@ -176,7 +179,7 @@ <h2>
       </dt>
       <dd>
         Identifies major version of file. Determines which tags are valid and
-        establishes rules concerning content. Valid versions are 1 to 7.
+        establishes rules concerning content. Valid versions are 1 to 8.
       </dd>
     </dl>
   </dd>
@@ -198,7 +201,7 @@ <h2>
         <span class="highlight">versions 1 to 6:</span> Contains information about user who created the file &nbsp; used for submissions to the online database, omitted for other exports.
       </li>
       <li>
-        <span class="highlight">version 7:</span> Not supported. Ignored if present.
+        <span class="highlight">version 7 and later:</span> Not supported. Ignored if present.
       </li>
     </ul>
   </dd>
@@ -212,7 +215,7 @@ <h2>
         <span class="highlight">versions 1 to 6:</span> User's name or nickname.
       </li>
       <li>
-        <span class="highlight">version 7:</span> Not supported. Ignored if present.
+        <span class="highlight">version 7 and later:</span> Not supported. Ignored if present.
       </li>
     </ul>
   </dd>
@@ -226,7 +229,7 @@ <h2>
         <span class="highlight">versions 1 to 6:</span> User's email address.
       </li>
       <li>
-        <span class="highlight">version 7:</span> Not supported. Ignored if present.
+        <span class="highlight">version 7 and later:</span> Not supported. Ignored if present.
       </li>
     </ul>
   </dd>
@@ -240,7 +243,7 @@ <h2>
         <span class="highlight">versions 1 to 6:</span> Any comments provided by user.
       </li>
       <li>
-        <span class="highlight">version 7:</span> Not supported. Ignored if present.
+        <span class="highlight">version 7 and later:</span> Not supported. Ignored if present.
       </li>
     </ul>
   </dd>
@@ -687,33 +690,21 @@ <h2>
     </ul>
   </dd>
 
-  <dt>
-    <strong>codesnip-export/routines/routine/xref</strong>
-  </dt>
-  <dd>
-    List of cross-referenced snippets.
-  </dd>
+</section>
 
-  <dt>
-    <strong>codesnip-export/routines/routine/xref/pascal-name</strong>
-  </dt>
-  <dd>
-    <div class="half-spaced">
-      Name of a snippet within cross-reference list.
-    </div>
-    <ul class="squashed">
-      <li>
-        <span class="highlight">versions 1 to 4:</span> Name must begin with an
-        English language letter or the underscore.
-      </li>
-      <li>
-        <span class="highlight">version 5 and later:</span> Name can begin with
-        any character that is valid as the first character of a Unicode Pascal
-        identifier.
-      </li>
-    </ul>
-  </dd>
-</dl>
+<section id="erratum">
+
+<h2>
+  Erratum
+</h2>
+
+<p>
+  The <em>codesnip-export/routines/routine/xref</em> and <em>codesnip-export/routines/routine/xref/pascal-name</em> tags were included in versions 1 to 7 of this specification in error. XRefs were never intended to be written to export files by any version of CodeSnip, as source code comments make clear.
+</p>
+
+<p>
+  These tags have been removed from this document entirely of specification version 8.
+</p>
 
 </section>
 
@@ -1008,6 +999,18 @@ <h2>
       </dd>
     </dl>
   </dd>
+
+  <dt>
+    <strong>Version 8 - 15 April 2025</strong>
+  </dt>
+  <dd>
+    <p>
+      Introduced with CodeSnip v4.24.3.
+    </p>
+    <p>
+      The <em>codesnip-export/routines/routine/xref</em> and <em>codesnip-export/routines/routine/xref/pascal-name</em> tags were removed from the specification. See <a href="#erratum">Erratum</a> above for details.
+    </p>
+  </dd>
 </dl>
 
 </section>
@@ -1058,6 +1061,10 @@ <h2>
   Readers of v2 files and later can parse REML as v6, since all versions of REML up to v6 are backwards compatible.
 </p>
 
+<p>
+  Readers of v1 to v7 files must ignore any <em>codesnip-export/routines/routine/xref</em> tags and sub tags in the unlikely event that they are found. For an explanation see <a href="#erratum">Erratum</a> above.
+</p>
+
 </section>
 
 </body>

Diff for: Docs/Design/FileFormats/saved.html

@@ -5,7 +5,7 @@
  * v. 2.0. If a copy of the MPL was not distributed with this file, You can
  * obtain one at https://mozilla.org/MPL/2.0/
  *
- * Copyright (C) 2012-2021, Peter Johnson (gravatar.com/delphidabbler).
+ * Copyright (C) 2012-2025, Peter Johnson (gravatar.com/delphidabbler).
  *
  * CodeSnip File Format Documentation: Saved Files
 -->
@@ -46,20 +46,27 @@ <h2>
 </h2>
 
 <p>
-  CodeSnip saves external files in two different ways:
+  CodeSnip saves external files in three different ways:
 </p>
 
 <ol>
   <li>
-    By saving snippets to file from the <em>File | Save Snippet</em> menu.
+    By saving snippet information to file from the <em>File | Save Snippet Information</em> menu option.
   </li>
   <li>
-    By saving units to file from the <em>File | Save Unit</em> menu.
+    By saving snippets to file from the <em>File | Save Snippet</em> menu option.
+  </li>
+  <li>
+    By saving units to file from the <em>File | Save Unit</em> menu option.
   </li>
 </ol>
 
 <p>
-  In each case the following file types can be chosen by the user:
+  In the first case the snippet is always saved in rich text format.
+</p>
+
+<p>
+  In the second two cases the following file types can be chosen by the user:
 </p>
 
 <ul>
@@ -69,6 +76,9 @@ <h2>
   <li>
     Pascal source files (either .inc or .pas files).
   </li>
+  <li>
+    HTML 5 files.
+  </li>
   <li>
     XHTML files.
   </li>
@@ -78,7 +88,7 @@ <h2>
 </ul>
 
 <p>
-  There is no specific file format for these files, except that XHTML and RTF
+  There is no specific file format for these files, except that HTML 5, XHTML and RTF
   files conform to published specifications.
 </p>
 
@@ -87,7 +97,11 @@ <h2>
 </h2>
 
 <p>
-  The encodings used depend on the file type and user choice. Different file
+  In the first case the RTF is always saved in ASCII format.
+</p>
+
+<p>
+  In the 2nd and 3rd cases the encodings used depend on the file type and user choice. Different file
   types have different encoding choices, as follows:
 </p>
 
@@ -124,6 +138,16 @@ <h2>
       </li>
     </ul>
   </dd>
+  <dt>
+    HTML 5 files
+  </dt>
+  <dd>
+    <ul class="squashed">
+      <li>
+        UTF-8
+      </li>
+    </ul>
+  </dd>
   <dt>
     XHTML files
   </dt>
@@ -140,7 +164,7 @@ <h2>
   <dd>
     <ul class="squashed">
       <li>
-        ANSI (system default code page)
+        ANSI (system default code page). ASCII format is actually used.
       </li>
     </ul>
   </dd>

Diff for: Src/ActiveText.UHTMLRenderer.pas

@@ -3,7 +3,7 @@
  * v. 2.0. If a copy of the MPL was not distributed with this file, You can
  * obtain one at https://mozilla.org/MPL/2.0/
  *
- * Copyright (C) 2009-2023, Peter Johnson (gravatar.com/delphidabbler).
+ * Copyright (C) 2009-2025, Peter Johnson (gravatar.com/delphidabbler).
  *
  * Provides a class that renders active text as HTML.
 }
@@ -145,7 +145,7 @@ procedure TActiveTextHTML.InitialiseTagInfoMap;
 function TActiveTextHTML.MakeClosingTag(const Elem: IActiveTextActionElem):
   string;
 begin
-  Result := THTML.ClosingTag(fTagInfoMap[Elem.Kind].Name);
+  Result := TXHTML.ClosingTag(fTagInfoMap[Elem.Kind].Name);
 end;
 
 function TActiveTextHTML.MakeOpeningTag(const Elem: IActiveTextActionElem):
@@ -160,7 +160,7 @@ function TActiveTextHTML.MakeOpeningTag(const Elem: IActiveTextActionElem):
       Attrs := THTMLAttributes.Create;
     Attrs.Add('class', fCSSStyles.ElemClasses[Elem.Kind])
   end;
-  Result := THTML.OpeningTag(fTagInfoMap[Elem.Kind].Name, Attrs);
+  Result := TXHTML.OpeningTag(fTagInfoMap[Elem.Kind].Name, Attrs);
 end;
 
 function TActiveTextHTML.Render(ActiveText: IActiveText): string;
@@ -242,7 +242,7 @@ function TActiveTextHTML.RenderText(const TextElem: IActiveTextTextElem):
   end
   else
     Result := '';
-  Result := Result + THTML.Entities(TextElem.Text);
+  Result := Result + TXHTML.Entities(TextElem.Text);
 end;
 
 { TActiveTextHTML.TCSSStyles }

Diff for: Src/Browser.UHighlighter.pas

@@ -3,7 +3,7 @@
  * v. 2.0. If a copy of the MPL was not distributed with this file, You can
  * obtain one at https://mozilla.org/MPL/2.0/
  *
- * Copyright (C) 2005-2021, Peter Johnson (gravatar.com/delphidabbler).
+ * Copyright (C) 2005-2025, Peter Johnson (gravatar.com/delphidabbler).
  *
  * Class that highlights text in web browser that match a search criteria.
 }
@@ -194,7 +194,7 @@ function TWBHighlighter.HighlightWord(const Word: string;
     begin
       // Apply highlight to found text by spanning it with highlight style
       SpanAttrs := THTMLAttributes.Create('style', fHighLightStyle);
-      Range.pasteHTML(THTML.CompoundTag('span', SpanAttrs, Range.htmlText));
+      Range.pasteHTML(TXHTML.CompoundTag('span', SpanAttrs, Range.htmlText));
       Inc(Result);
     end
     else

Diff for: Src/ClassHelpers.RichEdit.pas

@@ -0,0 +1,53 @@
+{
+ * This Source Code Form is subject to the terms of the Mozilla Public License,
+ * v. 2.0. If a copy of the MPL was not distributed with this file, You can
+ * obtain one at https://mozilla.org/MPL/2.0/
+ *
+ * Copyright (C) 2025, Peter Johnson (gravatar.com/delphidabbler).
+ *
+ * Class helper for TRichEdit.
+}
+
+unit ClassHelpers.RichEdit;
+
+interface
+
+uses
+  // Delphi
+  ComCtrls,
+  // Project
+  URTFUtils;
+
+type
+  TRichEditHelper = class helper for TRichEdit
+  public
+    procedure Load(const ARTFMarkup: TRTFMarkup);
+  end;
+
+implementation
+
+uses
+  // Delphi
+  SysUtils,
+  Classes;
+
+{ TRichEditHelper }
+
+procedure TRichEditHelper.Load(const ARTFMarkup: TRTFMarkup);
+var
+  Stream: TStream;
+begin
+  PlainText := False;
+  Stream := TMemoryStream.Create;
+  try
+    ARTFMarkup.ToStream(Stream);
+    Stream.Position := 0;
+    // must set MaxLength or long documents may not display
+    MaxLength := Stream.Size;
+    Lines.LoadFromStream(Stream, TEncoding.ASCII);
+  finally
+    Stream.Free;
+  end;
+end;
+
+end.