summaryrefslogtreecommitdiff
path: root/obsolete/help/Catalogue/catalogue.dtd
blob: aac908840aa397d4c8cf03aeef18c17656bf3fc3 (plain)
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
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
<?xml version="1.0" encoding="UTF-8"?>

<!-- The basic design of the DTD for the TeX Catalogue

Copyright (c) 1999-2004 Graham J. Williams

The CATALOGUE has a MAINTAINER which records the email address or
username of the person maintaining the catalogue, a DATESTAMP
to record when it was last modified, and a LICENSE to indicate that it
can not be taken by someone else and copyrighted.  It is to be freely
available under terms similar to the intent of the FSF GPL. All three
attributes must be provided.

The CATALOGUE consists of a collection of zero or more ENTRYs.

The ABOUT element records general information about the package,
including a mandatory CAPTION (at least it probably should be
mandatory, but is not presently).

TODO

    Complete the description of the DTD


Change history
==============

2015-11-17  Manfred Lotz      Add boolean attributes 'female' and 'died' to authors.
                              Default for both is 'false'.
2015-03-30  Manfred Lotz      Make license a mandatory element.
2015-03-15  Manfred Lotz      Added licenses to be in sync with http://ctan.org/license/
                              bsd2, bsd4, lgpl3
2014-11-28  Manfred Lotz      Make authorref element mandadory.
2014-11-16  Manfred Lotz      Added an optional installation_notes element (PCDATA).
2014-09-16  Manfred Lotz      Added an optional note (CDATA) to uploaderref.
2014-09-14  Manfred Lotz      Added more specific bsd3 license in addition to bsd.
2014-03-01  Manfred Lotz      Added a list of valid language codes as a constraint for 
                              attribute language. The list is taken from 
                              http://www.lingoes.net/en/translator/langcode.htm
							  and expanded by the list of ISO 639 codes, as required.
 
2014-02-03  Manfred Lotz      Add optional element uploaderref to indicate a person
                              who may upload on behalf of the original author.
							  Constraint: Only registered package authors may 
                                          upload a package on behalf of another.
- -->

<!ENTITY hellip "&#8230;">
<!ENTITY nbsp   "&#160;">
<!ENTITY pound  "&#163;">

<!ENTITY % text "#PCDATA|xref|em|a|p|pre|tt|br">

