<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<!--
* CodeSnip File Format Documentation: Export
*
* $Rev$
* $Date$
-->
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head>
<title>
CodeSnip File Format Documentation - Export
</title>
<link
rel="stylesheet"
type="text/css"
media="screen"
href="main.css"
/>
</head>
<body>
<div class="title">
<div>
DelphiDabbler CodeSnip
</div>
<div class="subtitle">
File Format Documentation
</div>
</div>
<h1>
Export Files
</h1>
<p class="todo">
<strong>TODO:</strong>
Add list of links to sections of this document and to any other related
documents.
</p>
<h2>
Introduction
</h2>
<p>
User defined snippets can be exported from the program for importing into
another program or for submitting to the online database. Exported data is
stored in a single XML file.
</p>
<p>
There have been several different versions of the XML file format. Each of
these is explained below.
</p>
<h2>
Encoding
</h2>
<p>
XML export files use UTF-8 encoding without a byte order mark. XML generated
for submission to the online database is also encoded in UTF-8.
</p>
<p>
CodeSnip 4 includes an <em>encoding</em> attribute "UTF-8" in the
XML file's XML processing instruction. Earlier versions of the program omitted
this attribute.
</p>
<h2>
File Format
</h2>
<p>
There have been six different versions of the XML file format – v1 to
v6. Tags from all six versions are explained below with notes describing
which versions a tag applies to. Where there is no note the tag is valid in
all versions.
</p>
<dl>
<dt>
<strong><em>XML processing instruction</em></strong>
</dt>
<dd>
<div class="half-spaced">
Attributes:
</div>
<dl class="indent">
<dt>
<em>version</em>
</dt>
<dd>
Always set to "1.0"
</dd>
<dt>
<em>encoding</em>
</dt>
<dd>
<div class="half-spaced">
Character encoding used for file.
</div>
<ul class="squashed">
<li>
<span class="highlight">versions 1..4:</span> Attribute not
provided.
</li>
<li>
<span class="highlight">version 5 and later:</span> Always set to
"UTF-8".
</li>
</ul>
</dd>
</dl>
</dd>
<dt>
<strong>codesnip-export</strong>
</dt>
<dd>
<div class="half-spaced">
Parent node for whole file. Attributes are:
</div>
<dl class="indent">
<dt>
<em>watermark</em>
</dt>
<dd>
Identifies file as correct type – always set to
"B46969D4-D367-4F5F-833E-F165FBA78631".
</dd>
<dt>
<em>version</em>
</dt>
<dd>
Identifies version of file. Determines which tags are valid and
establishes rules concerning content. Valid versions are 1..6.
</dd>
</dl>
</dd>
<dt>
<strong>codesnip-export/prog-version</strong>
</dt>
<dd>
Version of program that generated the file, as a dotted quad with format
N.N.N.N where N is a non-negative integer.
</dd>
<dt>
<strong>codesnip-export/user-info</strong>
</dt>
<dd>
Contains information about user who created the file (omitted for normal
exports – included for submissions to the online database).
</dd>
<dt>
<strong>codesnip-export/user-info/name</strong>
</dt>
<dd>
User's name or nickname.
</dd>
<dt>
<strong>codesnip-export/user-info/email</strong>
</dt>
<dd>
User's email address.
</dd>
<dt>
<strong>codesnip-export/user-info/comments</strong>
</dt>
<dd>
Any comments provided by user.
</dd>
<dt>
<strong>codesnip-export/routines</strong>
</dt>
<dd>
Contains a list of all exported snippets.
</dd>
<dt>
<strong>codesnip-export/routines/routine</strong>
</dt>
<dd>
<div class="half-spaced">
Contains information about an exported snippet. One per snippet.
Attribute is:
</div>
<dl class="indent">
<dt>
<em>name</em>
</dt>
<dd>
<div class="half-spaced">
Name of snippet.
</div>
<ul class="squashed">
<li>
<span class="highlight">versions 1..4:</span> Name must begin with
an English language letter or the underscore.
</li>
<li>
<span class="highlight">version 5 and later:</span> Name can begin
with any character that is valid as the first character of a Unicode
Pascal identifier.
</li>
</ul>
</dd>
</dl>
</dd>
<dt>
<strong>codesnip-export/routines/routine/description</strong>
</dt>
<dd>
<div class="half-spaced">
Description of snippet.
</div>
<ul class="squashed">
<li>
<span class="highlight">versions 1..5:</span> Content is a single line
of plain text.
</li>
<li>
<span class="highlight">version 6:</span> Content is formatted text
encoded in REML markup. REML v3 is supported.
</li>
</ul>
</dd>
<dt>
<strong>codesnip-export/routines/routine/source-code-text</strong>
</dt>
<dd>
Snippet source code.
</dd>
<dt>
<strong>codesnip-export/routines/routine/comments</strong>
</dt>
<dd>
<div class="half-spaced">
<ul class="squashed">
<li>
<span class="highlight">version 1:</span> Additional comments about
snippets.
</li>
<li>
<span class="highlight">version 2 and later:</span> Not supported.
</li>
</ul>
</div>
</dd>
<dt>
<strong>codesnip-export/routines/routine/credits</strong>
</dt>
<dd>
<div class="half-spaced">
<ul class="squashed">
<li>
<span class="highlight">version 1:</span> Credits for snippets. May
contain a single piece of text, delimited by "[" and
"]" that can form a hyperlink. URL for the hyperlink is
provided in <em>codesnip-export/routines/routine/credits-url</em>.
</li>
<li>
<span class="highlight">version 2 and later:</span> Not supported.
</li>
</ul>
</div>
</dd>
<dt>
<strong>codesnip-export/routines/routine/credits-url</strong>
</dt>
<dd>
<div class="half-spaced">
<ul class="squashed">
<li>
<span class="highlight">version 1:</span> URL required by
<em>codesnip-export/routines/routine/credits</em> tag. Present only if
<em>codesnip-export/routines/routine/credits</em> requires a hyperlink.
</li>
<li>
<span class="highlight">version 2 and later:</span> Not supported.
</li>
</ul>
</div>
</dd>
<dt>
<strong>codesnip-export/routines/routine/extra</strong>
</dt>
<dd>
<div class="half-spaced">
<ul class="squashed">
<li>
<span class="highlight">version 1:</span> Not supported.
</li>
<li>
<div class="unspaced">
<span class="highlight">version 2 and later:</span> Additional
information about a snippet. Content is formatted text encoded in
REML markup.
</div>
<ul class="squashed">
<li>
<span class="highlight">version 2:</span> indicates REML v1
</li>
<li>
<span class="highlight">version 3:</span> indicates REML v2
</li>
<li>
<span class="highlight">versions 4 and 5:</span> indicates REML
v3.
</li>
</ul>
</li>
</ul>
</div>
</dd>
<dt>
<strong>codesnip-export/routines/routine/standard-format</strong>
</dt>
<dd>
<div class="half-spaced">
<ul class="squashed">
<li>
<span class="highlight">versions 1 and 2:</span> Flag indicating if
snippet is in "standard format". Value of 1 indicates true
and 0 indicates false.
</li>
<li>
<span class="highlight">version 3 and later:</span> Not supported.
</li>
</ul>
</div>
</dd>
<dt>
<strong>codesnip-export/routines/routine/kind</strong>
</dt>
<dd>
<div class="half-spaced">
<ul class="squashed">
<li>
<span class="highlight">versions 1 and 2:</span> Not supported.
</li>
<li>
<span class="highlight">version 3 and later:</span> Value indicating
kind of snippet. Permissible values are:
<ul class="squashed">
<li>
<span class="highlight">versions 3 and 4:</span>
"freeform", "routine", "type" &
"const".
</li>
<li>
<span class="highlight">version 5 and later:</span>
"freeform", "routine", "type",
"const", "class" & "unit".
</li>
</ul>
</li>
</ul>
</div>
</dd>
<dt>
<strong>codesnip-export/routines/routine/compiler-results</strong>
</dt>
<dd>
Contains a list of compile results for the snippet.
</dd>
<dt>
<strong>codesnip-export/routines/routine/compiler-results/compiler-result
</strong>
</dt>
<dd>
<div class="half-spaced">
Entry for each known compiler. Attribute is:
</div>
<dl class="indent">
<dt>
<em>id</em>
</dt>
<dd>
<div class="half-spaced">
Identifies compiler. Valid identifiers are are one of:
</div>
<ul class="squashed">
<li>
<em>d2</em> – Delphi 2 compiler
</li>
<li>
<em>d3</em> – Delphi 3 compiler
</li>
<li>
<em>d4</em> – Delphi 4 compiler
</li>
<li>
<em>d5</em> – Delphi 5 compiler
</li>
<li>
<em>d6</em> – Delphi 6 compiler
</li>
<li>
<em>d7</em> – Delphi 7 compiler
</li>
<li>
<em>d2005</em> – Delphi 2005 compiler
</li>
<li>
<em>d2006</em> – Delphi 2006 compiler
</li>
<li>
<em>d2007</em> – Delphi 2007 compiler
</li>
<li>
<em>d2009</em> – Delphi 2009 compiler
</li>
<li>
<em>d2010</em> – Delphi 2010 compiler
</li>
<li>
<em>dXE</em> – Delphi XE compiler
</li>
<li>
<em>dXE2</em> – Delphi XE2 compiler
</li>
<li>
<em>fpc</em> – Free Pascal compiler
</li>
</ul>
</dd>
</dl>
<div class="half-spaced">
Values are:
</div>
<ul class="squashed">
<li>
"Y" – Compiles with the identified compiler.
</li>
<li>
"W" – Compiles with the identified compiler with
warnings.
</li>
<li>
"N" – Does not compile with the identified compiler.
</li>
<li>
"Q" – Compile result for this compiler is not known.
</li>
</ul>
<div class="half-spaced">
Omitting a tag for a certain compiler is permitted and is equivalent to
specifying "Q".
</div>
</dd>
<dt>
<strong>codesnip-export/routines/routine/units</strong>
</dt>
<dd>
List of required units.
</dd>
<dt>
<strong>codesnip-export/routines/routine/units/pascal-name</strong>
</dt>
<dd>
Name of a unit within unit list. Must be a valid Pascal identifier.
</dd>
<dt>
<strong>codesnip-export/routines/routine/depends</strong>
</dt>
<dd>
List of required snippets.
</dd>
<dt>
<strong>codesnip-export/routines/routine/depends/pascal-name</strong>
</dt>
<dd>
<div class="half-spaced">
Name of a snippet within depends list.
</div>
<ul class="squashed">
<li>
<span class="highlight">versions 1..4:</span> Name must begin with an
English language letter or the underscore.
</li>
<li>
<span class="highlight">version 5 and later:</span> Name can begin with
any character that is valid as the first character of a Unicode Pascal
identifier.
</li>
</ul>
</dd>
<dt>
<strong>codesnip-export/routines/routine/xref</strong>
</dt>
<dd>
List of cross-referenced snippets.
</dd>
<dt>
<strong>codesnip-export/routines/routine/xref/pascal-name</strong>
</dt>
<dd>
<div class="half-spaced">
Name of a snippet within cross-reference list.
</div>
<ul class="squashed">
<li>
<span class="highlight">versions 1..4:</span> Name must begin with an
English language letter or the underscore.
</li>
<li>
<span class="highlight">version 5 and later:</span> Name can begin with
any character that is valid as the first character of a Unicode Pascal
identifier.
</li>
</ul>
</dd>
</dl>
<h2>
Differences Between File Versions
</h2>
<p>
The differences between different export file versions is summarised below:
</p>
<dl>
<dt>
Version 1
</dt>
<dd>
First version of database.
</dd>
<dt>
Version 2
</dt>
<dd>
<div class="half-spaced">
The following tags are no longer supported:
</div>
<ul class="squashed">
<li>
<em>codesnip-export/routines/routine/comments</em>
</li>
<li>
<em>codesnip-export/routines/routine/credits</em>
</li>
<li>
<em>codesnip-export/routines/routine/credits-url</em>
</li>
</ul>
<div class="half-spaced">
The following tag was introduced:
</div>
<ul class="squashed">
<li>
<em>codesnip-export/routines/routine/extra</em> (uses REML v1 markup).
</li>
</ul>
</dd>
<dt>
Version 3
</dt>
<dd>
<div class="half-spaced">
The following tag is no longer supported:
</div>
<ul class="squashed">
<li>
<em>codesnip-export/routines/routine/standard-format</em>
</li>
</ul>
<div class="half-spaced">
The following tag was introduced:
</div>
<ul class="squashed">
<li>
<em>codesnip-export/routines/routine/kind</em>
</li>
</ul>
<div class="half-spaced">
The version of REML supported by the
<em>codesnip-export/routines/routine/extra</em> tag was updated to v2.
</div>
</dd>
<dt>
Version 4
</dt>
<dd>
The version of REML supported by the
<em>codesnip-export/routines/routine/extra</em> tag was updated to v3.
</dd>
<dt>
Version 5
</dt>
<dd>
<div class="half-spaced">
The XML file's encoding was explicitly set to "UTF-8" by setting
the encoding attribute of the XML processing instruction to this value.
</div>
<div class="half-spaced">
Snippet names, wherever they occur in the XML file, can now begin with
any character that is a valid first character of a Unicode Pascal
identifier. Previously the first character of the attribute had to be one
of 'A'..'Z', 'a'..'z' or '_'.
</div>
<div class="half-spaced">
New "class" and "unit" snippet kinds supported.
</div>
</dd>
<dt>
Version 6
</dt>
<dd>
A snippet's description is now stored as formatted text using REML markup.
Previously the description was plain text.
</dd>
</dl>
<h3>
Notes For File Readers Used For Importing
</h3>
<p>
Readers of version 1 files must convert the contents of the
<em>codesnip-data/routines/routine/comments</em>,
<em>codesnip-data/routines/routine/credits</em> and
<em>codesnip-data/routines/routine/credits-url</em> tags into formatted text
that simulates the parsed content of the
<em>codesnip-data/routines/routine/extra</em> tag.
</p>
<p>
Readers of v1 and v2 files should map a
<em>codesnip-data/routines/routine/standard-format</em> value of "0"
to a <em>codesnip-data/routines/routine/kind</em> value of
"freeform" and a value of "1" to "routine".
</p>
<p>
Readers of v1 to v5 files must convert the plain text snippet description read
from <em>codesnip-data/routines/routine/description</em> into the formatted
text equivalent of a single paragraph containing the description.
</p>
</body>
</html>
