| By: | Lars Marius Garshol |
|---|---|
| Affiliation: | Ontopia A/S |
| Date: | $Date: 2001/07/04 13:27:24 $ |
| Version: | Version 1.1 ($Revision: 1.12 $) |
| |
This technical report defines version 1.1 of the Linear Topic Map Notation, also known as LTM. It provides both an introduction and a formal definition. A complete EBNF specification is given at the end of the document.
Please note that this document is not a formal specification from any recognized standards body, but a specification published by Ontopia, a commercial company, for the convenience of all interested parties. The specification may be taken up by some standards body at some point, but nothing suggests that this will happen soon.
Version 1.1 extends version 1.0 to provide support for constructs introduced into the topic map model by the XTM 1.0 specification. Specifically, support has been added for specifying the subject address of a topic, giving topics multiple subject indicators (instead of just one), and for writing occurrences inline in the LTM file.
Version 1.1 is completely backwards compatible with version 1.0, so that any version 1.0 file will be read correctly by LTM 1.1 processors. The opposite is, of course, not the case.
The linear topic map notation is a simple textual format for writing topic maps. Just like the XML exchange format it represents the constructs in the topic map standard as text, but unlike the XML format it is compact and simple. The notation can be written in any text editor and processed by topic map software that supports it, or converted into the XML format supported by such software.
The XML-based topic map exchange format is defined in such a way as to make it easy to comprehend for humans and to develop software for, and these purposes it fulfills very well. However, this benefit has been realized at the cost of making it awkward to read and write for humans. Now, humans were not really intended to do this, they were intended to use specialized topic map editors, which would insulate their users from the syntactical details of the exchange format.
However, there is still a need for a simple textual format that can be used to concisely and clearly express topic map constructs in emails, discussions and similar contexts. Another benefit of such a format is that it makes it easy to quickly create and maintain small topic maps for demonstration and personal purposes. This is useful while we wait for good topic map editors to be developed.
While you may find that this syntax provides you with a convenient and easy way to maintain your topic maps, please note that the only standardized forms for interchangeable topic maps remain the XTM 1.0 and ISO 13250 syntaxes.
This notation has been developed by Ontopia. Steve Pepper came up with the original idea, based on the linear notation for conceptual graphs. The notation has since been refined by Lars Marius Garshol, with input from Geir Ove Grønmo and Steve Pepper. Useful contributions from Murray Altheim are also gratefully acknowledged.
While the copyright to both this description and the format itself is held by Ontopia Ontopia reserves only the right to be recognized as the originator of the notation. Permission to use it in any way for any purpose whatsoever is hereby granted in perpetuity to all potential users.
The basis of the notation is the ability to define topics, which is done by writing the SGML or XML ID of the topic in square brackets. An example is shown below.
[ltm]
This represents a topic map consisting of a single topic that has the ID 'ltm', but no other characteristics. If you want, you can provide it with a base name and a sort name as well, as in the example below. Note that the sort name is optional.
[ltm = "The linear topic map notation";
"linear topic map notation, the"]
You can even add a display name, if you want. If you have a display name the sort name is optional, but you need two semicolons to tell the parser that the second name is a display name and not a sort name. The example below shows a topic with all three name types.
[foo = "basename"; "sortname"; "dispname"]
The topic can also be typed, if so desired. The example below adds the type 'format' to the ltm topic. Multiple type IDs can be listed after the colon, separated by whitespace, if the topic has more than just one type.
[ltm : format = "The linear topic map notation";
"linear topic map notation, the"]
Note that even if no topic with the ID 'format' is defined anywhere in the LTM file this reference will cause the topic to be created by the LTM processor. The 'format' topic will have an ID, but no other characteristics. Note also that LTM is oblivious to whitespace. You can add as much whitespace as you want anywhere (except inside strings) without having any effect on the resulting topic map.
LTM also supports providing subject indicators for topics, as shown below. The URL of the subject indicator is quoted and preceded by an '@' character. Any number of subject indicators can be given.
[ltm : format = "The linear topic map notation";
"linear topic map notation, the"
@"http://www.ontopia.net/topicmaps/ltm-tech-report.html"]
ISO 13250 only has the concept of subject identity (subject indicator in XTM 1.0), but XTM 1.0 adds to this the possibility for topics to have an addressable subject. This essentially means that in XTM 1.0 one can specify that the subject of a topic is a specific resource. This can be done in LTM 1.1 as well, and is represented using a '%' character followed by the quoted URL of the resource. An example is shown below.
[xmlspec : specification = "The XML 1.0 specification"
%"http://www.w3.org/TR/REC-xml"]
The final construct supported by LTM for topics is scoping of names. This can be done for the base name, sortname, dispname-trinity as a whole, by putting a topic ID preceded by a slash after the initial '=' character, as shown below. Multiple topic IDs are allowed, separated by whitespace.
[ltm : format = / norwegian
"Den lineære topic map-notasjonen";
"lineær topic map-notasjon, den"
@"http://www.ontopia.net/topicmaps/ltm-tech-report.html"]
Note that if this example and the previous [ltm] example were to appear in the same LTM file it would cause a single topic to be created with the union of the characteristics of these two definitions. That means that the topic would have the 'ltm' ID, the format type, the two different name sets and the given subject indicator.
Note also that there are no requirements on the order in which constructs appear in LTM files. A topic type can be used before it is defined, for example.
The LTM notation also supports defining associations. In the example below the LTM topic defined above is associated with a topic with the ID 'topic maps' by an association that has the format-for type. ('format-for' is of course the ID of the topic that types that association.)
format-for([ltm], [topic-maps])
Note the use of square brackets around the IDs. All the constructs used when defining topics can be used here, which means that it is possible to define topics with their characteristics in the associations they participate in without defining them anywhere else. The example could therefore also have been written as follows.
format-for([ltm], [topic-maps : standard = "Topic maps"])
The meaning of this example is that LTM is a serialization format for topic maps. This should perhaps be made clearer by adding association role types. The example below does this.
format-for([ltm] : format, [topic-maps] : standard)
Note that if the association role type is omitted the role type will default to the type of the topic. The rationale for this is that it is a useful shorthand for a commonly occurring construction.
LTM also supports defining occurrences. This is done using the notation shown below, where the occurrence information is given in curly braces. Three pieces of information, all of which are required, appear inside the braces, separated by commas. The first is the ID of the topic which has the occurrence, the second is the ID of the occurrence role type and the third is the locator of the occurrence in double quotes.
{ltm, specification, "http://www.ontopia.net/topicmaps/ltm-tech-report.html"}
LTM 1.1 adds support for specifying the resource data of an occurrence inline in the LTM file. This can be done as shown below.
{ltm, description, [[A simple text-based format for topic maps.]]}
Below is given a more complete example of an LTM topic map. Note that text appearing between '/*' and '*/' is comments.
/* topic types */
[format = "Format"]
[standard = "Standard"]
[organization = "Organization"]
/* association types */
[format-for = "Format for"]
[defined-by = "Defined by"]
/* occurrence types */
[specification = "Specification"]
[homepage = "Home page"]
/* topics, associations and occurrences */
[topic-maps : standard = "Topic maps"
= / fullname "ISO/IEC 13250 Topic Maps"]
{topic-maps, specification,
"http://www.y12.doe.gov/sgml/sc34/document/0129.pdf"}
[xtm : format = "XTM Syntax"]
[ltm : format = "The linear topic map notation";
"linear topic map notation, the"
@"http://www.ontopia.net/topicmaps/ltm-tech-report.html"]
{ltm, specification, "http://www.ontopia.net/topicmaps/ltm-tech-report.html"}
format-for([ltm], [topic-maps])
format-for([xtm], [topic-maps])
defined-by([ltm], [ontopia])
defined-by([xtm], [topicmaps.org])
[ontopia : organization = "Ontopia AS"]
{ontopia, homepage, "http://www.ontopia.net"}
[topicmaps.org : organization = "TopicMaps.Org"]
{topicmaps.org, homepage, "http://www.topicmaps.org"}
This section defines the LTM syntax using a formal extended BNF grammar. Lexical tokens are given either as single-quoted strings directly in the grammar, or as upper-case names of token types. The token types are defined separately further below.
topic-map ::= encoding? (topic | assoc | occur) +
encoding ::= '@' STRING
topic ::= '[' NAME (WS ':' NAME+)? (topname)* subject? indicator* ']'
subject ::= '%' STRING
indicator ::= '@' STRING
topname ::= '=' scope? basename ((';' sortname) |
(';' sortname? ';' dispname))?
scope ::= '/' NAME+
basename ::= STRING
sortname ::= STRING
dispname ::= STRING
assoc ::= NAME '(' assoc-role (',' assoc-role)* ')'
assoc-role ::= topic (':' NAME )?
occur ::= '{' occ-topic ',' occ-type ',' resource '}'
resource ::= STRING | DATA
occ-topic ::= NAME
occ-type ::= NAME
The lexical token types defined below use Perl-style regular expressions for their definitions. Note that while whitespace (represented by the WS token type) is implicitly allowed between any two tokens, it is explicitly required in the 'topic' production in the above grammar. This is to avoid problems caused by the fact that a colon is allowed in topic IDs.
NAME = [A-Za-z_][-A-Za-z_0-9.:]* COMMENT = /\*([^*]|\*[^/])*\*/ STRING = "[^"]*" DATA = \[\[(([^>]+>)*|\])\] WS = [\r\n\t ]+
The NAME token type is slightly modified compared to the definition in the XML recommendation. The colon is no longer allowed as a name start character, since otherwise a single colon could be both a name and a separator.
All tokens are case-sensitive.
All LTM files are to be processed as if they were composed of Unicode characters. Files may be in any encoding, but if that encoding is not ISO 8859-1 it should be declared using the encoding production. If the encoding declaration appears in the file it must appear at the very beginning. Support for this construct is optional, but all processors must allow it to be present and at least ignore it.
The encoding names used are those defined by IANA, which are the same as those used by XML. The IANA character encoding identifier registry can be found at http://www.isi.edu/in-notes/iana/assignments/character-sets.
Below is shown a simple example of an LTM file that uses the UTF-8 character encoding.
@"utf-8" [grove : person = "Geir Ove Grønmo"]
(The name is of course Geir Ove Grønmo, encoded in UTF-8, but viewed as if it were ISO 8859-1.)
Any topic referred to by its ID in an LTM file is considered to exist, even if it is never defined anywhere by an explicit occurrence of the topic production with that topic. All occurrences of the same topic ID are considered to be references to the same topic.
When an instance of the topic production is found, and a topic with the same ID has already been found, the two topic definitions are merged as follows:
 |
The types of the resulting topic are considered to be the union of the types found in each definition. |
|
The names of the resulting topic are considered to be the union of the names found in each definition. |
|
The subject indicators of the resulting topic are considered to be the union of the subject indicators found in each definition. |
|
More than one subject address for the topic is found, the one occurring last in the file is used. |
If two topic definitions are found which have different topic IDs, but in which the same name occurs in the same scope, no specific behaviour is guaranteed. Possible results are that the topics may be merged, that they may remain distinct and that an error may be signalled. The behaviour for topics with equal subject addresses or subject indicators but different IDs is subject to the same unpredictability.
The following topic map constructs from ISO 13250 and XTM 1.0 are not supported:
|
Scoping on individual base names, sort names and display names. (This may be added in future versions.) |
|
Variant names that are not strings. |
|
Scoping of associations, occurrences and topics. (This may be added in future versions.) |
|
The name structure of base names and variant names as defined by XTM 1.0. |
|
Facets. (ISO 13250 only.) |
|
The mnemonic string alternatives to types on various constructs. (ISO 13250 only.) |
|
Added themes. (ISO 13250.) |