Skip to content

Commit c6aa404

Browse files
author
delphidabbler
committed
Clarify and correct collection documentation
1 parent 18b2cfb commit c6aa404

File tree

1 file changed

+78
-64
lines changed

1 file changed

+78
-64
lines changed

csdb/v4.16/docs/collection-format.html

Lines changed: 78 additions & 64 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
* This file copyright (C) 2020, Peter Johnson (gravatar.com/delphidabbler) and
55
* is licensed under the MIT License: https://opensource.org/licenses/MIT
66
*
7-
* DelphiDabbler Code Snippets Database Documentation: Collection file format
7+
* DelphiDabbler Code Snippets Database Documentation: Collection file format
88
* documentation.
99
-->
1010
<html lang="en">
@@ -63,7 +63,7 @@
6363
</li>
6464
</ul>
6565
</nav>
66-
66+
6767
</header>
6868

6969
<section id="intro">
@@ -84,11 +84,14 @@ <h1>
8484
<p>
8585
All the files are plain text, encoded in UTF-8 format with UTF-8 preamble (BOM).
8686
</p>
87-
87+
<p>
88+
All files are located in the same directory.
89+
</p>
90+
8891
</section>
8992

9093
<section id="meta">
91-
94+
9295
<h1>
9396
Meta Data Files
9497
</h1>
@@ -101,10 +104,10 @@ <h1>
101104
<code>categories.ini</code> lists the categories contained in the collection.
102105
</li>
103106
<li>
104-
A set of further <code>.ini</code> files, one for each category specified in <code>categories.ini</code>. Each of these files contains numerous details of each snippet along with the name of the file containing the source code.
107+
A set of further <code>.ini</code> files, one for each category specified in <code>categories.ini</code>. Each of these files contains numerous details of each snippet along with the name of the file containing its source code.
105108
</li>
106109
</ol>
107-
110+
108111
<h2>
109112
Format Of <code>categories.ini</code>
110113
</h2>
@@ -162,31 +165,31 @@ <h2>
162165
Credits=&lt;credits-text&gt;
163166
Credits_URL=&lt;url-used-in-credits&gt;
164167
Comments=&lt;comments-text&gt;
165-
Delphi2=&lt;Y|N|Q|W&gt;
166-
Delphi3=&lt;Y|N|Q|W&gt;
167-
Delphi4=&lt;Y|N|Q|W&gt;
168-
Delphi5=&lt;Y|N|Q|W&gt;
169-
Delphi6=&lt;Y|N|Q|W&gt;
170-
Delphi7=&lt;Y|N|Q|W&gt;
171-
Delphi2005Win32=&lt;Y|N|Q|W&gt;
172-
Delphi2006Win32=&lt;Y|N|Q|W&gt;
173-
Delphi2007=&lt;Y|N|Q|W&gt;
174-
Delphi2009Win32=&lt;Y|N|Q|W&gt;
175-
Delphi2010=&lt;Y|N|Q|W&gt;
176-
DelphiXE=&lt;Y|N|Q|W&gt;
177-
DelphiXE2=&lt;Y|N|Q|W&gt;
178-
DelphiXE3=&lt;Y|N|Q|W&gt;
179-
DelphiXE4=&lt;Y|N|Q|W&gt;
180-
DelphiXE5=&lt;Y|N|Q|W&gt;
181-
DelphiXE6=&lt;Y|N|Q|W&gt;
182-
DelphiXE7=&lt;Y|N|Q|W&gt;
183-
DelphiXE8=&lt;Y|N|Q|W&gt;
184-
Delphi10S=&lt;Y|N|Q|W&gt;
185-
Delphi101B=&lt;Y|N|Q|W&gt;
186-
FPC=&lt;Y|N|Q|W&gt;
168+
Delphi2=&lt;&quot;Y&quot;|&quot;N&quot;|&quot;Q&quot;|&quot;W&quot;&gt;
169+
Delphi3=&lt;&quot;Y&quot;|&quot;N&quot;|&quot;Q&quot;|&quot;W&quot;&gt;
170+
Delphi4=&lt;&quot;Y&quot;|&quot;N&quot;|&quot;Q&quot;|&quot;W&quot;&gt;
171+
Delphi5=&lt;&quot;Y&quot;|&quot;N&quot;|&quot;Q&quot;|&quot;W&quot;&gt;
172+
Delphi6=&lt;&quot;Y&quot;|&quot;N&quot;|&quot;Q&quot;|&quot;W&quot;&gt;
173+
Delphi7=&lt;&quot;Y&quot;|&quot;N&quot;|&quot;Q&quot;|&quot;W&quot;&gt;
174+
Delphi2005Win32=&lt;&quot;Y&quot;|&quot;N&quot;|&quot;Q&quot;|&quot;W&quot;&gt;
175+
Delphi2006Win32=&lt;&quot;Y&quot;|&quot;N&quot;|&quot;Q&quot;|&quot;W&quot;&gt;
176+
Delphi2007=&lt;&quot;Y&quot;|&quot;N&quot;|&quot;Q&quot;|&quot;W&quot;&gt;
177+
Delphi2009Win32=&lt;&quot;Y&quot;|&quot;N&quot;|&quot;Q&quot;|&quot;W&quot;&gt;
178+
Delphi2010=&lt;&quot;Y&quot;|&quot;N&quot;|&quot;Q&quot;|&quot;W&quot;&gt;
179+
DelphiXE=&lt;&quot;Y&quot;|&quot;N&quot;|&quot;Q&quot;|&quot;W&quot;&gt;
180+
DelphiXE2=&lt;&quot;Y&quot;|&quot;N&quot;|&quot;Q&quot;|&quot;W&quot;&gt;
181+
DelphiXE3=&lt;&quot;Y&quot;|&quot;N&quot;|&quot;Q&quot;|&quot;W&quot;&gt;
182+
DelphiXE4=&lt;&quot;Y&quot;|&quot;N&quot;|&quot;Q&quot;|&quot;W&quot;&gt;
183+
DelphiXE5=&lt;&quot;Y&quot;|&quot;N&quot;|&quot;Q&quot;|&quot;W&quot;&gt;
184+
DelphiXE6=&lt;&quot;Y&quot;|&quot;N&quot;|&quot;Q&quot;|&quot;W&quot;&gt;
185+
DelphiXE7=&lt;&quot;Y&quot;|&quot;N&quot;|&quot;Q&quot;|&quot;W&quot;&gt;
186+
DelphiXE8=&lt;&quot;Y&quot;|&quot;N&quot;|&quot;Q&quot;|&quot;W&quot;&gt;
187+
Delphi10S=&lt;&quot;Y&quot;|&quot;N&quot;|&quot;Q&quot;|&quot;W&quot;&gt;
188+
Delphi101B=&lt;&quot;Y&quot;|&quot;N&quot;|&quot;Q&quot;|&quot;W&quot;&gt;
189+
FPC=&lt;&quot;Y&quot;|&quot;N&quot;|&quot;Q&quot;|&quot;W&quot;&gt;
187190
Extra=&lt;extra-info-REML&gt;
188-
Kind=&lt;freeform|routine|type|const|class|unit&gt;
189-
TestInfo=&lt;none|basic|advanced&gt;</pre>
191+
Kind=&lt;&quot;freeform&quot;|&quot;routine&quot;|&quot;type&quot;|&quot;const&quot;|&quot;class&quot;|&quot;unit&quot;&gt;
192+
TestInfo=&lt;&quot;none&quot;|&quot;basic&quot;|&quot;advanced&quot;&gt;</pre>
190193
<p>The sections in these files are named with identifiers that uniquely identify a snippet. This <span class="very-strong">must</span> be a valid Unicode Pascal identifier. The keys in a section have the following purpose:</p>
191194
<dl>
192195
<dt>
@@ -289,12 +292,26 @@ <h2>
289292
Text string containing any additional comments about the snippet. Optional. Ignored if a non-empty <code class="key">Extra</code> key is present.
290293
</p>
291294
</dd>
295+
<dt>
296+
<code class="key">Extra</code>
297+
</dt>
298+
<dd>
299+
<p>
300+
Optional. Provides extra information about the snippet. When present the value <span class="very-strong">must</span> be a valid string of REML<sup><a href="#footnote-1">1</a></sup> code.
301+
</p>
302+
<p>
303+
If omitted the extra information is generated from the values of any <code class="key">Comments</code>, <code class="key">Credits</code> and <code class="key">Credits_URL</code> keys.
304+
</p>
305+
<p>
306+
When <code class="key">Extra</code> has a non-empty value the <code class="key">Comments</code>, <code class="key">Credits</code> and <code class="key">Credits_URL</code> keys are ignored.
307+
</p>
308+
</dd>
292309
<dt>
293310
<code class="key">DelphiXXX</code> &amp; <code class="key">FPC</code>
294311
</dt>
295312
<dd>
296313
<p>
297-
This related group of keys describe compilation results for the snippets on various compilers. Valid key names are:
314+
This related group of keys describe the results of compiling the snippet with various compilers. The key name identifies the compiler. Valid key names are:
298315
</p>
299316
<ul class="unspaced">
300317
<li><code class="key">Delphi2</code> – Delphi 2 compiler</li>
@@ -330,21 +347,7 @@ <h2>
330347
<li><code class="value">Q</code> – compilation result unknown</li>
331348
</ul>
332349
<p>
333-
If any of the above compilers is not present, the compile result is assumed to be <code class="value">Q</code>. A compile result of <code class="value">W</code> is obsolete and treated as if it were <code class="value">Y</code>.
334-
</p>
335-
</dd>
336-
<dt>
337-
<code class="key">Extra</code>
338-
</dt>
339-
<dd>
340-
<p>
341-
Optional. Provides extra information about the snippet. When present the value <span class="very-strong">must</span> be a valid string of REML<sup><a href="#footnote-1">1</a></sup> code.
342-
</p>
343-
<p>
344-
If omitted the extra information is generated from the values of any <code class="key">Comments</code>, <code class="key">Credits</code> and <code class="key">Credits_URL</code> keys.
345-
</p>
346-
<p>
347-
When <code class="key">Extra</code> has a non-empty value the <code class="key">Comments</code>, <code class="key">Credits</code> and <code class="key">Credits_URL</code> keys are ignored.
350+
If any of the above compiler keys is not present, the compile result for the associated compiler is assumed to be <code class="value">Q</code>.
348351
</p>
349352
</dd>
350353
<dt>
@@ -363,7 +366,7 @@ <h2>
363366
<li><code class="value">unit</code> – a complete Pascal unit.</li>
364367
</ul>
365368
<p>
366-
If <code class="key">kind</code> is not present then its value defaults to <code class="value">freeform</code>.
369+
If <code class="key">Kind</code> is not present then its value defaults to <code class="value">freeform</code>.
367370
</p>
368371
</dd>
369372
<dt>
@@ -385,25 +388,25 @@ <h2>
385388
<dt>
386389
</dl>
387390
<p>
388-
The format is quite messy, with several keys having similar or overlapping purposes. This has happened because new features have been added over time while preserving backward compatibility.
391+
The format is quite messy, with several keys having similar or overlapping purposes. This has happened because new keys have been added over time while preserving backward compatibility.
389392
</p>
390393
<p>
391-
Backwards compatibility with older formats has now been dropped, but to save development time some of the old style values have been retained. However some duplication of keys has been removed.
394+
Backwards compatibility with older file formats has now been dropped, but to save development time some of the old style values have been retained. However some duplication of keys has been removed from the collection.
392395
</p>
393396

