XNote 1.0

Working Draft 2001-09-02

• Author: Sean B. Palmer, <sean@mysterylights.com>
• This version: http://infomesh.net/2001/09/XNote/

Abstract

XNote 1.0 is a simple XML application that allows people to create documentation with certain special features - such as HyperText, annotations, and lists - especially for use on the World Wide Web.

Status Of This Document

This document is made available by the author as a note to the World Wide Web community. (c) Copyright 2001, Sean B. Palmer. Distribution of this document is unlimited, as long as no change whatsoever is made to the content. Citations may be made, as long as they are used in a sensible context, and include the URI and status of this working draft.

This document is based upon numerous previous works and conversations which may be lost in the mists of time. An attempt at crediting for this document is given in Appendix B.

Table Of Contents

• 1.0 Introduction
• 2.0 Attributes
• 3.0 Content Groups
• 4.0 Root Element
• 5.0 XNote Modules
• 6.0 Whitespace Considerations
• 7.0 Conformance
• Appendix A: MIME Type For XNote

1.0 Introduction

XNote 1.0 is a language created in order to fulfil the need for a lightweight, repurposable, and easily transformable XML documentation format. XHTML and WML have not, in the authors opinion, fulfilled the interoperability requirements of the World Wide Web user base. This language is not intended to replace these languages, but instead offers a base format which can be stored on servers, and then served out according to the preferences of the user.

2.0 Attributes

This specification defines two sets of attributes, "core attributes" and "main attributes".

2.1 Core Attributes

The following are the core attributes:-

id

This is an XML ID, per section x.x.x of the Extensible Markup Language specification.

xml:lang

This is a lang attribute in the default XML namespace (as defined in XML names). It alllows one to specify a natural language for an element.

xml:space

This is the space attribute in the default XML namespace (as defined in XML names). It allows one to specify the whitespace preservation characteristics of an element.

xml:base

This is the base attribute in the default XML namespace. It allows one to specify the URI base for any XLink child elements, to any level.

2.2 Main Attributes

This includes all of the "core attributes" plus:-

label

This is a generic attribute that allows one to attach additonal semantics to a set of elements depending on some sort of relationship between them which cannot be modelled due to the characteristics of the XML tree structure. It takes, as its value, an NCNAME, that concatenates with the "labelbase" attribute on <xnote> to form a URI.

3.0 Content Groups

Note that all elements may use the following set of content groups. The exact nature of these content groups will become clear when the names are defined later on in this specification. The names such as "annot" and "meta" in the following set of content groups are referred to in this specification as "modules". This is synonumous with the term "substitution group" in XML Schema, and basically consists of a set of elements which may be used.

• grp.a (annot|meta)*
• grp.b (class|list|text|media)*
• grp.class (grp.a|grp.b)*
• grp.inl (grp.a,(text|media|phrasing)*)
• grp.lst (grp.a,list|text)+)

4.0 Root Element

The root element of all conforming XNote 1.0 documents must be <xnote/> in the XNote 1.0 namespace.

• <xnote> (grp.class)

5.0 XNote Modules

The following are the set of XNote 1.0 modules; sets of elements with common semantics. They have been aranged in this modular fashion for ease of use, comprehension to people reading this specification, and for reuse by other applications.

5.1 The "annot" Module

This module contains a set of elements which may be used to annotate their enclosing elements. That is to say, these set of elements always refers to their direct parent element. @@ Unary metadata.

annot =>

<hd>, <summary>, <desc> #(grp.inl)

• <hd> - this is a title for a particular element.
• <summary> - this is a summary for a particular element.
• <desc> - this is a description for a particular element.

5.2 The "meta" Module

This module contains a set of element which may be used to add scoped metadata to their enclosing element. Again, this set of elements always refer to their direct parent element. Where the parent element is the root element, this is said to refer to the whole document.

meta =>

<data> #(annot)*

<info> (annot)*

<data> - this attaches some literal metadata with an element, &/or extra information.

<info> - this element can be used to attach a URI to a document with a predicate. Much like an RDF triple, using the parent element as the subject, the rel attribute as a predicate, and the href value as an object.

These elements may both have "rel" and "rev" attributes. These attributes may be used on a variety of other elements in this specification too. They consist of a single QName, and are used to attach a property to the metadata relationship. For "rel" the property and value are attached to the document. For "rev" the property and document are attached to ythe value, i.e. the inverse of "rel". For example:-

<xnote ...>
   <data rel="c:myproperty">My data</data>
   <info rev="c:myprop" xlink:href="http://myuri.org/"/>
</xnote>

attaches the literal data "My data" to the document using the c:myproperty QName as a QName, and the current document to the resource identified by the URI http://myuri.org/ using the property represented by the QName c:myprop.

Note that all QNames appearing in XNote attributes use an RDF style concatenation mechanism, to resolve to a URI. Hence, the following elements are exactly the same:-

<data xmlns:c="http://myuri.org/#" 
   rel="c:myprop">My data</data>
<data xmlns:c="http://myuri.org/#my" 
   rel="c:prop">My data</data>

and mean that the literal value "My data" is atached to the document using the resource identified by the URI http://myuri.org/#myprop as a property. Processors must concatenate QNames in attributes in this fashion when using them.

This specification sets out a number of special URIs for use in the rel and rev attributes.

