The SeeAlso Markup Language

Fredrik Lundh | May 2005

The SeeAlso Markup Language is a minimal XML dialect that can be used to generate links between different web-based documentation sets. A documentation generator can use one or more SeeAlso files to add outbound links to related documents at other sites. A documention generator can also generate SeeAlso files, for use by other sites.

(To view it another way, a SeeAlso file is a collection of trackbacks, stored in a single XML file.)

Here’s a small SeeAlso file, which contains a single link:

A larger example can be found here. Also see Generating SeeAlso Indexes for the Python Library Reference.

FIXME: Use a namespace?

Elements #

The seealso Element

This is the document root element. It can contain zero or one info element, followed by zero or more item elements.

The src attribute contains the source URI for this document. An application may use this URI to look for a newer version of the file. The src attribute is optional; if omitted, the application will have to keep track of the source location in some other way.

The info Element

This element contains information about the SeeAlso origin site, such as site name, contact addresses, etc. There are no standard subelements defined at this time, but you can use custom elements as long as they live in a distinct namespace.

Providing relevant Dublin Core properties as info subelements is encouraged.

The item Element

This element contains information for a single SeeAlso item. It should contain an href attribute that points to the associated resource.

This element can have zero or more title, excerpt, and target elements. For maximum interoperability, you should include a title and a target element for each SeeAlso item.

The title Element

The title of the SeeAlso item. An item should have at least one title. Multiple titles are allowed, but should be avoided (if used, applications are free to use any of them).

The title should contain plain text, but the em element can be used to emphasize words or phrases. No other HTML markup can be used.

The excerpt Element

An excerpt from the SeeAlso item, or any other description that is relevant. As for titles, multiple excerpts are allowed, but should be avoided (if multiple excerpts are present, applications are free to use any of them).

The excerpt should contain plain text, but the em element can be used to emphasize words or phrases. No other HTML markup can be used.

The target Element

The target resource for this SeeAlso item (that is, the resource which will link back to this item).

The target can be a URI, or use any other form relevant for the application. For example, objects in the Python standard library can be identified by a dotted path (e.g. Tkinter.Canvas.move or atexit.register).

An item should have at least one target. Multiple targets can be used, where appropriate.

FIXME: Add some mechanism to specify “target domains”? Current effbot.org samples use a target-domain attribute in the seealso element.

The em Element

This element can be used to emphasize portions of a title or excerpt. Applications are free to render emphasized portions in a suitable way (e.g. use italics), or to treat them as ordinary text.

FIXME: Put this tag in the XHTML namespace?

Using Custom Elements

Other elements can be used freely, as long as they live in a distinct namespace. You can for example use Dublin Core elements, RSS elements, or more extensive XHTML markup.

For interoperability, custom elements should be placed after the standard elements, and the document should be designed to make sense also if all custom elements are ignored.