Querying the CTAN Database with JSON – Package
The information about a single package can be obtained under the URL like
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 a JSON object as in the following listing (with line breaking and indentation for improved readability):
{"id":"tex", "name":"TeX", "caption":"A sophisticated typesetting engine", "authors":[{"id":"knuth","active":true}], "copyright":[{"owner":"D. E. Knuth","year":"1982"}], "license":"knuth", "version":{"number":"3.14159265","date":"2014-01-07"}, "descriptions":[{"description":"TeX is a typesetting system that incorporates a macro processor.\nA TeX source document specifies or incorporates a number of macro\ndefinitions that instruct the TeX engine how to typeset the\ndocument. The TeX engine also uses font metrics generated by\nMetafont, or by any of several other\nmechanisms that incorporate fonts from other sources into an\nenvironment suitable for TeX.\n\nTeX has been, and continues, a basis and an inspiration for\nseveral other programs, including e-TeX\nand PDFTeX.\n\nThe distribution includes the source of Knuth’s\nTeX book; this source is there to read, as an\nexample of writing TeX — it should not be processed\nwithout Knuth’s direct permission."], "lang":null}], "ctan":{"path":"/systems/knuth/dist/tex", "file":true}, "miktex":"miktex-tex-bin-2.9", "texlive":"tex", "topics":["engine"]}
The entry object has several attributes:
-
id
- This attribute contains the unique id of the package. This attribute is mandatory.
-
name
-
The entry has the mandatory attribute
<name>
. The name contains the print representation of the package name. -
caption
-
The entry has the mandatory attribute
<caption>
. The caption contains a short description of the package. -
authors
-
The entry has the attribute
authors
which contains a list of authors. The author is a object which has several attributes:-
id
- This attribute contains the id of the author. This attribute is mandatory.
-
title
- This attribute is the title of the author. It is optional and can be empty. The default is empty.
-
givenname
- This attribute contains the given name. It is optional and can be empty.
-
von
- This attribute is the von part of the author's name. It is usually in lower case and has values like von, van, or de. It is optional and can be empty. The default is empty.
-
familyname
- This attribute is the family name. It is optional and can be empty.
-
junior
- This attribute is the junior part of the author's name. It is usually an addition to the name like jr., sr., or a numeral like I, II, III, IV. It is optional and can be empty. The default is empty.
-
pseudonym
- This attribute is the alias name to protect the privacy of an author who requests it. It is optional and can be empty. The default is empty. In case this attribute is not empty the other name constituents are not shown.
-
female
-
This attribute is the boolean indicator that the author is
female. It is optional and can be empty. The default is
false
. -
died
- This attribute is the indicator that the author is deceased. It is optional and can be empty. The default is empty.
-
-
copyright
-
The entry can have a list-valued attribute
copyright
. It carries the information about the copyright. This list contains objects which have 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 an attribute
license
. The value can be either a string or a list of strings with keys of licenses. -
version
-
The entry has the attribute
version
. It carries the information about the version of the package. This object has several attributes:-
number
- This attribute contains the version number.
-
date
- This attribute contains the version date.
At least one of
number
ordate
have to be given. Otherwise the tag is suppressed. -
-
descriptions
-
The entry has a list of description objects. It may have
attributes:
-
description
- This attribute contains the longer description of the package. It may include HTML markup.
-
lang
-
This attribute contains the ISO code for the language of the
description. Alternately it may be
null
to indicate the default language, i.e. English.
-
-
<ref>
-
An inner tag of
<description>
is<ref>
. It is used to reference a package. The tag may have an attribute:-
refid
- This attribute contains the reference.
-
-
documentation
-
The entry has the list attribute
documentation
. The list elements indicate references to documentation. The objects 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 parameterkeep-url
is true then this attribute contains always a valid URL without thectan:
prefix.
-
-
ctan
-
The entry has the optional attribute
ctan
. It carries the location of the package in the CTAN tree. This JSON object 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 attribute
install
. It carries the location of the package on CTAN in form of an installable TDS-compliant zip archive. This JSON object has several attributes:-
path
-
This attribute contains path relative to the CTAN directory
/install
. This attribute is mandatory.
-
-
miktex
-
The entry has the optional attribute
miktex
. It carries the name of the package in MiKTeX. This JSON object has several attributes:-
location
- This attribute contains name of the package in MiKTeX. This attribute is mandatory.
-
-
texlive
-
The entry has the optional attribute
texlive
. It carries the name of the package in TeX Live. This JSON object has several attributes:-
location
- This attribute contains name of the package in TeX Live. This attribute is mandatory.
-
-
index
-
The entry has the optional attribute
index
. If present then it contains a list of extra terms to be indexed for the search. -
topics
-
The entry has the optional attribute
topics
. If present then it contains a list of topics keys for this entry. -
home
-
The entry has the optional attribute
home
. If present then it contains the URL of the home page of the package.
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:
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:
The following fields are recognized in the drop list:
-
author
,caption
,copyright
,ctan
,description
,documentation
,home
,index
,install
,miktex
,name
,texlive
,topic
,version