UserPreferences

PaceXHTMLIntrospection


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 &quot;APP&quot;
     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.


CategoryProposals