394-
397+
395398
</section>
396399

397400
<section id="source-code">
398401

399402
<h1>
400403
Source Code Files
401404
</h1>
402-
405+
403406
<p>
404407
There is a separate source code file for each snippet. These file names <span class="very-strong">must</span> be named exactly as specified in the related category <code>.ini</code> file's <code class="key">Snip</code> key. They are usually numbered from <code>001</code> and have a <code>.dat</code> extension, but this is not a requirement.
405408
</p>
406-
409+
407410
</section>
408411

409412
<section id="credits">
@@ -423,27 +426,27 @@ <h1>
423426
<p>
424427
The files may be empty if there are no contributors and/or testers, but they <span class="very-strong">must</span> be present.
425428
</p>
426-
429+
427430
<p>
428431
The credits files are not referenced by, and do not reference, any of the other files in the collection.
429432
</p>
430-
433+
431434
</section>
432435

433436
<section id="license">
434437

435438
<h1>
436439
License File
437440
</h1>
438-
441+
439442
<p>
440443
There are two files relating to license (and copyright) information: the full text of the license in human readable format and a file providing machine readable meta data about the license and copyright.
441444
</p>
442445

443446
<h2>
444447
Full License Text
445448
</h2>
446-
449+
447450
<p>
448451
This is a plain UTF-8 text file named <code>LICENSE</code> that contains the license that applies to the source code in the collection.
449452
</p>
@@ -463,7 +466,7 @@ <h2>
463466
</p>
464467

