You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: csdb/v4.16/docs/collection-format.html
+78-64Lines changed: 78 additions & 64 deletions
Original file line number
Diff line number
Diff line change
@@ -4,7 +4,7 @@
4
4
* This file copyright (C) 2020, Peter Johnson (gravatar.com/delphidabbler) and
5
5
* is licensed under the MIT License: https://opensource.org/licenses/MIT
6
6
*
7
-
* DelphiDabbler Code Snippets Database Documentation: Collection file format
7
+
* DelphiDabbler Code Snippets Database Documentation: Collection file format
8
8
* documentation.
9
9
-->
10
10
<htmllang="en">
@@ -63,7 +63,7 @@
63
63
</li>
64
64
</ul>
65
65
</nav>
66
-
66
+
67
67
</header>
68
68
69
69
<sectionid="intro">
@@ -84,11 +84,14 @@ <h1>
84
84
<p>
85
85
All the files are plain text, encoded in UTF-8 format with UTF-8 preamble (BOM).
86
86
</p>
87
-
87
+
<p>
88
+
All files are located in the same directory.
89
+
</p>
90
+
88
91
</section>
89
92
90
93
<sectionid="meta">
91
-
94
+
92
95
<h1>
93
96
Meta Data Files
94
97
</h1>
@@ -101,10 +104,10 @@ <h1>
101
104
<code>categories.ini</code> lists the categories contained in the collection.
102
105
</li>
103
106
<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.
<p>The sections in these files are named with identifiers that uniquely identify a snippet. This <spanclass="very-strong">must</span> be a valid Unicode Pascal identifier. The keys in a section have the following purpose:</p>
191
194
<dl>
192
195
<dt>
@@ -289,12 +292,26 @@ <h2>
289
292
Text string containing any additional comments about the snippet. Optional. Ignored if a non-empty <codeclass="key">Extra</code> key is present.
290
293
</p>
291
294
</dd>
295
+
<dt>
296
+
<codeclass="key">Extra</code>
297
+
</dt>
298
+
<dd>
299
+
<p>
300
+
Optional. Provides extra information about the snippet. When present the value <spanclass="very-strong">must</span> be a valid string of REML<sup><ahref="#footnote-1">1</a></sup> code.
301
+
</p>
302
+
<p>
303
+
If omitted the extra information is generated from the values of any <codeclass="key">Comments</code>, <codeclass="key">Credits</code> and <codeclass="key">Credits_URL</code> keys.
304
+
</p>
305
+
<p>
306
+
When <codeclass="key">Extra</code> has a non-empty value the <codeclass="key">Comments</code>, <codeclass="key">Credits</code> and <codeclass="key">Credits_URL</code> keys are ignored.
307
+
</p>
308
+
</dd>
292
309
<dt>
293
310
<codeclass="key">DelphiXXX</code> & <codeclass="key">FPC</code>
294
311
</dt>
295
312
<dd>
296
313
<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:
<li><codeclass="value">Q</code> – compilation result unknown</li>
331
348
</ul>
332
349
<p>
333
-
If any of the above compilers is not present, the compile result is assumed to be <codeclass="value">Q</code>. A compile result of <codeclass="value">W</code> is obsolete and treated as if it were <codeclass="value">Y</code>.
334
-
</p>
335
-
</dd>
336
-
<dt>
337
-
<codeclass="key">Extra</code>
338
-
</dt>
339
-
<dd>
340
-
<p>
341
-
Optional. Provides extra information about the snippet. When present the value <spanclass="very-strong">must</span> be a valid string of REML<sup><ahref="#footnote-1">1</a></sup> code.
342
-
</p>
343
-
<p>
344
-
If omitted the extra information is generated from the values of any <codeclass="key">Comments</code>, <codeclass="key">Credits</code> and <codeclass="key">Credits_URL</code> keys.
345
-
</p>
346
-
<p>
347
-
When <codeclass="key">Extra</code> has a non-empty value the <codeclass="key">Comments</code>, <codeclass="key">Credits</code> and <codeclass="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 <codeclass="value">Q</code>.
348
351
</p>
349
352
</dd>
350
353
<dt>
@@ -363,7 +366,7 @@ <h2>
363
366
<li><codeclass="value">unit</code> – a complete Pascal unit.</li>
364
367
</ul>
365
368
<p>
366
-
If <codeclass="key">kind</code> is not present then its value defaults to <codeclass="value">freeform</code>.
369
+
If <codeclass="key">Kind</code> is not present then its value defaults to <codeclass="value">freeform</code>.
367
370
</p>
368
371
</dd>
369
372
<dt>
@@ -385,25 +388,25 @@ <h2>
385
388
<dt>
386
389
</dl>
387
390
<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.
389
392
</p>
390
393
<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.
392
395
</p>
393
396
394
-
397
+
395
398
</section>
396
399
397
400
<sectionid="source-code">
398
401
399
402
<h1>
400
403
Source Code Files
401
404
</h1>
402
-
405
+
403
406
<p>
404
407
There is a separate source code file for each snippet. These file names <spanclass="very-strong">must</span> be named exactly as specified in the related category <code>.ini</code> file's <codeclass="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.
405
408
</p>
406
-
409
+
407
410
</section>
408
411
409
412
<sectionid="credits">
@@ -423,27 +426,27 @@ <h1>
423
426
<p>
424
427
The files may be empty if there are no contributors and/or testers, but they <spanclass="very-strong">must</span> be present.
425
428
</p>
426
-
429
+
427
430
<p>
428
431
The credits files are not referenced by, and do not reference, any of the other files in the collection.
429
432
</p>
430
-
433
+
431
434
</section>
432
435
433
436
<sectionid="license">
434
437
435
438
<h1>
436
439
License File
437
440
</h1>
438
-
441
+
439
442
<p>
440
443
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.
441
444
</p>
442
445
443
446
<h2>
444
447
Full License Text
445
448
</h2>
446
-
449
+
447
450
<p>
448
451
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.
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. <codeclass="value">MIT License</code> or <codeclass="value">Mozilla Public License 2.0</code>.
483
486
</p>
484
487
</dd>
485
488
<dt>
486
489
<codeclass="key">LicenseSPDX</code>
487
490
</dt>
488
491
<dd>
489
492
<p>
490
-
The Open Source Initiative (OSI) SPDX short identifier of the license, if any. E.g. <codeclass="value">MIT</code> or <codeclass="value">MPL-2.0</code>. If the license does not have a SPDX identifier this key <spanclass="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. <codeclass="value">MIT</code> or <codeclass="value">MPL-2.0</code>. If the license does not have a SPDX identifier this key <spanclass="very-strong">must</span> either be omitted or be empty.
491
494
</p>
492
495
<p>
493
496
For a list of OSI licenses with their SPDXs see <ahref="https://opensource.org/licenses/alphabetical"
The date of the copyright or range of copyright dates as plain text. E.g. <codeclass="value">2020</code> or <codeclass="value">2005-2020</code>.
513
+
The year of the copyright or range of years as plain text. E.g. <codeclass="value">2020</code> or <codeclass="value">2005-2020</code>.
511
514
</p>
512
515
</dd>
513
516
<dt>
514
517
<codeclass="key">CopyrightHolder</code>
515
518
</dt>
516
519
<dd>
517
520
<p>
518
-
The name of the copyright holder as plain text. Where there are contributors either list them all or append <codeclass="value">and contributors</code><sup><ahref="#footnote-3">3</a></sup> to the primary copyright holder's name. E.g. <codeclass="value">Joe Bloggs</code> or <codeclass="value">Annie Smith, Joe Bloggs and Jessie Sharp</code> or <codeclass="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 <codeclass="value">and contributors</code><sup><ahref="#footnote-3">3</a></sup> to the primary copyright holder's name. E.g.:
522
+
</p>
523
+
<ulclass="unspaced">
524
+
<li>
525
+
<codeclass="value">Joe Bloggs</code>;
526
+
</li>
527
+
<li>
528
+
<codeclass="value">Annie Smith, Joe Bloggs and Jessie Sharp</code>;
529
+
</li>
530
+
<li>
531
+
<codeclass="value">Annie Smith and Contributors</code>.
532
+
</li>
519
533
</p>
520
534
</dd>
521
535
<dt>
@@ -539,7 +553,7 @@ <h2>
539
553
<h1>
540
554
Version Information File
541
555
</h1>
542
-
556
+
543
557
<p>
544
558
There is a plain UTF-8 text file named <code>VERSION</code> that contains the version number of the database in the form <codeclass="value">vX.X.X</code>. where <codeclass="value">X</code> represents a non-negative integer. The file is <spanclass="very-strong">required</span> and <spanclass="very-strong">must</span> be non-empty.
545
559
</p>
@@ -555,7 +569,7 @@ <h1>
555
569
<p>
556
570
The <code>VERSION</code> file is not referenced by, and does not reference, any of the other files in the collection.
0 commit comments