Merge branch 'release/4.26.0'

Release v4.26.0

Author: delphidabbler

CHANGELOG.md

@@ -6,6 +6,40 @@ 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.26.0 of 02 May 2025
+
+* Updated the dialogue box displayed when saving units and annotated source code [issue #166]:
+  * The _File Encoding_ drop down list control is disabled if there is only one encoding option.
+  * Updated and clarified the naming of encodings in the _File Encoding_ drop down list.
+  * The sole encoding option displayed for the _Rich text file_ file type was changed from the erroneous ANSI to the correct ASCII.
+* Fixed bug where, when ANSI encoding was selected in the _Save Unit_ and _Save Annotated Source_ dialogue boxes, snippets containing characters not supported in the default locale's code page were being rendered diffently in the Preview dialogue box to when saved to file [issue #164]. The previewed code is now the same as that of the saved source code.
+* Updated file formats available when the _File | Save Snippet Information_ menu option is selected:
+  * Syntax highlighting of the existing RTF format output is now optional.
+  * Added the option to save snippet information in the following new formats:
+    * Plain text, in UTF-8, UTF-16LE, UTF-16BE and the system locale's default ANSI code page. [issue #162]
+    * HMTL 5 with optional syntax highlighting, in UTF-8 format [issue #153].
+    * XHTML with optional syntax highlighting, in UTF-8 format [issue #153].
+    * Markdown, in UTF-8, UTF-16LE, UTF-16BE and the system locale's default ANSI code page [issue #155].
+  * Changed the _Save Snippet Information_ dialogue box: 
+    * It is now based on that used for saving unit and annotated source code in that file encoding and snippet highlighting can be customised where relevant, although the _Comment style_ controls are disabled since they are not relevant.
+    * The suggested file name was changed from "SnippetInfo" to the display name of the selected snippet.
+    * The dialogue box caption now contains the display name of the selected snippet.
+* Changed the title of the _Save Annotated Source_ dialogue box when displaying snippets.
+* Added option to prevent descriptive comments from appearing in the implementation section of generated units. A check box for this option has been added to the _Code Formatting_ tab of the _Preferences_ dialogue box [issue #85].
+* The _Help | CodeSnip News Blog_ menu item was changed to link to the [DelphiDabbler Blog](https://delphidabbler.blogspot.com/) instead of the CodeSnip Blog, because the latter is to be closed down. The menu item was renamed to _Help | CodeSnip News On DelphiDabbler Blog_ [issue #161].
+* Improved how the CSS used in generated HTML 5 and XHTML files is generated:
+  * The ordering of CSS selectors can now be pre-determined.
+  * CSS lengths and sizes can now be specified in units, such as `em`, instead of just pixels.
+* Refactored the `USourceGen` unit to remove an unnecessary dependency on user preferences [issue #167].
+* Updated the help file: 
+  * Re changes when saving snippet information [issue #163].
+  * Re changes to the _Save Unit_ and _Save Annotated Source_ dialogue boxes.
+  * Re changes to the blog linked from the _Help_ menu.
+  * Re the new option to inhibit comments in the implementation sections of generated units.
+* Updated documentation: 
+  * File format documentation was changed re the addition of the Markdown file format and the changes to the encodings used in saved files.
+  * Read-me files were updated re the change of news blog.
+
 ## 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].
@@ -15,7 +49,7 @@ Releases are listed in reverse version number order.
 * 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].
+  * 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].

Docs/Design/FileFormats/config.html

@@ -167,7 +167,7 @@ <h3>
 </p>
 
 <p>
-  There have been several versions of this file. The current one is version 19. The change to version 19 came with CodeSnip v4.21.0 and the addition of the [Compilers] section and the <code class="key">CanAutoInstall</code> key in the [Cmp:XXX] sections.
+  There have been several versions of this file. The current one is version 20. The change to version 20 came with CodeSnip v4.26.0 and the addition of the <code class="key">UseCommentsInUnitImpl</code> key in the <code>[Prefs:SourceCode]</code> section.
 </p>
 
 <p>
@@ -771,7 +771,7 @@ <h4>
       The version number of the config file. Incremented whenever the file format changes. If this section or this value is missing then the default value is <code class="value">1</code>.
     </div>
     <div class="half-spaced">
-      The current value is <code class="value">19</code>.
+      The current value is <code class="value">20</code>.
     </div>
   </dd>
   <dt>
@@ -1262,6 +1262,12 @@ <h4>
   <dd>
     Flag indicating whether multi-paragraph snippet descriptions are to be truncated to the first paragraph only in documentation comments. <code class="value">True</code> &rArr; truncate the description; <code class="value">False</code> &rArr; use the full description.
   </dd>
+  <dt>
+    <code class="key">UseCommentsInUnitImpl</code> (Boolean)
+  </dt>
+  <dd>
+    Flag indicating whether source code comments are repeated in a generated unit's implementation section. <code class="value">True</code> &rArr; emit comments in both the interface and implementation sections; <code class="value">False</code> &rArr; emit comments in the interface section only.
+  </dd>
   <dt>
     <code class="key">UseSyntaxHiliting</code> (Boolean)
   </dt>

Docs/Design/FileFormats/saved.html

@@ -51,20 +51,38 @@ <h2>
 
 <ol>
   <li>
-    By saving snippet information to file from the <em>File | Save Snippet Information</em> menu option.
+    By saving snippet information using the <em>File | Save Snippet Information</em> menu option.
   </li>
   <li>
-    By saving snippets to file from the <em>File | Save Snippet</em> menu option.
+    By saving snippets using the <em>File | Save Snippet</em> menu option.
   </li>
   <li>
-    By saving units to file from the <em>File | Save Unit</em> menu option.
+    By saving units using the <em>File | Save Unit</em> menu option.
   </li>
 </ol>
 
 <p>
-  In the first case the snippet is always saved in rich text format.
+  In the first case the snippet information can be saved as one of the following file types:
 </p>
 
+<ul>
+  <li>
+    Plain text.
+  </li>
+  <li>
+    HTML 5 files.
+  </li>
+  <li>
+    XHTML files.
+  </li>
+  <li>
+    Rich text files.
+  </li>
+  <li>
+    Markdown files.
+  </li>
+</ul>
+
 <p>
   In the second two cases the following file types can be chosen by the user:
 </p>
@@ -88,7 +106,7 @@ <h2>
 </ul>
 
 <p>
-  There is no specific file format for these files, except that HTML 5, XHTML and RTF
+  There is no specific file format for these files, except that HTML 5, XHTML, RTF and Markdown
   files conform to published specifications.
 </p>
 
@@ -97,11 +115,7 @@ <h2>
 </h2>
 
 <p>
-  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
+  The available encodings depend on the file type and user choice. Different file
   types have different encoding choices, as follows:
 </p>
 
@@ -118,10 +132,10 @@ <h2>
         UTF-8
       </li>
       <li>
-        Unicode little endian (UTF16-LE)
+        UTF-16LE
       </li>
       <li>
-        Unicode big endian (UTF16-BE)
+        UTF-16BE
       </li>
     </ul>
   </dd>
@@ -164,7 +178,26 @@ <h2>
   <dd>
     <ul class="squashed">
       <li>
-        ANSI (system default code page). ASCII format is actually used.
+        ASCII
+      </li>
+    </ul>
+  </dd>
+  <dt>
+    Markdown
+  </dt>
+  <dd>
+    <ul class="squashed">
+      <li>
+        ANSI (system default code page)
+      </li>
+      <li>
+        UTF-8
+      </li>
+      <li>
+        UTF-16LE
+      </li>
+      <li>
+        UTF-16BE
       </li>
     </ul>
   </dd>

Docs/ReadMe-portable.txt

@@ -144,8 +144,8 @@ Updating the Program
 Updates are published on GitHub. See
 https://github.com/delphidabbler/codesnip/releases
 
-News of new updates is published on the CodeSnip Blog:
-https://codesnip-app.blogspot.com/.
+News of new updates is published on the DelphiDabbler Blog:
+https://delphidabbler.blogspot.com/.
 
 
 Known Installation and Upgrading Issues
@@ -248,6 +248,9 @@ Thanks to:
 + The authors of the third party source code and images used by the program. See
   the program's about box or License.html for details.
 
++ SirRufo for helping to fix a long standing bug where CodeSnip would crash on
+  resuming from hibernation.
+
 + Various contributors to the DelphiDabbler Code Snippets database. Names of
   contributors are listed in the program's About Box (use the "Help | About"
   menu option then select the "About the Database" tab). The list will be empty

Docs/ReadMe-standard.txt

@@ -179,8 +179,8 @@ Updating the Program
 Updates are published on GitHub. See
 https://github.com/delphidabbler/codesnip/releases
 
-News of new updates is published on the CodeSnip Blog:
-https://codesnip-app.blogspot.com/.
+News of new updates is published on the DelphiDabbler Blog:
+https://delphidabbler.blogspot.com/.
 
 
 Known Installation and Upgrading Issues
@@ -293,6 +293,9 @@ Thanks to:
 + geoffsmith82 and an anonymous contributor for information about getting
   CodeSnip to work with Delphi XE2.
 
++ SirRufo for helping to fix a long standing bug where CodeSnip would crash on
+  resuming from hibernation.
+
 + The authors of the third party source code and images used by the program. See
   the program's about box or License.html for details.
 

README.md

@@ -35,7 +35,7 @@ The following support is available to CodeSnip users:
 * A comprehensive help file.
 * A read-me file that discusses installation, configuration, updating and known issues. There are different versions of this file for each edition of CodeSnip: one for the [standard edition](https://raw.githubusercontent.com/delphidabbler/codesnip/master/Docs/ReadMe-standard.txt) and another for the [portable edition](https://raw.githubusercontent.com/delphidabbler/codesnip/master/Docs/ReadMe-portable.txt). [^1]
 * The [Using CodeSnip FAQ](https://github.com/delphidabbler/codesnip-faq/blob/master/UsingCodeSnip.md).
-* The [CodeSnip Blog](https://codesnip-app.blogspot.co.uk/).
+* The [DelphiDabbler Blog](https://delphidabbler.blogspot.co.uk/) that provides CodeSnip news.
 * CodeSnip's own [Web Page](https://delphidabbler.com/software/codesnip).
 
 There's also plenty of info available on how to compile CodeSnip from source - see below.

Src/ActiveText.UHTMLRenderer.pas

@@ -65,6 +65,7 @@       TCSSStyles = class(TObject)
       fTagInfoMap: TTagInfoMap;
       fIsStartOfTextLine: Boolean;
       fLINestingDepth: Cardinal;
+      fTagGen: THTMLClass;
     const
       IndentMult = 2;
     procedure InitialiseTagInfoMap;
@@ -73,7 +74,7 @@       TCSSStyles = class(TObject)
     function MakeOpeningTag(const Elem: IActiveTextActionElem): string;
     function MakeClosingTag(const Elem: IActiveTextActionElem): string;
   public
-    constructor Create;
+    constructor Create(const ATagGenerator: THTMLClass = nil);
     destructor Destroy; override;
     function Render(ActiveText: IActiveText): string;
   end;
@@ -87,13 +88,18 @@ implementation
 
 { TActiveTextHTML }
 
-constructor TActiveTextHTML.Create;
+constructor TActiveTextHTML.Create(const ATagGenerator: THTMLClass);
 begin
   inherited Create;
   fCSSStyles := TCSSStyles.Create;
   fBuilder := TStringBuilder.Create;
   fLINestingDepth := 0;
   InitialiseTagInfoMap;
+  if not Assigned(ATagGenerator) then
+    // default behaviour before ATagGenerator parameter was added
+    fTagGen := TXHTML
+  else
+    fTagGen := ATagGenerator;
 end;
 
 destructor TActiveTextHTML.Destroy;
@@ -145,7 +151,7 @@ procedure TActiveTextHTML.InitialiseTagInfoMap;
 function TActiveTextHTML.MakeClosingTag(const Elem: IActiveTextActionElem):
   string;
 begin
-  Result := TXHTML.ClosingTag(fTagInfoMap[Elem.Kind].Name);
+  Result := fTagGen.ClosingTag(fTagInfoMap[Elem.Kind].Name);
 end;
 
 function TActiveTextHTML.MakeOpeningTag(const Elem: IActiveTextActionElem):
@@ -160,7 +166,7 @@ function TActiveTextHTML.MakeOpeningTag(const Elem: IActiveTextActionElem):
       Attrs := THTMLAttributes.Create;
     Attrs.Add('class', fCSSStyles.ElemClasses[Elem.Kind])
   end;
-  Result := TXHTML.OpeningTag(fTagInfoMap[Elem.Kind].Name, Attrs);
+  Result := fTagGen.OpeningTag(fTagInfoMap[Elem.Kind].Name, Attrs);
 end;
 
 function TActiveTextHTML.Render(ActiveText: IActiveText): string;
@@ -242,7 +248,7 @@ function TActiveTextHTML.RenderText(const TextElem: IActiveTextTextElem):
   end
   else
     Result := '';
-  Result := Result + TXHTML.Entities(TextElem.Text);
+  Result := Result + fTagGen.Entities(TextElem.Text);
 end;
 
 { TActiveTextHTML.TCSSStyles }