Querying the CTAN Database with XML – Package

The information about a single package can be obtained under the URL like

http://www.ctan.org/xml/1.0/pkg/tex

The last element in the URl is the key of the package as used by CTAN. Those keys are also listed in the list of packages.

The result is an XML file as in the following listing:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE entry SYSTEM 'http://www.ctan.org/xml/1.0/catalogue.dtd'>
<entry id='tex'>
  <name>TeX</name>
  <caption>A sophisticated typesetting engine</caption>
  <authorref id='knuth' />
  <copyright owner='D. E. Knuth' year='1982' />
  <license type='knuth'/>
  <version  number="3.1415926" />
  <description>
    TeX is a typesetting system that incorporates a macro processor.
    A TeX source document specifies or incorporates a number of macro
    definitions that instruct the TeX engine how to typeset the
    document.  The TeX engine also uses font metrics generated by
    Metafont, or by any of several other
    mechanisms that incorporate fonts from other sources into an
    environment suitable for TeX.
    
    TeX has been, and continues, a basis and an inspiration for
    several other programs, including e-TeX
    and PDFTeX.
    
    The distribution includes the source of Knuth’s
    TeX book; this source is there to read, as an
    example of writing TeX — it should not be processed
    without Knuth’s direct permission.
  </description>
  <ctan path='/systems/knuth/dist/tex' />
  <miktex location='miktex-tex-bin-2.9' />
  <texlive location='tex' />
  <keyval key='topic' value='engine' />
</entry>  

The entry has the outer tag <package> This tag has several attributes:

id

This attribute contains the unique id of the package. This attribute is mandatory.

<name>

The entry has the mandatory inner tag <name>. The name contains the print representation of the package name. This tag has no attributes.

<caption>

The entry has the mandatory inner tag <caption>. The caption contains a short description of the package. This tag has no attributes.

<authorref>

The entry can have zero or more the inner tags <authorref>. It carries the reference to an author. This tag has several attributes:

id

This attribute contains the id of the author. This attribute is mandatory.

givenname

This attribute contains the given name of the author. It is present only if the parameter author-name is true and the given name is known.

familyname

This attribute contains the family name of the author. It is present only if the parameter author-name is true and the family name is known.

<copyright>

The entry can have zero or more the inner tags <copyright>. It carries the information about the copyright. This tag has several attributes:

owner

This attribute contains the name of the copyright holder. This attribute is mandatory.

year

This attribute contains the year or years of the copyright. This attribute is mandatory.

<license>

The entry can have zero or more the inner tags <license>. It carries the information about the licenses under which several parts of the package are distributed. This tag has an attribute:

type

This attribute contains the key of the license to apply.

<version>

The entry has the inner tag <version>. It carries the information about the version of the package. This tag has several attributes:

number

This attribute contains the version number.

date

This attribute contains the version date.

At least one of number or date have to be given. Otherwise the tag is suppressed.

<description>

The entry has some optional inner tags <description>. The value is a longer description of the package. This description can make use of HTML for formatting. The tag may have an attribute:

lang

This attribute contains the ISO code for the language of the description.

<xref>

An inner tag of <description> is <xref>. It is used to reference a package. The tag may have an attribute:

refid

This attribute contains the reference.

<documentation>

The entry has some optional inner tags <documentation>. These tags indicate references to documentation. The tag may have attributes:

lang

This attribute contains the ISO code for the language of the description.

details

This attribute contains the (English) text describing this documentation item.

href

This attribute contains a reference to the documentation. The prefix ctan: indicates a reference to a directory on CTAN. If the parameter keep-url is true then this attribute contains always a valid URL without the ctan: prefix.

<ctan>

The entry has the optional inner tag <ctan>. It carries the location of the package in the CTAN tree. This tag has several attributes:

path

This attribute contains the relative path of the package in the CTAN tree. This attribute is mandatory.

file

This attribute contains the indicator that this package consists of a single file only. This is in contrast to a whole package directory. This attribute is optional and defaults to false.

<install>

The entry has the optional inner tag <install>. It carries the location of the package on CTAN in form of an installable TDS-compliant zip archive. This tag has several attributes:

path

This attribute contains path relative to the CTAN directory /install. This attribute is mandatory.

<miktex>

The entry has the optional inner tag <miktex>. It carries the name of the package in MiKTeX. This tag has several attributes:

location

This attribute contains name of the package in MiKTeX. This attribute is mandatory.

<texlive>

The entry has the optional inner tag <texlive>. It carries the name of the package in TeX Live. This tag has several attributes:

location

This attribute contains name of the package in TeX Live. This attribute is mandatory.

<keyval>

The entry has zero or more inner tags <keyval>. It is meant as extension point to add arbitrary key-value pairs. This tag has several attributes:

key

This attribute contains key of the key-value pair. This attribute is mandatory.

value

This attribute contains value of the key-value pair. This attribute is mandatory.

The following keys are currently in use:

topic

With this key the value contains the name of one of the topics.

index

With this key the value is also indexed for the CTAN search.

Omitting Or Enforcing the Doctype Declaration

The list of licenses may include a doctype declaration. This declaration can be suppressed with the URL parameter no-dtd which should be set to true as in

http://www.ctan.org/xml/1.0/licenses?no-dtd=true

A doctype declaration can be enforced with the URL parameter no-dtd which should be set to false in this case.

The default is no-dtd=false.

Omitting the XML Declaration

The list of licenses starts with an XML declaration. This declaration can be suppressed with the URL parameter no-xml which should be set to true as in

http://www.ctan.org/xml/1.0/licenses?no-xml=true

Expanding Author Information

The author information is contained as id referencing an entry in the authors file. If the parameter author-name can be set to true to include the first name and family name of the author as well. Example:

http://www.ctan.org/xml/1.0/pkg/tex?author-name=true

Selecting Fields

Sometimes it might be desirable to get some of the fields only. This can be accomplished with the parameter drop. It takes a comma separated list of fields to drop. Example:

http://www.ctan.org/xml/1.0/pkg/tex?drop=documentation,description

The following fields are recognized in the drop list:

author, caption, copyright, ctan, description, documentation, home, index, install, miktex, name, texlive, topic, version