From curtis@duhn.com Wed Jan 23 21:36:00 2002 From: curtis@duhn.com (Curtis Duhn) Date: Wed Jan 23 21:36:00 2002 Subject: [tocml-list] We have a list Message-ID: Ok. The list is set up. Let's make a spec. Curtis Duhn curtis@duhn.com From curtis@duhn.com Fri Jan 25 00:38:00 2002 From: curtis@duhn.com (Curtis Duhn) Date: Fri Jan 25 00:38:00 2002 Subject: [tocml-list] Identifying the TOCML file for a page Message-ID: I've been thinking about the best way for the browser to figure out what TOCML file to load as the site map for a given page. I thought about using a well known file name that the browser could look for, sort of like favicon.ico, but I decided I don't like the idea of polluting everyone's Apache logs with failed requests for sitemap.toc. Instead, it seems the right way to do it is to use HTML's LINK tag. It appears to be designed for this type of thing. Each page could link to its site map using a tag like this: When the browser sees this tag, it can go fetch the TOCML file and expand it to show the node with id="tocml.vision" as the current node. As I understand it, REV="Contents" tells the user agent that the specified URL is a table of contents that links to this page. If we use the "Contents" link-type, I'm thinking we should also encourage the TYPE="text/xml" attribute. The user agent can use this as a hint that it should go ahead an load the TOC rather than just displaying a link, which it might do for an HTML TOC. "Contents" is a predefined link type in HTML 4.0. Since its intended use is to point to a TOC file, it makes sense to use it for our purposes. There's some risk in this though, since some user agents might be expecting to find HTML at the other end of the link. If browsers have well-established and incompatible behavior for this link type, it might make sense to define our own link-type for TOCML site maps. There isn't a predefined link type for site map, so perhaps REL="map" would be appropriate. The HTML 4.0 spec does allow for author defined link-types, saying, "Authors may wish to define additional link types not described in this specification. If they do so, they should use a profile to cite the conventions used to define the link types. Please see the profile attribute of the HEAD element for more details." I whipped up a little test page with the proposed link tag above. Mozilla 0.9.7 doesn't seem to pay any attention to it. If you guys are using other browsers, can you try this link and see if your browser renders anything in response to the LINK tag? http://www.duhn.com/tocml/test.html Curtis Duhn curtis@duhn.com From curtis@duhn.com Fri Jan 25 01:24:00 2002 From: curtis@duhn.com (Curtis Duhn) Date: Fri Jan 25 01:24:00 2002 Subject: [tocml-list] TOCML Example Message-ID: I don't really like this syntax, but I wanted to get a baseline example out the door that we can work from. I don't have time to describe the semantics right now, but hopefully it's pretty straightforward. Curtis Duhn curtis@duhn.com From curtis@duhn.com Fri Jan 25 19:02:03 2002 From: curtis@duhn.com (Curtis Duhn) Date: Fri Jan 25 19:02:03 2002 Subject: [tocml-list] Interface example Message-ID: If my scattered explanations of the proposed TOCML user agent are confusing, it might help to check out the site that inspired the idea. Go to http://msdn.microsoft.com/library/ in a Microsoft IE browser (unfortunately it doesn't render with expanding trees in Mozilla) and play with the tree control on the left-hand side. A few years back when I was a Windows developer, I was continually amazed with how quickly I could find documents using this tree interface. It took a little while to get familiar with their taxonomy, but once I did, the tree control became more efficient to use than the search engine. That's really impressive when you consider that their corpus contains several gigabytes of text documents. I soon found myself craving this type of tree interface for every site I visited. It occurred to me that this could be integrated with the browser, if only there existed an XML spec that everyone could use to publish their hierarchical site maps. So I started daydreaming about TOCML. For a couple of years it fought a losing battle for brain-time against my other ideas, but for whatever reason I recently got a bug up my ass and decided to turn this idea into a spec. I'm hoping some other people will get excited about TOCML, and we can start some open-source projects that implement it. There. You now have an example interface, and a gratuitous history lesson. (Sorry about that.) Curtis Duhn curtis@duhn.com From curtis@duhn.com Sun Jan 27 23:54:00 2002 From: curtis@duhn.com (Curtis Duhn) Date: Sun Jan 27 23:54:00 2002 Subject: [tocml-list] TOCML 0.1 Draft Specification Message-ID: Here's a draft spec for TOCML 0.1. It can be found on the web site at http://www.duhn.com/tocml/specs/tocml-spec_0.1.txt Table Of Contents Markup Language TOCML Version 0.1 Specification Curtis Duhn - 1/27/2001 1. STATUS This is a pre 1.0 draft of the TOCML specification. This is not a standard and should not be used as such. Future revisions may radically change the specification in incompatible ways. This document is a product of the TOCML project, at http://www.duhn.com/tocml/. Development of this document takes place on tocml-list, which can be found at http://two.pairlist.net/mailman/listinfo/tocml-list. If you have feedback on this document, please join tocml-list and post your comments, or send them to the author at curtis@duhn.com. 2. VERSIONS The version number of the TOCML specification is in the form "x.y", where x is the major version number, and y is the minor version number. The semantics of these numbers are as follows: The minor version number will be incremented for any change that is backward compatible with all previous TOCML versions with the same major version number. This guarantees that any valid TOCML x.y document is also a valid TOCML x.y+1 document. The major version number will be incremented whenever TOCML is changed in a way that is not backward compatible with the previous TOCML version. When the major version number is incremented, the minor version number will be reset to 0. These backward compatibility rules will not be enforced until version 1.0. We reserve the right to make incompatible, and even radical changes to TOCML versions 0.x while we settle on the baseline spec. Once version 1.0 has been published, backward compatibility rules will take effect. 3. THE TOCML DOCUMENT: A TOCML document is an XML document with a top-level element of , which is described below. 3.1 Element The element is required as the top-level element of the TOCML document. It has one required attribute, "version", and two required elements, and . 3.1.1 Attribute: version The "version" attribute of indicates the version of TOCML with which this document complies. It is in the form, "x.y", where x is the major TOCML version, and y is the minor TOCML version. 3.2 Element The element is required as the first child of the element. It is intended to be a container for any information that pertains globally to the document as a whole. has no required attributes, and no required elements. may optionally contain a single element. 3.3 Element The element identifies the parent of this document. It has one required attribute, "link", which specifies the URL of a TOCML file that the TOCML processor can treat as this document's parent. If a TOCML document does not provide a element, the TOCML processor will treat this document as the root of its own tree. The TOCML processor may follow links up the tree until it finds a parentless document that it can treat as the root. 3.4 Element The element has no attributes. It must contain exactly one element, which is the root node of this file's tree. 3.5 Element The element represents a node of this document's tree. It has two required attributes, "title" and "id", and three optional attributes, "description", "link" and "children". The element may contain zero or more child elements. If a element contains no children, it is called a leaf node. If a element contains one or more children, it is called an interior node. 3.5.1 Attribute: title The required "title" attribute provides a concise title for the . While there is no limit to the length of the title attribute, authors should keep it small enough to be rendered on a single line in a tree control. TOCML processors may truncate long titles if necessary. The title should not contain any markup, since it may not be rendered using HTML. 3.5.2 Attribute: id The required "id" attribute uniquely identifies the node within its document. This allows other documents to create links to the node by ending the document's URL with a fragment consisting of # followed by the ID. The author should ensure that all IDs are unique within a TOCML document. If duplicate IDs exist within a document, TOCML processors should select the first matching node encountered. Note: I'm still on the fence about making id a required attribute. If we don't require it, documents could still link to individual nodes using XPointer syntax, but this would require all TOCML processors to be able to process XPointer fragments, which might be a little heavy for this first version. Requiring an ID calls for a little extra work on the part of the document author, but in exchange it simplifies the job of the linking author and the TOCML processor. 3.5.3 Attribute: description The optional "description" attribute may contain a longer description for the node. The TOCML processor may or may not choose to render this string, so the author shouldn't presume that the user will necessarily see it. In a Yahoo style interface, this string could be used as the node's description. In an expanding tree control interface, this description could be displayed as a tool tip when the user hovers his mouse over the node. The description should not contain any markup, since it may not be rendered using HTML. 3.5.4 Attribute: link The optional "link" attribute may contain a URL pointing to the resource associated with this node. When the user clicks on the node, the link URL will be loaded in the browser. If the node has no link attribute, the node will not load any page in the browser when clicked. 3.5.5 Attribute: children The optional "children" attribute points to a URL containing a TOCML file. If the current node's children attribute doensn't contain a "#", then the children of the root node of the designated document will be rendered as children of the current node. If the current node's children attribute contains a "#" followed by an ID, then the children of the node with a matching ID in the designated document will be rendered as children of the current node. Curtis Duhn curtis@duhn.com