Abstract
Provide a simple introspection document in an XHTML format that is machine parsable, human readable and eliminates the need for a collection document.
Status: Withdrawn
This Pace has been withdrawn in favor of PaceXHTMLIntrospection2
Rationale
The introspection documents floated thus far are not satisfactory. The old introspection format has shortcomings as noted in PaceXoXoIntrospection from which this pace steals most of its language. Having a separate collection document is a relic from when the WG was thinking that we would list members there. PaceXoXoIntrospection is better but does not have explicit parsing queues, provide richer metadata for human consumption (why else use XHTML?) or support many of the features that the working group is interested in (as per the collection documents of PaceSimplifyCollections).
Proposal
Replace Section 8 as follows, with the caveat that the editors may rename any field:
8.0 XHTML Service Document
In order for authoring to commence, a client must first discover the capabilities and locations of collections offered.
8.1
The XHTML Service Document utilizes the XMDP profile to describe the capabilities and locations of collections.
<dl class="profile"> <dt>class</dt> <dd> <p> <a rel="help" href="http://www.w3.org/TR/html401/struct/global.html#adef-class" >HTML4 definition of the 'class' attribute.</a> Values of class attributes in an XHTML document for Atom Publishing Protocol service introspection can be interpreted according to this document. The Atom Publishing Protocol will be referred to as "APP" for the remainder of this document. This document should be peppered with references to the AtomPub spec. This document is for discussion purposes only. </p> <dl> <dt id="service">service</dt> <dd> A container for the class names and relations defined in the remainder document such that they describe the service offered. </dd> <dt id="serviceTitle">serviceTitle</dt> <dd> The title of a service. </dd> <dt id="serviceDescription">serviceDescription</dt> <dd> A description of a service. </dd> <dt id="workspace">workspace</dt> <dd> A container for the class names and relations defined in the remainder of this document such that they describe one or more APP collections that can be used together (to produce a given blog or feed for instance.) </dd> <dt id="workspaceTitle">workspaceTitle</dt> <dd> The title of a workspace. </dd> <dt id="workspaceDescription">workspaceDescription</dt> <dd> A description of a workspace. </dd> <dt id="classCollection">collection</dt> <dd> A container for the class names and relations defined in the remainder of this document such that they describe an APP collection. This class can also contain itself recursively. </dd> <dt id="collectionTitle">collectionTitle</dt> <dd> The title of an APP collection. If this is not present, the title attribute of the anchor with rel='collection' will be used. If this is not present, the text of the anchor with rel='collection' will be used. </dd> <dt id="collectionDescription">collectionDescription</dt> <dd> A textual description of an APP collection. If this is not present, the text of the anchor with rel='collection' will be used. </dd> <dt id="traversal">traversal</dt> <dd> An APP "magic brackets" definition of how to traverse an APP collection. If this is not present the feed at the collection URI should indicate traversal. </dd> <dt id="memberType">memberType</dt> <dd> A member type accepted by an APP collection. </dd> </dl> </dd> <dt>rel</dt> <dd> <p> <a rel="help" href="http://www.w3.org/TR/html401/struct/links.html#adef-rel"> HTML4 definition of the 'rel' attribute.</a> </p> <dl> <dt id="relCollection">collection</dt> <dd> Indicates that the referenced resource is a APP collection. </dd> </dl> </dd> </dl>
The XOXO microformat is recommended to provide structure to XHTML Service Documents.[1]
[1] http://microformats.org/wiki/xoxo
An example XHTML Service Document might look something like the following.
<?xml version="1.0"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"> <head profile="http://example.org/xoxoProfile http://example.org/appIntrospectionProfile"> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> <title>Atom Publishing Protocol XHTML Introspection Example</title> <meta name="DC.Creator" content="Arno, Luke" /> <link rel="schema.dc" href="http://purl.org/metadata/dublin_core_elements#creator" /> <link rel="stylesheet" type="text/css" href="introspection.css" title="appIntrospection" /> <link rel="stylesheet" type="text/css" href="http://tantek.com/log/2004/undohtml.css" title="appIntrospection" /> </head> <body class="service"> <h1 class="serviceTitle"> Atom Publishing Protocol Example Service </h1> <p class="serviceDescription"> This APP services serves as an example of what XHTML introspection might look like. </p> <ol class="xoxo workspace"> <li class="collection"> <a href="http://example.org/e" rel="collection" class="collectionTitle">Entries</a> <p class="collectionDescription"> This collection holds blog entries. </p> <dl> <dt>Traverse by Date</dt> <dd> <address class="traversal"> http://example.org/e/d/{daterange} </address> </dd> <dt>Traverse by Index</dt> <dd> <address class="traversal"> http://example.org/e/{index} </address> </dd> <dt>Member Types</dt> <dd class="memberType">text</dd> <dd class="memberType">htxml</dd> <dd class="memberType">xhtml</dd> <dd class="memberType">src</dd> </dl> </li> <li class="collection"> <a href="http://example.org/c" rel="collection" class="collectionTitle">Comments</a> <p class="collectionDescription"> This collection holds comments. </p> <dl> <dt>Traverse by Date</dt> <dd> <address class="traversal"> http://example.org/c/d/{daterange} </address> </dd> <dt>Traverse by Index</dt> <dd> <address class="traversal"> http://example.org/c/{index} </address> </dd> <dt>Member Types</dt> <dd class="memberType">text</dd> <dd class="memberType">htxml</dd> <dd class="memberType">xhtml</dd> <dd class="memberType">src</dd> </dl> </li> <li class="collection"> <a href="http://example.org/m" rel="collection" class="collectionTitle">Media</a> <p class="collectionDescription"> This collection holds non-entry resources. </p> <dl> <dt>Traverse by Date</dt> <dd> <address class="traversal"> http://example.org/c/m/{daterange} </address> </dd> <dt>Traverse by Index</dt> <dd> <address class="traversal"> http://example.org/m/{index} </address> </dd> <dt>Member Types</dt> <dt class="memberType">src</dt> </dl> </li> </ol> </body> </html>
A minimal example might look like this:
<?xml version="1.0"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"> <head profile="http://example.org/appIntrospectionProfile "> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> <title> Atom Publishing Protocol Minimal XHTML Introspection Example </title> <meta name="author" content="Arno, Luke" /> </head> <body class="service"> <ol class="xoxo"> <li> <a href="http://example.org/e" rel="collection" title="Entries">Entries</a> </li> <li> <a href="http://example.org/c" rel="collection" title="Comments">Comments</a> </li> <li> <a href="http://example.org/m" rel="collection" title="Media">Media</a> </li> </ol> </body> </html>
Impacts
Notes
It may or may not be a good idea to allow collections to be recursive.