465468
<pre class="sample">LicenseName=&lt;human-readable-name&gt;
466-
LicenseSPDX=&lt;code&gt;
469+
LicenseSPDX=&lt;code-name&gt;
467470
LicenseURL=&lt;url&gt;
468471
CopyrightDate=&lt;date-range&gt;
469472
CopyrightHolder=&lt;name&gt;
@@ -479,19 +482,19 @@ <h2>
479482
</dt>
480483
<dd>
481484
<p>
482-
The name of the license as plain text. E.g. <code>MIT License</code> or <code>Mozilla Public License 2.0</code>.
485+
The name of the license as plain text. E.g. <code class="value">MIT License</code> or <code class="value">Mozilla Public License 2.0</code>.
483486
</p>
484487
</dd>
485488
<dt>
486489
<code class="key">LicenseSPDX</code>
487490
</dt>
488491
<dd>
489492
<p>
490-
The Open Source Initiative (OSI) SPDX short identifier of the license, if any. E.g. <code class="value">MIT</code> or <code class="value">MPL-2.0</code>. If the license does not have a SPDX identifier this key <span class="very-strong">must</span> either be omitted or be empty.
493+
The Open Source Initiative (OSI) SPDX short identifier of the license, if any. E.g. <code class="value">MIT</code> or <code class="value">MPL-2.0</code>. If the license does not have a SPDX identifier this key <span class="very-strong">must</span> either be omitted or be empty.
491494
</p>
492495
<p>
493496
For a list of OSI licenses with their SPDXs see <a href="https://opensource.org/licenses/alphabetical"
494-
>https://opensource.org/licenses/alphabetical</a>.
497+
>https://opensource.org/licenses/alphabetical</a>.
495498
</p>
496499
</dd>
497500
<dt>
@@ -507,15 +510,26 @@ <h2>
507510
</dt>
508511
<dd>
509512
<p>
510-
The date of the copyright or range of copyright dates as plain text. E.g. <code class="value">2020</code> or <code class="value">2005-2020</code>.
513+
The year of the copyright or range of years as plain text. E.g. <code class="value">2020</code> or <code class="value">2005-2020</code>.
511514
</p>
512515
</dd>
513516
<dt>
514517
<code class="key">CopyrightHolder</code>
515518
</dt>
516519
<dd>
517520
<p>
518-
The name of the copyright holder as plain text. Where there are contributors either list them all or append <code class="value">and contributors</code><sup><a href="#footnote-3">3</a></sup> to the primary copyright holder's name. E.g. <code class="value">Joe Bloggs</code> or <code class="value">Annie Smith, Joe Bloggs and Jessie Sharp</code> or <code class="value">Annie Smith and Contributors</code>.
521+
The name of the copyright holder as plain text. Where there are contributors either list them all or append <code class="value">and contributors</code><sup><a href="#footnote-3">3</a></sup> to the primary copyright holder's name. E.g.:
522+
</p>
523+
<ul class="unspaced">
524+
<li>
525+
<code class="value">Joe Bloggs</code>;
526+
</li>
527+
<li>
528+
<code class="value">Annie Smith, Joe Bloggs and Jessie Sharp</code>;
529+
</li>
530+
<li>
531+
<code class="value">Annie Smith and Contributors</code>.
532+
</li>
519533
</p>
520534
</dd>
521535
<dt>
@@ -539,7 +553,7 @@ <h2>
539553
<h1>
540554
Version Information File
541555
</h1>
542-
556+
543557
<p>
544558
There is a plain UTF-8 text file named <code>VERSION</code> that contains the version number of the database in the form <code class="value">vX.X.X</code>. where <code class="value">X</code> represents a non-negative integer. The file is <span class="very-strong">required</span> and <span class="very-strong">must</span> be non-empty.
545559
</p>
@@ -555,7 +569,7 @@ <h1>
555569
<p>
556570
The <code>VERSION</code> file is not referenced by, and does not reference, any of the other files in the collection.
557571
</p>
558-
572+
559573
</section>
560574

561575
<footer>

0 commit comments

Comments
 (0)