<!ENTITY % language "language (
		aa     | ab     | ae     | af     | af-za  | ak     |
		am     | an     | ar     | ar-ae  | ar-bh  | ar-dz  |
		ar-eg  | ar-iq  | ar-jo  | ar-kw  | ar-lb  | ar-ly  |
		ar-ma  | ar-om  | ar-qa  | ar-sa  | ar-sy  | ar-tn  |
		ar-ye  | as     | av     | ay     | az     | az-az  |
		ba     | be     | be-by  | bg     | bg-bg  | bh     |
		bi     | bm     | bn     | bo     | br     | bs-ba  |
		ca     | ca-es  | ce     | co     | cr     | cs     |
		cs-cz  | cv     | cy     | cy-gb  | da     | da-dk  |
		de     | de-at  | de-ch  | de-de  | de-li  | de-lu  |
		dv     | dv-mv  | dz     | ee     | el     | el-gr  |
		en     | en-au  | en-bz  | en-ca  | en-cb  | en-gb  |
		en-ie  | en-jm  | en-nz  | en-ph  | en-tt  | en-us  |
		en-za  | en-zw  | eo     | es     | es-ar  | es-bo  |
		es-cl  | es-co  | es-cr  | es-do  | es-ec  | es-es  |
		es-gt  | es-hn  | es-mx  | es-ni  | es-pa  | es-pe  |
		es-pr  | es-py  | es-sv  | es-uy  | es-ve  | et     |
		et-ee  | eu     | eu-es  | fa     | fa-ir  | ff     |
		fi     | fi-fi  | fj     | fo     | fo-fo  | fr     |
		fr-be  | fr-ca  | fr-ch  | fr-fr  | fr-lu  | fr-mc  |
		fy     | ga     | gd     | gl     | gl-es  | gn     |
		gu     | gu-in  | gv     | ha     | he     | he-il  |
		hi     | hi-in  | ho     | hr     | hr-ba  | hr-hr  |
		ht     | hu     | hu-hu  | hy     | hy-am  | hz     |
		ia     | id     | id-id  | ie     | ig     | ii     |
		ik     | io     | is     | is-is  | it     | it-ch  |
		it-it  | iu     | ja     | ja-jp  | jv     | ka     |
		ka-ge  | kg     | ki     | kj     | kk     | kk-kz  |
		kl     | km     | kn     | kn-in  | ko     | ko-kr  |
		kok    | kok-in | kr     | ks     | ku     | kv     |
		kw     | ky     | ky-kg  | la     | lb     | lg     |
		li     | ln     | lo     | lt     | lt-lt  | lu     |
		lv     | lv-lv  | mg     | mh     | mi     | mi-nz  |
		mk     | mk-mk  | ml     | mn     | mn-mn  | mr     |
		mr-in  | ms     | ms-bn  | ms-my  | mt     | mt-mt  |
		my     | na     | nb     | nb-no  | nd     | ne     |
		ng     | nl     | nl-be  | nl-nl  | nn-no  | nn     |
		nr     | ns     | ns-za  | nv     | ny     | oc     |
		oj     | om     | or     | os     | pa     | pa-in  |
		pi     | pl     | pl-pl  | ps     | ps-ar  | pt     |
		pt-br  | pt-pt  | qu     | qu-bo  | qu-ec  | qu-pe  |
		rm     | rn     | ro     | ro-ro  | ru     | ru-ru  |
		rw     | sa     | sa-in  | sd     | se     | se-fi  |
		se-no  | se-se  | si     | sk     | sk-sk  | sl     |
		sl-si  | sm     | sn     | so     | sq     | sq-al  |
		sr-ba  | sr-sp  | ss     | st     | su     | sv     |
		sv-fi  | sv-se  | sw     | sw-ke  | syr    | syr-sy |
		ta     | ta-in  | te     | te-in  | tg     | th     |
		th-th  | ti     | tk     | tl     | tl-ph  | tn     |
		tn-za  | to     | tr     | tr-tr  | ts     | tt     |
		tt-ru  | tw     | ty     | ug     | uk     | uk-ua  |
		ur     | ur-pk  | uz     | uz-uz  | ve     | vi     |
		vi-vn  | vo     | wa     | wo     | xh     | xh-za  |
		yi     | yo     | za     | zh     | zh-cn  | zh-hk  |
		zh-mo  | zh-sg  | zh-tw  | zu     | zu-za             ) #IMPLIED">


<!ELEMENT fullcat (authors, catalogue)>


<!-- author element
We keep only one entry for each author, as a sanity measure.

The 'id' attribute values are prefixed 'auth:', for instance 
'auth:hefferon-j' because XML has a single namespace for id's.

