1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
|
<chapter id="hacking">
<title>Hacking &appname;</title>
<para>
In the spirit of Free Software, you're welcome to hack on &appname; as much as you like. You should be able to write scripts to import, export, or modify data very easily. This chapter gives you more information about doing that.
</para>
<sect1 id="file-format">
<title>File Format</title>
<para>
The default &appname; data file is a zip archive, normally with a <literal role="extension">.tc</literal> file extension. Inside the archive is a top-level <filename>tellico.xml</filename> file. Images may be included inside the <filename>images/</filename> directory in the archive., or they may be included in the &xml; data directly in a base64 encoding. Images may also be saved inside the application data directory, in which case, they are not in the data file at all. &appname; can also load the &xml; file, by itself, uncompressed.
</para>
<sect2 id="xml-format">
<title>&xml; Data</title>
<para>
</para>
<sect3 id="coll-xml-data">
<title>Collection</title>
<programlisting>
<![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE tellico PUBLIC "-//Robby Stephenson/DTD Tellico V9.0//EN" "http://periapsis.org/tellico/dtd/v9/tellico.dtd">
<tellico xmlns="http://periapsis.org/tellico/" syntaxVersion="9">
<collection title="My Books" type="2">
</collection>
</tellico>
]]>
</programlisting>
<para>
The file begins with the required &xml; declaration and encoding, followed by the doctype. When a new field type is added or additional properties are set on the default fields, the doctype DTD version is incremented. &appname; is always able to open and read any previous DTD version, but will save files in the current version. The DTD location does point to an actual DTD file.
</para>
<para>
The top-level element is a <markup><tellico></markup> element, containing the default namespace declaration and the syntax version of the file, which should always match the DTD.
</para>
<para>
The <markup><tellico></markup> element contains one <markup><collection></markup> element. Multiple collections are ignored, for now. The <markup>title</markup> attribute contains the collection title, while the <markup>type</markup> specifies what kinds of entries are contained in the collection. The allowable types are in <link linkend="collection-type-values">listed in a later section</link>. An optional <markup>entryTitle</markup> attribute may be used to specify the title of the entries for a custom collection, and should be plural.
</para>
</sect3>
<sect3 id="fields-xml-data">
<title>Fields</title>
<programlisting>
<![CDATA[
<fields>
<field flags="8" title="Title" category="General" format="1" type="1" name="title" />
<field flags="7" title="Author" category="General" format="2" type="1" name="author" />
<field flags="2" title="Binding" category="General" allowed="Hardback;Paperback;Trade Paperback;E-Book;Magazine;Journal" format="4" type="3" name="binding" />
<field flags="6" title="Publisher" category="Publishing" format="0" type="1" name="publisher" />
<field flags="4" title="Edition" category="Publishing" format="0" type="1" name="edition" />
<field flags="3" title="Copyright Year" category="Publishing" format="4" type="6" name="cr_year" />
<field flags="2" title="Publication Year" category="Publishing" format="4" type="6" name="pub_year" />
<field flags="0" title="ISBN#" category="Publishing" format="4" type="1" name="isbn" description="International Standard Book Number" />
<field flags="7" title="Genre" category="Classification" format="0" type="1" name="genre" />
<field flags="7" title="Keywords" category="Classification" format="0" type="1" name="keyword" />
<field flags="0" title="Front Cover" category="Front Cover" format="4" type="10" name="cover" />
<field flags="0" title="Comments" category="Personal" format="4" type="1" name="comments" />
</fields>
]]>
</programlisting>
<para>
All of the fields are defined inside a <markup><fields></markup> element, of which there can be only one. All of the information for a field, except for any extended properties, are included as attributes of the <markup><field></markup> element. The allowable values for the <markup>flags</markup>, <markup>format</markup>, and <markup>type</markup> attributes are given in a <link linkend="field-type-values">following section</link>.
</para>
<para>
A <markup><field></markup> element with a name attribute equal to <emphasis>_default</emphasis> tells &appname; to include all the default fields for that collection type.
</para>
</sect3>
<sect3 id="entries-xml-data">
<title>Entries</title>
<programlisting>
<![CDATA[
<entry>
<title>C++ Programming Language, The</title>
<authors>
<author>Stroustrup, Bjarne</author>
</authors>
<publisher>Addison-Wesley Pub Co</publisher>
<edition>3rd</edition>
<pub_year>1997</pub_year>
<isbn>0-201-88954-4</isbn>
<genres>
<genre>Non-Fiction</genre>
</genres>
<keywords>
<keyword>Programming</keyword>
<keyword>Computers</keyword>
</keywords>
<cover>cf65a2f023b6cb9e9233323dca10ac7c.jpeg</cover>
</entry>
]]>
</programlisting>
<para>
For every field in the collection, an <markup><entry></markup> may contain an element whose name is identical to the field name. If multiple values are allowed for the field, then the letter <emphasis>s</emphasis> is added to the field name to create an element, and each value is added as a child of the element, as in the case of the author, genre, and keyword fields above.
</para>
<para>
As a result, if additional fields are added to the collection, the date file will no longer conform to the DTD. However, &appname; uses a non-validating &xml; parser, so additional fields do not cause problems.
</para>
</sect3>
<sect3 id="images-xml-data">
<title>Images</title>
<programlisting>
<![CDATA[
<images>
<image width="111" format="JPEG" height="140" id="cf65a2f023b6cb9e9233323dca10ac7c.jpeg" />
</images>
]]>
</programlisting>
<para>
Inside the <markup><images></markup> element, each image referenced by an entry is listed, along with attributes describing the image's size, format, and id. If the image is contained inside the Zip file, the element is empty. Otherwise, the image data may be contained in the &xml; stream as base64-encoded text.
</para>
</sect3>
</sect2>
</sect1>
<sect1 id="collection-type-values">
<title>Collection Type Values</title>
<para>
The type of collection is given in the type attribute of the collection element. The value is equal to the <type>Type</type> enum value in <filename>src/collection.h</filename>.
</para>
<table>
<title>Collection Type Values</title>
<tgroup cols="2">
<thead>
<row>
<entry>Collection Type</entry>
<entry>Value</entry>
</row>
</thead>
<tbody>
<row><entry>Custom Collection</entry><entry>1</entry></row>
<row><entry>Book Collection</entry><entry>2</entry></row>
<row><entry>Video Collection</entry><entry>3</entry></row>
<row><entry>Music Collection</entry><entry>4</entry></row>
<row><entry>Bibliography</entry><entry>5</entry></row>
<row><entry>Comic Book Collection</entry><entry>6</entry></row>
<row><entry>Wine Collection</entry><entry>7</entry></row>
<row><entry>Coin Collection</entry><entry>8</entry></row>
<row><entry>Stamp Collection</entry><entry>9</entry></row>
<row><entry>Trading Card Collection</entry><entry>10</entry></row>
<row><entry>Video Game Collection</entry><entry>11</entry></row>
<row><entry>File Catalog</entry><entry>12</entry></row>
<row><entry>Board Game Collection</entry><entry>13</entry></row>
</tbody>
</tgroup>
</table>
</sect1>
<sect1 id="field-type-values">
<title>Field Type Values</title>
<para>
&appname; will include all the default fields for a collection if the first field element has the name <emphasis>_default</emphasis>. For <emphasis>Paragraph</emphasis>, <emphasis>Table</emphasis>, or <emphasis>Image</emphasis> fields, the field category should be identical to the field title.
</para>
<para>
The type of field is given in the type attribute of the field element. The value is equal to the <type>FieldType</type> enum value in <filename>src/field.h</filename>. <emphasis>ReadOnly</emphasis> fields were intended for fields which should be retained in the collection, but which should not be editable by the user, such as some fields added when importing a collection from another file format. It is not currently used.
</para>
<table>
<title>Field Type Values</title>
<tgroup cols="2">
<thead>
<row>
<entry>Field Type</entry>
<entry>Value</entry>
</row>
</thead>
<tbody>
<row><entry>Simple Text</entry><entry>1</entry></row>
<row><entry>Paragraph</entry><entry>2</entry></row>
<row><entry>Choice</entry><entry>3</entry></row>
<row><entry>Checkbox</entry><entry>4</entry></row>
<row><entry><emphasis>ReadOnly</emphasis></entry><entry>5</entry></row>
<row><entry>Number</entry><entry>6</entry></row>
<row><entry>URL</entry><entry>7</entry></row>
<row><entry>Single-Column Table</entry><entry>8</entry></row>
<row><entry>Image</entry><entry>10</entry></row>
<row><entry>Dependent</entry><entry>11</entry></row>
<row><entry>Date</entry><entry>12</entry></row>
<row><entry>Rating</entry><entry>14</entry></row>
</tbody>
</tgroup>
</table>
<para>
The field may have different flags set, given as a bitwise OR'd value in the flags attribute on the field element. The flag for preventing the user from deleting a field is intended for such things as the citation key for bibliographic entries.
</para>
<table>
<title>Field Flag Values</title>
<tgroup cols="2">
<thead>
<row>
<entry>Field Flags</entry>
<entry>Value</entry>
</row>
</thead>
<tbody>
<row><entry>Allow Multiple Values</entry><entry><constant>0x01</constant></entry></row>
<row><entry>Allow Grouping</entry><entry><constant>0x02</constant></entry></row>
<row><entry>Allow Completion</entry><entry><constant>0x04</constant></entry></row>
<row><entry><emphasis>Disallow Deleting</emphasis></entry><entry><constant>0x08</constant></entry></row>
</tbody>
</tgroup>
</table>
<para>
The format of the field is given in the format attribute on the field element. <emphasis>Date Formatting</emphasis> is not currently used. Grouping by <emphasis>People</emphasis> uses all the fields which use <emphasis>Name Formatting</emphasis>.
</para>
<table>
<title>Field Format Values</title>
<tgroup cols="2">
<thead>
<row>
<entry>Field Format</entry>
<entry>Value</entry>
</row>
</thead>
<tbody>
<row><entry>Capitalization Only</entry><entry>0</entry></row>
<row><entry>Title Formatting</entry><entry>1</entry></row>
<row><entry>Name Formatting</entry><entry>2</entry></row>
<row><entry><emphasis>Date Formatting</emphasis></entry><entry>3</entry></row>
<row><entry>No Formatting</entry><entry>4</entry></row>
</tbody>
</tgroup>
</table>
</sect1>
<sect1 id="hidden-options">
<title>Hidden Configuration Options</title>
<para>
&appname; has some additional configuration options that are not visible in the &config-dialog;. They are not important enough to warrant cluttering the dialog with more settings, but as they represent options which may appeal to various users, the application does read them from the configuration file.
</para>
<para>
The settings for &appname; are saved in a file in the user's home folder, namely <filename>$<envar>TDEHOME</envar>/share/config/tellicorc</filename>. Within that file, settings are put in groups, which appear with bracketed names, such as [General Options]. To add a setting to the <emphasis>General Options</emphasis> group, find the line in the settings file with that group name. If it does not appear, then create it yourself by adding a line saying [General Options]. Then, the setting can be added underneath the group name.
</para>
<sect2 id="hidden-general-options">
<title>[General Options]</title>
<para>
These settings should be placed in the <emphasis>General Options</emphasis> group.
</para>
<sect3>
<title>Max Icon Size</title>
<para>
The maximum size of the icons in the &icon-view; may be changed with this setting. The default value is 96. The size must be in the range of 32 to 128.
</para>
</sect3>
<sect3>
<title>Example</title>
<informalexample>
<para><userinput>Max Icon Size=72</userinput></para>
</informalexample>
</sect3>
</sect2>
<sect2 id="hidden-bibtex-options">
<title>[Options - bibtex]</title>
<para>
These settings should be placed in the <emphasis>Options - bibtex</emphasis> group.
</para>
<sect3>
<title>lyxpipe</title>
<para>
This setting is for the location of the lyxpipe for sending bibliographic citations. It should not include the <literal role="extension">.in</literal> suffix.
</para>
</sect3>
<sect3>
<title>Example</title>
<informalexample>
<para><userinput>lyxpipe=$HOME/.lyx/lyxpipe</userinput></para>
</informalexample>
</sect3>
</sect2>
<sect2 id="hidden-export-options-pilotdb">
<title>[Export Options - PilotDB]</title>
<para>
These settings should be placed in the <emphasis>Export Options - PilotDB</emphasis> group.
</para>
<sect3>
<title>Charset</title>
<para>
The encoding of the exported data within the PilotDB file may be changed with this setting. The default value is the character set for the user's locale.
</para>
</sect3>
<sect3>
<title>Example</title>
<informalexample>
<para><userinput>Charset=Windows-1250</userinput></para>
</informalexample>
</sect3>
</sect2>
</sect1>
<sect1 id="bibtex-translation">
<title>Bibtex Character Translation</title>
<para>
When bibtex files are imported or exported, certain characters are translated between their TeX equivalents and the Unicode characters. Those character mappings are contained in the <filename>bibtex-translation.xml</filename> file, located in the installation data directory. The mappings can be modified, as desired. The key element contains the Unicode character, and the string elements within contain the TeX equivalents, which may be a one-to-many mapping. The first one is the one used when exporting to bibtex.
</para>
<programlisting>
<![CDATA[
<key char="À">
<string>{\`A}</string>
<string>\`{A}</string>
</key>
]]>
</programlisting>
</sect1>
<sect1 id="xslt-tricks">
<title>XSLT Tricks</title>
<para>
Here are some tips for writing XSLT to parse &appname; &xml; data: (TBD).
</para>
</sect1>
</chapter>
|