5.3 The "class" Module

This module contains a set of elements which allow for general classification.

class =>

<sec>, <nav> (grp.class)

• <sec> - this is a general classification element for XNote.
• <nav> - delimits a part of the document which is being used entirely for navigation.

5.4 The "list" Module

This module contains a set of elements which allows one to create lists of items.

list =>

<lst>, <ol> (grp.lst)

• <lst> - delimits a list
• <ol> - delimits an ordered list

5.5 The "media" Module

This module contains elements that allow one to include multimedia into ones document. This may include any material which has a MIME type and is available as a network retrivable entity in URI space. The mechanism for including this into ones document has been specially created so that metadata is required. This ensures that users who may not be able to access content of a certain modality can access alternaitves provided in another modality, or access a repurposable markup annotation of them.

media =>

<t> (annot+,m+)
<m> (annot)*

• <t> - this element is a group of metadata and other elements intended to constitute a media object. If the pref attribute is switched to true (it's set to false by default), then the author has set out this element with childeren according to preference. This element is a lot like the <switch> element in SMIL, except that metadata is required.
• <m> - this element points to some general media for use in a <t> element.

5.6 The "text" Module

This module contains elements that allow one to use basic text forms within a document.

text =>

<par> #(grp.inl)

• <par> - this element is used to delimit basic text runs. Note that <par> elements may nest; therefore, the <par> element is not synonymous to a paragraph. However, user agents/transformations may interpret the outer <par> element as being some kind of paragraph element, and the child <par> elements as being some type of inline phrasing (perhaps dependant on a label).

5.7 The "phrasing" Module

This module contains a set of elements that allow people to add special forms of text to their basic text forms, including HyperText, emhpasis, and code markup spans.

phrasing =>

<l>, <egg>, <em>, <k>, <code>, <ruby> #(grp.inl)

• <l> - this is a simple HyperText XLink, per the XLink specification. Links may nest.
• <egg> - this forms a context for a set of links within some text.
• <em> - emphasis. Nested emphasis indicates a higher level of emphasis.
• <k> - this indicates a key part of the text, i.e. keywords or phrases that are most relevant to the flow of text.
• <code> - this delimits a portion of code, i.e. computer code of some form.
• <ruby> - is defined in the RUBY specification.

6.0 Whitespace Considerations

The following characters are defined in [XML] as whitespace characters:-

• Space (&#x0020;)
• Tab (&#x0009;)
• Carriage return (&#x000D;)
• Line feed (&#x000A;)

The XML processor normalizes different system's line end codes into one single line-feed character, that is passed up to the application. Whitespace is handled according to the following rules:-

• In elements where the "xml:space" attribute is set to "preserve", the user agent must leave all whitespace characters intact (with the exception of leading and trailing whitespace characters, which should be removed).
• All whitespace surrounding elements which may not contain #PCDATA should be removed.
• Comments do not affect whitespace handling.
• One whitespace character on either side of a comment is treated as two white space characters.
• Leading and trailing whitespace inside an element which may contain #PCDATA must be removed.
• Line feed characters within an element which may contain #PCDATA must be converted into a space (except when the "xml:space" attribute is set to "preserve").
• A sequence of white space characters must be reduced to a single space character (except when the "xml:space" attribute is set to "preserve").
• Whitespace in attribute values is processed according to [XML].

This specification makes no particular requirements as to User Agent rendering.

7.0 Conformance

A fully conforming XNote 1.0 document is one which:-

• Validates against syntax set out in the the XML Schema provided.
• Declares the root element of the doucment to be <xnote>, in the XNote 1.0 namespace.

Any document which does not meet these requirements is not a conforming instance of XNote 1.0.

Appendix A: MIME Type For XNote

No MIME type has yet been registered for XNote 1.0. We are thinking of registering something like: application/prs.xnote+xml. XNote instances served using this MIME type may be processed as XML.

Appendix B: Acknowledgements

Thanks to Aaron Swartz, William Loughborough, Dan Connolly, Murray Altheim, and Al Gilman - all of whom did not contribute directly to this draft or even endorse it, but taghut me a lot about making decent languages.

Appendix C: Notation

The notation used throughout this specification is a proprietary one, designed to get across the general structure of the language to the reader in a clear and efficient manner, basded upon DTDs. It's designed for people who can read DTDs already to pick it up more or less instantly.

The parts are not normative; the only normative content model is the XML Schema. Notwithstanding that, the patterns are the most useful thing to learn the language from and so here is a brief overview of what it means:-

• Lines consist of an element (in angular brackets), a group (starting with "grp."), or a number of these.
• The elements/groups are followed by a pattern, similar to the ones in DTDs. "?", "+" and "*" mean the same things (0 or 1 occurances, 1 or more occurances, and 0 or more occurances respectively), as do "," and "|" ("followed by" and "or" respectively).
• Patterns starting with "#" (e.g. "#(mypattern)*") may contain #PCDATA per the XML specification. Patterns for groups may not start with a "#".
• Patterns may contain elements, modules (substitution groups), or groups. Elements in the patterns do not have to have angular brackets around them.

Example:-

<a>, <b> (grp.c|(d,e,f)+)?

Element "<a>" and element "b" may contain either "grp.c", or "d" followed by "e" followed by "f" 1 or more times, 0 or 1 times.