Make the collection's specification more useful to 3rd party users

[delphidabbler]

The collection format defined by docs/collection-format.html was originally designed to describe the rule applying to the code-snippets collection only.

However, the format is now being used within CodeSnip Vault, which is planned to become the next major release of CodeSnip. It has been found that the current specification is too specialised for this more general use. The following changes to the spec are proposed to make it more useful for general use:

• Make snippet descriptions optional in category files. Keep Desc deprecated, but make DescEx optional.
• Add a new, ACKNOWLEDGEMENTS file that takes a list of acknowledgements. This is similar to CONTRIBUTORS and TESTERS but is much more general than TESTERS. This file could be optional.
• Clarify the rules for the LICENSE-INFO. Currently the file is not stated to be compulsory, but if it is present the LicenseName, CopyrightDate and CopyrightHolder keys must have values. This makes no sense.
• Permit the LICENSE file to be empty.
• Make it easier to detect this collection format by implementing issue Add a new compulsory file that identifies DCSC format collections #65.
• Implement the LastModifed key per issue Add a "last modified" field to each snippet #67.

None of these suggestions will break backward compatibility.

It is no problem for this collection to make these rules stricter providing the spec is followed. For example an Implementation Notes section could make it clear that, while DescEx is optional, it always has a value in the collection.

[delphidabbler]

All the changes needed to make the "database" more open without breaking backwards compatibility are too unwieldy.

This really needs to get a major version bump.

[delphidabbler]

• Make snippet descriptions optional in category files. Keep Desc deprecated, but make DescEx optional.

Since we're going for a major release, we can finally get rid of the two different versions of the description and just have the one.

To make the format more useful to 3rd parties we could have the following two fields:

1. Desc - contains the snippet description.

2. DescFormat - specifies the format use for the description in Desc. This could be one of, say:

   • text - plain text
   • reml5 - REML format, v5 support
   • reml6 - REML format, v6 support
   • html5 - HTML5 format
   • rtf - Rich text format

   To be the most friendly, the default should probably be text, but that will mean that every entry in the DCSC will have to have DescFormat=reml6 for every snippet.

[delphidabbler]

To be the most friendly, the default [for DescFormat] should probably be text, but that will mean that every entry in the DCSC will have to have DescFormat=reml6 for every snippet.

A possible solution would be to introduce a new defaults or config file that specifies the default values for some keys that applies collection wide. For example:

[Defaults]
DateFormat=reml6
Kind=freeform
...

[delphidabbler]

DescFormat - specifies the format use for the description in Desc. This could be one of, say:

• text - plain text
• reml5 - REML format, v5 support
• reml6 - REML format, v6 support
• html5 - HTML5 format
• rtf - Rich text format

If all these possible formats are to be supported then it's asking a lot of any program that can access the collection to be able to display all of them.

Therefore it would be sensible to expose the formats that a collection uses in a requirements file. A program would then be able to check the requirements and refuse to load the collection if it can't support the formats.

We could also bring back the concept of duplicate descriptions where the main Desc field contains formatted text and a second (DescAlt??), optional, field provides the plain text alternative.

If the requirements file was an ini file then it could look something like:

[requirements]
TextFormats=text,reml5,reml6
HasDescAlt=false

We could combine this file with the other proposed defaults file into a single config file.

[delphidabbler]

• Add a new, ACKNOWLEDGEMENTS file that takes a list of acknowledgements. This is similar to CONTRIBUTORS and TESTERS but is much more general than TESTERS. This file could be optional.
• Clarify the rules for the LICENSE-INFO. Currently the file is not stated to be compulsory, but if it is present the LicenseName, CopyrightDate and CopyrightHolder keys must have values. This makes no sense.
• Permit the LICENSE file to be empty.

Moving to v3 gives the opportunity to clear up the whole mess of the LICENSE-INFO, LICENSE, TESTERS & CONTRIBUTORS files and the possible new ACKNOWLEDGEMENTS file.

The contents of LICENSE-INFO could be changed as follows:

LicenseName=<human-readable-name>
LicenseSPDX=<code-name>
LicenseURL=<url>
LicenseFile=<file-name>🆕
CopyrightDate=<date-range>
CopyrightHolder=<name>
CopyrightHolderURL=<url>
ContributorsFile=<file-name>🆕
AcknowledgementsFile=<file-name>🆕

Nothing has been removed from the v2 file. The three additional keys are as follows:

• LicenseFile - The name of a file containing the full license text. Normally either LicenseFile or LicenseURL would be used, but not both. If both are used then the documents should have the same content. This gets rid of the required for the LICENSE file to be part of the specification. Any referenced file MUST exist & MUST be UTF8 plain text.

• ContributorsFile - The name of any contributors who share the copyright. MUST be present if CopyrightHolder references "and contributors" or similar. Otherwise MAY be present. The referenced file MUST exist. The file MUST be a simple list of names, one per line in UTF8 plain text.

• AcknowledgementsFile - A text file containing any other acknowledgements. Optional. Any referenced file MUST exist and be plain text in UTF8. May EITHER be a simple list of names OR be structured with one or more title lines followed by a non-empty list of names. Title lines would be identified by a leading # followed by one or more spaces before the title text. Leading spaces MUST be stripped from lines, so it would be possible to indent names. Empty lines will also be stripped.

NOTE: The above removes the need for a TESTERS file, however when porting from v2 to v3 the file could be arranged by adding AcknowledgementsFile=TESTERS to LICENSE-INFO, and optionally adding a title line to TESTERS and identing all the names. For example, a v2 TESTERS file:

Alice
Bob
Cara
Dave

could be changed to:

# The following people helped to test the snippets:
    Alice
    Bob
    Cara
    Dave

We could rename LICENSE-INFO something like LEGAL to reflect its broadened purpose.