<?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*, 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>

<!-- 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 the authority of the license, although I
haven't made much use of that.

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

- -->

<!ELEMENT license (#PCDATA)>
<!ATTLIST license 
  type (artistic|bsd|dfsg|gfdl|gpl|knuth|lgpl|lppl|nocommercial
       |nosell|nosource|opl|other|pd|shareware|unknown) "unknown"
  source    CDATA #IMPLIED
  authority CDATA #IMPLIED
  date      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>

<!ELEMENT documentation (#PCDATA)>
<!ATTLIST documentation href CDATA #REQUIRED>
<!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)*>

<!ELEMENT ctan     EMPTY>
<!ATTLIST ctan path CDATA #REQUIRED>
<!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>