Merge tag 'v2.0.0' into develop

First v2 release

Author: delphidabbler

csdb/CHANGELOG.md

@@ -1,13 +1,45 @@
 # Changelog
 
-This is the change log for the _DelphiDabbler Code Snippets Database_ collection starting with version 2.
+This is the change log for the _DelphiDabbler Code Snippets Database_ collection.
 
-All notable changes to this project will be documented in this file.
+From v2.0.0 all notable changes to this project will be documented in this file.
+
+> No change log was kept for version 1 of the collection.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-> No change log was kept for version 1 of the collection.
+## v2.0.0 of 2020/05/02
+
+Initial release of v2 of the collection.
 
-## v2.0.0 of 2020/xx/xx
+### Changes since last v1 release
 
-* Initial release of v2 of the collection.
+* Removed any code that restricted use of the collection to _[DelphiDabbler CodeSnip](https://github.com/delphidabbler/codesnip)_. The collection can now be used by 3rd party applications.
+    * Removed backwards compatibility with _CodeSnip_ v4.15.1 and earlier.
+    * Removed conditionally included code and _CodeSnip_ version dependent code from category .ini files.
+    * Merged multiple versions of category .ini files down into a single file. (These multiple file were used to hide some categories from earlier versions of _CodeSnip_).
+    * Removed duplicated, _CodeSnip_ version dependent, source code files: used a copy of the most recent version and removed version specifiers from the file names.
+* Rationalised and corrected errors in category .ini files:
+    * Condensed two string management categories into one.
+    * Removed `Desc` keys where they duplicated `DescEx` keys.
+    * Removed some duplicate `Credits` and `Comments` keys.
+    * Removed some empty keys.
+    * Fixed or removed some broken web links.
+    * Rephrased some descriptive text.
+* Changed layout of category .ini files and `categories.ini`:
+    * Re-ordered sections of `categories.ini` in alphabetic order.
+    * Removed all explanatory comments: there were inconsistencies.
+    * Added header comments, including copyright and licensing information, to all .ini files.
+* File format changes:
+    * Removed the `StandardFormat` key from the specification of category .ini files.
+    * Added requirements for `LICENSE`, `LICENSE_INFO` and `VERSION` files and added suitable files to the collection.
+    * Changed the required name for the contributors and testers files to `CONTRIBUTORS` and `TESTERS` respectively. Renamed the existing `contrib.txt` and `testers.txt` files accordingly.
+    * Made support for REML v4 an official requirement.
+    * Dropped support for conditional inclusion of code in .ini files.
+* Added documentation:
+    * Of the collection file format.
+    * A read-me file.
+    * This change log.
+* Ensured that all files in the collection use the UTF-8 text file preamble (aka byte order mark).
+* Added a shell script to create releases.
+* Officially adopted the MIT license for source code files.

csdb/MakeRelease.sh

@@ -1,14 +1,19 @@
 #!/bin/bash
 
 # --------------------------------------------------------------------------
+# DelphiDabbler Code Snippets Database v2
 #
 # Build tool for Windows to package up files ready for release.
 #
+# This file is licensed under the MIT license, copyright © 2020 Peter Johnson,
+# https://gravatar.com/delphidabbler
+#
+#
 # Two packages are made, each in a zip file: one containing the collection and
 # the other containing documentation. Both zip files are written to the
 # _release sub-folder in the collection's home directory.
 #
-# Any pre-existing _release sub-folder is deleted before the zip files are
+# Any pre-existing _release sub-folder is cleared before the zip files are
 # created.
 #
 # Requirements:
@@ -23,17 +28,18 @@
 
 VERSION=$1
 RELEASE_DIR="./_release"
-RELEASE_FILE_PREFIX="csdb-v"
-COLLECTION_ZIP_FILE="${RELEASE_DIR}/${RELEASE_FILE_PREFIX}${VERSION}.zip"
-DOCS_ZIP_FILE="${RELEASE_DIR}/${RELEASE_FILE_PREFIX}${VERSION}-docs.zip"
+RELEASE_FILE_STUB="${RELEASE_DIR}/csdb-v${VERSION}"
+
+COLLECTION_ZIP_FILE="${RELEASE_FILE_STUB}-data.zip"
+DOCS_ZIP_FILE="${RELEASE_FILE_STUB}-docs.zip"
 
 echo Creating CSDB release $1
 echo
 
 rm -rf $RELEASE_DIR || true
 mkdir $RELEASE_DIR
 
-echo Zipping collection
+echo Zipping data
 zip -j -q $COLLECTION_ZIP_FILE ./collection/*
 
 echo Zipping documentation

csdb/README.md

@@ -8,28 +8,35 @@ All of the snippets have been tested: some received basic testing while others h
 
 ## History
 
-Version 1 was designed exclusively for use with _DelphiDabbler [CodeSnip](https://github.com/delphidabbler/codesnip)_ and was downloaded by the program directly from a web service on DelphiDabbler.com.
+Version 1 was designed exclusively for use with _DelphiDabbler [CodeSnip](https://github.com/delphidabbler/codesnip)_ (v4.15.1 and earlier) and was downloaded by the program directly from a web service on DelphiDabbler.com.
 
-Version 2 is designed to be able to be used by other applications in addition to _CodeSnip_. This version is **not** backwards compatible with version 1.
+Version 2 is designed to be able to be used by other applications in addition to _CodeSnip_ (v4.16.0 or later). This version is **not** backwards compatible with version 1.
 
 ## Using the Collection
 
-When used with _CodeSnip_, v4.16.0 or later is required.
+Anyone is welcome to write applications or web pages that access the snippets in the collection, subject to the terms of the license (see below). You should read the collection's documentation which explains the file format in detail.
 
-Anyone is welcome to write applications or web pages that access the snippets in the collection. You should read the collection's documentation which explains the file format in detail.
-
-> **WARNING:** Implementors must not read the collection data directly from this GitHub repository - that could generate more than the permitted amount of traffic. Instead you must download a release from the _Releases_ tab and either distribute the collection with the application or host it on a web server.
+> **WARNING:** Implementors **must not** read the collection data directly from this GitHub repository - that could generate more than the permitted amount of traffic. Instead you must download a release from the _Releases_ tab and either distribute the collection with the application or host it on a web server.
 
 ## Documentation
 
 The collection data format is fully documented in the file `collection-format.html` in the `docs` directory.
 
+## Releases
+
+Releases can be found on the `releases` tab on the GitHub project page.
+
+Each release comprises two zip files, as follows (replace `X.Y.X` in the file names with the release version number):
+
+  * `csdb-vX.Y.Z-data.zip` - Contains all the data in the collection. Required by applications that access the collection.
+  * `csdb-vX.Y.Z-docs.zip` - Contains the documentation developers need to understand the structure of the data.
+
 ## Change Log
 
 The project's change log can be found in `CHANGELOG.md` in the collection's base directory.
 
 ## License
 
-All snippets in this collection are licensed under the MIT license **unless** the snippet contains contrary licensing information in its source code file, in which case that license applies to that snippet only.
+All snippets in this collection (stored in `.dat` files in the `collections` directory) are licensed under the MIT license and are copyright © 2005-2020, [Peter Johnson](https://gravatar.com/delphidabbler) and Contributors. The full license and a list of contributors can be found in the `LICENSE` and `CONTRIBUTORS` files in the `collection` sub-directory.
 
-Full details can be found in the `LICENSE` file in the `collection` sub-directory.
+All other files in this project are licensed under the MIT license and are copyright © 2020, [Peter Johnson](https://gravatar.com/delphidabbler).

csdb/collection/LICENSE

@@ -1,7 +1,4 @@
-All snippets in this collection are licensed under the MIT license (see below) UNLESS the snippet contains contrary licensing information in its source code file, in which case that license applies to that snippet only.
-
-MIT License
------------
+All snippets in this collection are licensed under the MIT license.
 
 >> Begin license text
 

csdb/collection/arrays.ini

@@ -1,4 +1,11 @@
-[ArrayToStringList]
+# DelphiDabbler Code Snippets Database v2
+#
+# Arrays category file
+#
+# This file is licensed under the MIT license, copyright © 2020 Peter Johnson,
+# https://gravatar.com/delphidabbler
+
+[ArrayToStringList]
 DescEx="<p>Copies the elements of string array <var>Strings</var> to string list <var>SL</var>, replacing any existing contents of <var>SL</var>.</p>"
 SeeAlso=StringListToArray
 Units=Classes
@@ -132,8 +139,6 @@ DelphiXE4=Y
 Delphi10S=Y
 FPC=Y
 
-# from arrays.3.ini
-
 [AppendByteArray]
 DescEx="Appends array of bytes <var>B2</var> to the end of byte array <var>B1</var>."
 Depends=TBytes
@@ -342,8 +347,6 @@ DelphiXE4=Y
 Delphi10S=Y
 FPC=Y
 
-# from arrays.4.ini
-
 [TArrayUtils]
 Kind=class
 Desc="A method-only advanced record that provides utility methods for working with generic dynamic arrays."

csdb/collection/categories.ini

@@ -1,7 +1,18 @@
-[arrays]
+# DelphiDabbler Code Snippets Database v2
+#
+# Master categories file
+#
+# This file is licensed under the MIT license, copyright © 2020 Peter Johnson,
+# https://gravatar.com/delphidabbler
+
+[arrays]
 Desc=Arrays
 Ini=arrays.ini
 
+[consts]
+Desc=Constants
+Ini=consts.ini
+
 [date]
 Desc=Date and Time
 Ini=date.ini
@@ -14,10 +25,6 @@ Ini=drive.ini
 Desc=Encoding
 Ini=encoding.ini
 
-[io]
-Desc=File and Stream I/O
-Ini=io.ini
-
 [file]
 Desc=File Management
 Ini=file.ini
@@ -30,9 +37,9 @@ Ini=graphics.ini
 Desc=Hex Utilities
 Ini=hex.ini
 
-[web]
-Desc=Internet
-Ini=web.ini
+[io]
+Desc=File and Stream I/O
+Ini=io.ini
 
 [maths]
 Desc=Mathematics
@@ -46,48 +53,42 @@ Ini=multimedia.ini
 Desc=Registry
 Ini=registry.ini
 
-[string-1]
-Desc=String Management (A..M)
-Ini=string-am.ini
+[shell]
+Desc=Windows Shell
+Ini=shell.ini
+
+[string]
+Desc=String Management
+Ini=string.ini
 
-[string-2]
-Desc=String Management (N..Z)
-Ini=string-nz.ini
+[structs]
+Desc="Structures"
+Ini=structs.ini
 
 [system]
 Desc=System
 Ini=sys.ini
 
+[types]
+Desc=Types
+Ini=types.ini
+
 [util]
 Desc=Utilities
 Ini=utils.ini
 
+[wb]
+Desc="TWebBrowser"
+Ini=wb.ini
+
+[web]
+Desc=Internet
+Ini=web.ini
+
 [win]
 Desc=Windows
 Ini=windows.ini
 
-[shell]
-Desc=Windows Shell
-Ini=shell.ini
-
 [winsys]
 Desc=Windows System
 Ini=winsys.ini
-
-# from categories.3.ini
-
-[consts]
-Desc=Constants
-Ini=consts.ini
-
-[structs]
-Desc="Structures"
-Ini=structs.ini
-
-[types]
-Desc=Types
-Ini=types.ini
-
-[wb]
-Desc="TWebBrowser"
-Ini=wb.ini

csdb/collection/consts.ini

@@ -1,4 +1,9 @@
-# from consts.3.ini
+# DelphiDabbler Code Snippets Database v2
+#
+# Constants category file
+#
+# This file is licensed under the MIT license, copyright © 2020 Peter Johnson,
+# https://gravatar.com/delphidabbler
 
 [SHIL_Enum]
 Kind=const

csdb/collection/date.ini

@@ -1,4 +1,11 @@
-[AddDays]
+# DelphiDabbler Code Snippets Database v2
+#
+# Date and Time category file
+#
+# This file is licensed under the MIT license, copyright © 2020 Peter Johnson,
+# https://gravatar.com/delphidabbler
+
+[AddDays]
 DescEx="<p>Adds the number of days, <var>Days</var>, to the given date, <var>DateTime</var> and returns the result.</p><p>To subtract days, pass a negative value for <var>Days</var>.</p>"
 Credits="Contributed by Bill Miller."
 SeeAlso=DiffDays
@@ -1030,8 +1037,6 @@ DelphiXE4=Y
 Delphi10S=Y
 FPC=Y
 
-# from date.3.ini
-
 [GMTToLocalTime]
 DescEx="<p>Converts the given <var>TDateTime</var> value <var>GMTTime</var> from GMT (UTC) to local time.</p><p>Raises an exception if <var>GMTTime</var> is not valid or can't be converted.</p>"
 Extra="<p><warning>Warning:</warning> This routine requires the Windows NT platform (NT, 2000, XP, Vista etc).</p>"

csdb/collection/drive.ini

@@ -1,4 +1,11 @@
-[CurentDrive]
+# DelphiDabbler Code Snippets Database v2
+#
+# Drive Management category file
+#
+# This file is licensed under the MIT license, copyright © 2020 Peter Johnson,
+# https://gravatar.com/delphidabbler
+
+[CurentDrive]
 Desc="Returns the letter that identifies the current drive."
 Credits="Modified from Bill Miller's snippets collection."
 Snip=352.dat
@@ -135,8 +142,6 @@ DelphiXE4=Y
 Delphi10S=Y
 FPC=Y
 
-# from drive.3.ini
-
 [DeleteVolumeName]
 Desc="Deletes an existing volume label on a given drive. Returns True on success and False on failure."
 Extra="<p><warning>Note:</warning> Fails and returns False if the process has insufficient privileges to set the volume name.</p>"

csdb/collection/encoding.ini

@@ -1,4 +1,11 @@
-[BytesToAnsiString]
+# DelphiDabbler Code Snippets Database v2
+#
+# Encoding category file
+#
+# This file is licensed under the MIT license, copyright © 2020 Peter Johnson,
+# https://gravatar.com/delphidabbler
+
+[BytesToAnsiString]
 DescEx="Converts the given array of bytes to an ANSI raw byte string, which is returned. The returned string has the code page specified by <var>CodePage</var>."
 Credits="Based on code from the Stack Overflow posting [How can I convert TBytes to RawByteString?]."
 Credits_URL="http://stackoverflow.com/questions/773297/how-can-i-convert-tbytes-to-rawbytestring"
@@ -325,8 +332,6 @@ DelphiXE4=Y
 Delphi10S=Y
 FPC=Y
 
-# from encoding.3.ini
-
 [IsASCIIFile]
 DescEx="<p>Checks if file the named by <var>FileName</var> is a valid ASCII text file.</p><p><var>BytesToCheck</var> determines the number of bytes of the file that are to be checked. Specify 0 (the default) to check the whole file.</p><p>The file is read in chunks of <var>BufSize</var> bytes. If this parameter is omitted, the buffer size defaults to 8Kb.</p>"
 Extra="<p>It is possible, but unlikely, that an ASCII file could actually be encoded in UTF-7. This is a 7 bit encoding and therefore uses only valid ASCII characters. You can check for this encoding using the <var>IsUTF7File</var> snippet.</p>"

csdb/collection/file.ini

@@ -1,4 +1,11 @@
-[CopyFile]
+# DelphiDabbler Code Snippets Database v2
+#
+# File Management category file
+#
+# This file is licensed under the MIT license, copyright © 2020 Peter Johnson,
+# https://gravatar.com/delphidabbler
+
+[CopyFile]
 DescEx="Copies <var>Source</var> file to <var>Dest</var> file, preserving modification date."
 Units=Classes,SysUtils
 SeeAlso=CopyFiles
@@ -773,8 +780,6 @@ DelphiXE4=Y
 Delphi10S=Y
 FPC=Y
 
-# from file.3.ini
-
 [CountFiles]
 DescEx="<p>Returns the number of files in the folder specified by <var>APath</var> that match the DOS style wildcard <var>AWildCard</var>.</p><p>Any sub-directories of <var>APath</var> and the files they contain are not counted.</p>"
 Extra="<p>Slightly modified routine from Bill Miller's snippets collection.</p>"