<?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
Sarovar 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

- -->

<!ELEMENT fullcat (authors, catalogue)>

<!ELEMENT authors (author)*>
<!ELEMENT author EMPTY>
<!ATTLIST author
  id          ID    #REQUIRED
  familyname  CDATA #IMPLIED
  givenname   CDATA #IMPLIED
  emailname   CDATA #IMPLIED
  emaildomain CDATA #IMPLIED>


<!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
and

The MODIFIER attribute is the email address or the Sarovar username 
of the person who updated it, thus the email address will be
username@users.sarovar.org

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

- -->

<!ELEMENT entry (name, caption, authorref*, copyright?, home?, 
                 license*, version?, also*,
                 description?, documentation*, ctan?, tetex?, texlive?, 
                 miktex?, keyval*)>
<!ATTLIST entry 
  id        ID    #REQUIRED
  datestamp CDATA #REQUIRED
  modifier  CDATA #IMPLIED>

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

<!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.sarovar.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 (artistic|bsd|dfsg|fdl|gfsl|gpl|gpl2|gpl3|knuth
       |lgpl|lppl|lppl1.2|lppl1.3|nocommercial
       |nosell|nosource|opl|other|pd|shareware|unknown) "unknown"
  checked  CDATA #IMPLIED
  username CDATA #IMPLIED
  version  CDATA #IMPLIED
  file     CDATA #IMPLIED>


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

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

<!ELEMENT xref (#PCDATA)>
<!ATTLIST xref refid IDREFS #REQUIRED>

<!-- DOCUMENTATION

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 CDATA #IMPLIED>
<!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 (#PCDATA|xref|em|a|p|pre)*>

<!ELEMENT em       (#PCDATA)>
<!ELEMENT p        (#PCDATA)>
<!ELEMENT pre      (#PCDATA)>

<!ELEMENT email    (#PCDATA)>
<!ELEMENT miktex   (#PCDATA)>
<!ELEMENT name     (#PCDATA)>
<!ELEMENT number   (#PCDATA)>
<!ELEMENT released (#PCDATA)>
<!ELEMENT caption  (#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
  zip        (true|false)  "true"
  file       (true|false)  "false">

<!ELEMENT tetex    EMPTY>
<!ELEMENT texlive  EMPTY>
<!ATTLIST texlive location 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>