Skip to content

Commit c7706d5

Browse files
delphidabblerdelphidabbler
committed
Revise docs re collection v2.1.0 changes
Changes were: * DescEx now required * Desc, Comments, Comments_URL and Credits tags now deprecated
1 parent cbdb9b0 commit c7706d5

File tree

1 file changed

+70
-10
lines changed

1 file changed

+70
-10
lines changed

‎csdb/docs/collection-format.html

Lines changed: 70 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -156,16 +156,16 @@ <h2 id="category-ini">
156156
</p>
157157
<pre class="sample">[snippet-name]
158158
DisplayName=&lt;snippet-display-name&gt;
159-
Desc=&lt;description-text&gt;
159+
Desc=&lt;description-text&gt; *
160160
DescEx=&lt;description-REML&gt;
161161
Snip=&lt;snippet-file-name&gt;
162162
Units=&lt;required-units&gt;
163163
Depends=&lt;required-snippets&gt;
164164
SeeAlso=&lt;cross-referenced-snippets&gt;
165165
Extra=&lt;extra-info-REML&gt;
166-
Credits=&lt;credits-text&gt;
167-
Credits_URL=&lt;url-used-in-credits&gt;
168-
Comments=&lt;comments-text&gt;
166+
Credits=&lt;credits-text&gt; *
167+
Credits_URL=&lt;url-used-in-credits&gt; *
168+
Comments=&lt;comments-text&gt; *
169169
Delphi2=&lt;&quot;Y&quot;|&quot;N&quot;|&quot;Q&quot;|&quot;W&quot;&gt;
170170
Delphi3=&lt;&quot;Y&quot;|&quot;N&quot;|&quot;Q&quot;|&quot;W&quot;&gt;
171171
Delphi4=&lt;&quot;Y&quot;|&quot;N&quot;|&quot;Q&quot;|&quot;W&quot;&gt;
@@ -190,6 +190,11 @@ <h2 id="category-ini">
190190
FPC=&lt;&quot;Y&quot;|&quot;N&quot;|&quot;Q&quot;|&quot;W&quot;&gt;
191191
Kind=&lt;&quot;freeform&quot;|&quot;routine&quot;|&quot;type&quot;|&quot;const&quot;|&quot;class&quot;|&quot;unit&quot;&gt;
192192
TestInfo=&lt;&quot;none&quot;|&quot;basic&quot;|&quot;advanced&quot;&gt;</pre>
193+
<aside>
194+
<p>
195+
<strong>NOTE:</strong> As of v2.1.0 keys marked with an asterisk (*) are deprecated and are no longer used in the Code Snippets Database collection.
196+
</p>
197+
</aside>
193198
<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>
194199
<dl>
195200
<dt>
@@ -207,22 +212,44 @@ <h2 id="category-ini">
207212
<code class="key">Desc</code>
208213
</dt>
209214
<dd>
215+
<aside>
216+
<p>
217+
<span class="very-strong">Deprecated as of v2.1.0</span>: use <code class="key">DescEx</code> instead.
218+
</p>
219+
<p>
220+
v2.1.0 conformant collections <span class="very-strong">must not</span> use this key.
221+
</p>
222+
<p>
223+
Software <span class="very-strong">must</span> ignore this key when parsing v2.1.0 conformant collections.
224+
</p>
225+
</aside>
210226
<p>
211227
Description of the snippet as plain text.
212228
</p>
213229
<p>
214-
<code class="key">Desc</code> is ignored if a non-empty <code class="key">DescEx</code> key is present. At least one of the <code class="key">Desc</code> or <code class="key">DescEx</code> keys are <span class="very-strong">required</span> to be present and non-empty.
230+
For v2.0.x only, <code class="key">Desc</code> is ignored if a non-empty <code class="key">DescEx</code> key is present. At least one of the <code class="key">Desc</code> or <code class="key">DescEx</code> keys are <span class="very-strong">required</span> to be present and non-empty.
215231
</p>
216232
</dd>
217233
<dt>
218234
<code class="key">DescEx</code>
219235
</dt>
220236
<dd>
237+
<aside>
238+
<p>
239+
<span class="very-strong">Required as of v2.1.0</span>.
240+
</p>
241+
<p>
242+
v2.1.0 conformant collections <span class="very-strong">must</span> use this key.
243+
</p>
244+
<p>
245+
Software <span class="very-strong">must</span> report an error when parsing v2.1.0 conformant collections if <code class="key">DescEx</code> is missing.
246+
</p>
247+
</aside>
221248
<p>
222249
Formatted description of the snippet using REML<sup><a href="#footnote-1">1</a></sup> code.
223250
</p>
224251
<p>
225-
May be empty, in which case the <code class="key">Desc</code> key is used. <code class="key">Desc</code> is ignored if <code class="key">DescEx</code> has a non-empty value. At least one of the <code class="key">Desc</code> or <code class="key">DescEx</code> keys are <span class="very-strong">required</span> to be present and non-empty.
252+
For version 2.0.x only, <code class="key">DescEx</code> may be empty, in which case the <code class="key">Desc</code> key is used. <code class="key">Desc</code> is ignored if <code class="key">DescEx</code> has a non-empty value. At least one of the <code class="key">Desc</code> or <code class="key">DescEx</code> keys are <span class="very-strong">required</span> to be present and non-empty.
226253
</p>
227254
</dd>
228255
<dt>
@@ -291,16 +318,27 @@ <h2 id="category-ini">
291318
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.
292319
</p>
293320
<p>
294-
May be omitted or empty. In this case any 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, if present.
321+
May be omitted or empty.
295322
</p>
296323
<p>
297-
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.
324+
For v2.0.x only, if and only if <code class="key">Extra</code> is empty, extra information is generated from the <code class="key">Comments</code>, <code class="key">Credits</code> and <code class="key">Credits_URL</code> key values.
298325
</p>
299326
</dd>
300327
<dt>
301328
<code class="key">Credits</code><sup><a href="#footnote-2">2</a></sup>
302329
</dt>
303330
<dd>
331+
<aside>
332+
<p>
333+
<span class="very-strong">Deprecated as of v2.1.0</span>: use <code class="key">Extra</code> instead.
334+
</p>
335+
<p>
336+
v2.1.0 conformant collections <span class="very-strong">must not</span> use this key.
337+
</p>
338+
<p>
339+
Software <span class="very-strong">must</span> ignore this key when parsing v2.1.0 conformant collections.
340+
</p>
341+
</aside>
304342
<p>
305343
Text that notes any credits / acknowledgements. <code class="key">Credits</code> may optionally contain one (and only one) section of text delimited by <code>[</code> and <code>]</code> characters that indicate the presence of a hyperlink. The enclosed text is used as the text of a hyperlink whose URL <span class="very-strong">must</span> be specified in the <code class="key">Credits_URL</code> key.
306344
</p>
@@ -312,6 +350,17 @@ <h2 id="category-ini">
312350
<code class="key">Credits_URL</code><sup><a href="#footnote-2">2</a></sup>
313351
</dt>
314352
<dd>
353+
<aside>
354+
<p>
355+
<span class="very-strong">Deprecated as of v2.1.0</span>.
356+
</p>
357+
<p>
358+
v2.1.0 conformant collections <span class="very-strong">must not</span> use this key.
359+
</p>
360+
<p>
361+
Software <span class="very-strong">must</span> ignore this key when parsing v2.1.0 conformant collections.
362+
</p>
363+
</aside>
315364
<p>
316365
The URL used in any hyperlink present in the <code class="key">Credits</code> key.
317366
</p>
@@ -323,6 +372,17 @@ <h2 id="category-ini">
323372
<code class="key">Comments</code>
324373
</dt>
325374
<dd>
375+
<aside>
376+
<p>
377+
<span class="very-strong">Deprecated as of v2.1.0</span>: use <code class="key">Extra</code> instead.
378+
</p>
379+
<p>
380+
v2.1.0 conformant collections <span class="very-strong">must not</span> use this key.
381+
</p>
382+
<p>
383+
Software <span class="very-strong">must</span> ignore this key when parsing v2.1.0 conformant collections.
384+
</p>
385+
</aside>
326386
<p>
327387
Text string containing any additional comments about the snippet.
328388
</p>
@@ -650,11 +710,11 @@ <h1>
650710
<li id="footnote-1">
651711
<p>
652712
REML is a text markup language used to format text. REML version 4 is supported. The REML format is documented in <a href="reml.html">reml.html</a>.
653-
</p>
713+
</p>
654714
</li>
655715
<li id="footnote-2">
656716
<p>
657-
Here is an example of how the <code class="key">Credits</code> and <code class="key">Credits_URL</code> keys work together.
717+
Here is an example of how the <span class="very-strong">deprecated</span> <code class="key">Credits</code> and <code class="key">Credits_URL</code> keys work together.
658718
</p>
659719
<p>
660720
If <code class="key">Credits</code>=<code class="value">&quot;See [example 1]&quot;</code> and <code class="key">Credits_URL</code>=<code class="value">&quot;http://example.com&quot;</code> and the <code class="key">Extra</code> key is empty or missing then the extra REML code generated will be <samp>See &lt;a href=&quot;example.com&quot;&gt;example 1&lt;/a&gt;</samp>.

0 commit comments

Comments
 (0)