Authors names had been broken into family name and given name
but the problems with different cultures, with what to do with the names
of organizations, etc., proved to be too much.  The next choice was
to have a author display name as a string and then add a string by which 
the names could be alphabetized.  (For instance, the 'auth:hefferon-j'
may have a displayname of 'Jim Hefferon' and a collatename of 
'Hefferon Jim'.  The first letter of the collate name may be used to 
subdivide author's names into groups.)

Email name and domain are separated to discourage spammers.

The date attribute, if present, gives the date on which the email address
was reported to us.  If there is a date attribute then the checked attribute
says whether we have checked the email. 
-->
<!ELEMENT authors (author)*>
<!ELEMENT author EMPTY>
<!ATTLIST author
  id          ID    #REQUIRED
  familyname  CDATA #IMPLIED
  givenname   CDATA #IMPLIED
  emailname   CDATA #IMPLIED
  emaildomain CDATA #IMPLIED
  female (true|false) "false"
  died (true|false) "false">


<!ELEMENT catalogue (entry)*>
<!ATTLIST catalogue 
  maintainer CDATA #REQUIRED
  datestamp  CDATA #REQUIRED
  license    CDATA #REQUIRED>

<!-- ENTRY

The 'id' attribute is used internally to identify the entry.  It could
also serve as a sorting key, although ENTRY->ABOUT->NAME might be the
better one to sort on, since it can be any general name, as typically
what the package is known by (and is not restricted to be an XML ID,
which can not, for example, start with a numeral). 

The 'datestamp' attribute records the last time the entry was updated in
the svn database.

The 'modifier' attribute identifies the person who last updated this entry.

The 'obsolete' attribute is 'true' if the package is obsolete.

The 'withdrawn' attribute is 'true' if the package is no longer available.

TODO: The aim is to reduce the levels to one level under entry, so as
to remove ABOUT.

- -->

<!ELEMENT entry (name, caption, authorref+, uploaderref*, copyright*, 
		         home?, license+, version?, also*,
                 description*, installation_notes?,documentation*, ctan?, miktex?, texlive?, 
                 install?, keyval+)>
<!ATTLIST entry 
  id        ID    #REQUIRED
  datestamp CDATA #REQUIRED
  modifier  CDATA #IMPLIED
  obsolete   (true|false) "false"
  withdrawn  (true|false) "false" >


<!ELEMENT authorref EMPTY>
<!ATTLIST authorref id IDREFS #REQUIRED
                    active (true|false) "true">


<!-- uploaderref element
This indicates a CTAN author who is allowed to upload a package 
on behalf of the original author(s) of the package. 

Note: The original author (or one of the original authors) must confirm this 
      in an email to ctan@dante.de

   id     points to an author, who may upload on behalf of the original author(s), 
          e.g. auth:wright
   date   is the date when the original author's confirmation email arrived at 
          ctan@dante.de. Date format is: yyyy-mm-dd, e.g. 2014-01-31
   active Currently not used, set to "true" by default. 
-->
<!ELEMENT uploaderref EMPTY>
<!ATTLIST uploaderref id IDREFS #REQUIRED
		              date CDATA #REQUIRED
                      active (true|false) "true"
		              note CDATA #IMPLIED>
<!-- version element
This is that package author's version.  The 'number' attribute is a 
string.  It cannot be reliably parsed.
-->
<!ELEMENT version EMPTY>
<!ATTLIST version 
   number CDATA #IMPLIED
   date   CDATA #IMPLIED>

<!-- copyright element: 
The owner and year attributes are both unstructured strings; for instance,
year may be "1996-2005".  
-->
<!ELEMENT copyright EMPTY>
<!ATTLIST copyright
  owner CDATA #REQUIRED
  year  CDATA #REQUIRED>

<!-- LICENSE

An empty LICENSE element consists of the TYPE attribute which
indicates the type of license under which the package is available.
In general, UNKNOWN and OTHER licenses are specifically excluded from
free distributions. Please refer to
CTAN:/help/Catalogue/licenses.html, or
http://texcatalogue.ctan.org/licenses.html, for details.

The other attributes record details of the last time the license was
checked, including the date (checked="2006/06/19"), the version of the
package when the license was checked, and who checked it
(username="auth:graham").

If the TYPE is "other" then the PCDATA of the otherwise empty licence
element might provide further explanation.

The optional file attribute contains the name of the file where the license
statement has been found, like "Copyright" or "doc/README", and thus
makes checking again much easier.  The pseudo-file "header" would
indicate that there is no separate license file, but that all included
files state their license in their header comments. There is no
defined syntax for that field - you like, put anything there that
would indicate where to find the license information.

- -->

<!ELEMENT license (#PCDATA)>
<!ATTLIST license 
  type (apache2|artistic|artistic2|bsd|bsd2|bsd3|bsd4|collection|digest|fdl|gfl|gfsl
       |gpl|gpl2|gpl3
       |knuth|lgpl|lgpl2.1|lgpl3|lppl|lppl1|lppl1.2|lppl1.3|nocommercial|noinfo
       |nosell|nosource|ofl|opl|other-free|other-nonfree|pd|shareware|unknown) "unknown"
  checked  CDATA #IMPLIED
  username CDATA #IMPLIED
  version  CDATA #IMPLIED
  file     CDATA #IMPLIED
  note     CDATA #IMPLIED>


<!ELEMENT a (#PCDATA)>
<!ATTLIST a href CDATA #REQUIRED>

<!ELEMENT also (#PCDATA)>
<!ATTLIST also refid IDREFS #IMPLIED>

<!ELEMENT xref (%text;)*>
<!ATTLIST xref refid IDREFS #REQUIRED>

<!-- DOCUMENTATION

The 'href' attribute gives the location of documentation.  It takes two 
forms.  For documentation not on CTAN it is a resolvable URL.  For 
The documentation on CTAN it has the form "ctan:<path>", for instance 
"ctan:/macros/latex/contrib/shadethm/1st_read.me".

details is used to describe the type of documentation. It might be:
  Examples
  Package documentation

- --> 

<!ELEMENT documentation (#PCDATA)>
<!ATTLIST documentation
  href     CDATA #REQUIRED
  details  CDATA #IMPLIED
  %language;>


<!-- home element
The 'href' attribute gives the URL of the home location of the package,
e.g., a sourceforge project page that perhaps includes development versions.
-->
<!ELEMENT home EMPTY>
<!ATTLIST home href CDATA #REQUIRED>

<!-- DESCRIPTION

We would like to avoid too much, if any, HTML markup in the
description, as for some purposes this needs to be stripped. However,
it is useful to have some indication of markup, and so some basics are
allowed. Note that special characters, such as &lt; for < and &gt; for
> are allowed.

- -->

<!ELEMENT description (%text; | ul)*>
<!ATTLIST description
  %language;>

<!ELEMENT em       (#PCDATA)>
<!ELEMENT p        (#PCDATA)>
<!ELEMENT pre      (#PCDATA)>
<!ELEMENT tt       (#PCDATA|br|em)*>
<!ELEMENT br       EMPTY>
<!ELEMENT ul	   (li)+>
<!ELEMENT li       (%text;)*>

<!ELEMENT email    (#PCDATA)>
<!ELEMENT name     (#PCDATA)>
<!ELEMENT number   (#PCDATA)>
<!ELEMENT released (#PCDATA)>
<!ELEMENT caption  (#PCDATA)*>


<!-- INSTALLATION_NOTES

Installation_notes contains notes about anything which is an exception to
the standard installation procedure. 
This element should be used sparingly.

- -->
<!ELEMENT installation_notes (#PCDATA)>


<!-- CTAN

The path attribute can point to either a directory or an actual
file. By default it is assumed to be a directory 
(i.e. file=false). The attribute zip indicates whether the package is
archive as a zip archive on CTAN.

- -->

<!ELEMENT ctan     EMPTY>
<!ATTLIST ctan
  path       CDATA #REQUIRED
  %language;
  zip        (true|false)  "true"
  file       (true|false)  "false">

<!ELEMENT texlive  EMPTY>
<!ATTLIST texlive location CDATA #REQUIRED>

<!ELEMENT miktex   EMPTY>
<!ATTLIST miktex  location CDATA #REQUIRED>

<!-- install element: 
Present if we hold a TDS-packaged version of the material.

The 'path' attribute, if present, gives the CTAN path of the file. 
It begins with a '/', for instance, "/macros/latex/contrib/shadethm.zip".  
If not present then the material is in the standard location (for 
material whose ctan path attribute is "/a/b/c" the standard location 
is "/install/a/b/c.zip")
-->
<!ELEMENT install  EMPTY>
<!ATTLIST install path CDATA #REQUIRED>


<!-- KEYVAL (previously STATUS)

Suggested by Jim who would like to be able to store information like
   <status key='history-kept' value='true'>
This might capture those packages where an update has occurred but
CTAN saves a dated copy of the old version.  A person at home with the 
Catalogue could tell, even if they were not on the net, that the old 
version they want is available.  Further, a system could, in theory, 
come and look for it.  The CTAN web system could offer a link to 
histories on the page for that directory.

Graham suggested using "keyval" rather than "status" as "status"
implies something. However, Graham thinks it would be better to add
new elements to the DTD rather than this catch all.

Example keys

    functionality	for browsing packages by function
    archive-kept	does CTAN offer a .zip/.tar.gz of the package 

- -->

<!ELEMENT keyval EMPTY>
<!ATTLIST keyval key CDATA #REQUIRED
                 value CDATA #REQUIRED>