Topical
=======

**Preliminary draft,  22oct2004  +chris+**

ChangeLog:

* 22oct2004  +chris+: Change `//` syntax to `/**/`. Add `/*/`.

* 19oct2004  +chris+: Allow absolute categories in documents.  Explain
merging.

* 17oct2004  +chris+: ToDo: Drop adhoc categorization, move categories
into the description file.

* 17oct2004  +chris+: Initial revision

Introduction
------------

*Topical* is a lightweight way to mark occurrences of *topics* in
documents in a simple and straightforward way.

This document will mainly discuss and describe the 
Topical core.  Information about how to add Topical meta-data to
documents can be found in the appendices.

The Basics of Topical
---------------------

Topical is based on a very simple, text-based syntax that resembles
Unix path syntax.  Each Topical description is based on the following
syntax

    description ::= topic [";" topic]*

Which is essentially a semicolon-separated list of `topic`s.

A topic is a list of `name`s that is separated by `separator`s:

    topic ::= ["/" [name | wildcard]]* "/"? description?

    absolute-topic ::= ["/" name]* "/"? description?

    name ::= ["a".."z" | "A".."Z" | "0".."9" | "-" | "_"]+

    wildcard ::= "*" | "**"

    description ::= " "+ "(" text* ")"

    text ::= " ".."'" | "*".."~"

Valid topics could be, for example:

    /programming/**/ruby

    /programming/languages/scripting/ruby (The Ruby programming language)

    object-oriented/ruby

    ruby

    /things-to-do/**/diving (Diving)

These have this semantical meaning:

`/programming/**/ruby`: The marked data is about all `ruby` subtopics
of the topic `programming`.

`/programming/languages/scripting/ruby (The Ruby programming
language)`: The marked data is about the `ruby` subtopic (with the
description "The Ruby programming language" of the subtopic
`scripting` of the subtopic `languages` of the topic `programming`.

`object-oriented/ruby`: The marked data is about the subtopic `ruby`
of any (sub)topic `object-oriented`.

`ruby`: The marked data is about all (sub)topics named `ruby`.

`/things-to-do/**/diving (Diving)`: The marked data is about any subtopic
`diving` of the topic `things-to-do`, and labeled "Diving".

In Topical, there is no need for a central specification of topics;
all descriptions will be merged into a topic-tree (see section
"Merging").  However, it is strongly recommended to implement support
for a description file, and make use of it.

Description files
-----------------

*Description files* enable users to predefine a certain taxonomy.
A description file is structured like this:

    description ::= [topic "\n" description? "\n"]*

    description ::= [" " text-line]*

    text-line ::= " ".."~"*

Which is a file with one topic per line.

The topics of a description file *do not* specify any occurrences of
topics, they just declare that certain topics exist. For example, to
create a taxonomy of programming-languages, you may want to use a
description file like this:

    /programming (Programming)
    /programming/languages (Programming languages)
    /programming/languages/scripting (Scripting languages)
    /programming/languages/compiled (Compiled languages)
    /programming/languages/object-oriented (OO languages)

    /programming/languages/object-oriented/ruby
    /programming/languages/scripting/ruby
    /programming/languages/**/ruby (The Ruby programming language)

    /programming/languages/scripting/perl (The Perl programming language)
    /programming/languages/compiled/c (The C programming language)

Note that to a Topical implementation,
`/programming/languages/scripting/ruby` and
`/programming/languages/object-oriented/ruby` *are not* the same!
However, `/programming/languages/**/ruby` can (and should) be used to
specify that the section is about both topics (and to set the name).

Merging
-------

*Merging* is the name of the process that takes several topics and
builds a topic tree of them.  In the case of merging all topics of
above description file, you would get this topic tree:

    programming (Programming)
      languages (Programming languages)
        compiled (Compiled languages)
          c (The C programming language)        
        object-oriented (OO languages)
          ruby (The Ruby programming language)
        scripting (Scripting languages)
          ruby (The Ruby programming language)
          perl (The Perl programming language)

Only absolute topics are allowed to create new topics.

Merging only gets interesting if we add a few topics: Let's say the book
"Programming Ruby" is about these topics:

    programming/**/ruby

Now, we have this topic tree:

    programming (Programming)
      languages (Programming languages)
        compiled (Compiled languages)
          c (The C programming language)        
        object-oriented (OO languages)
          ruby (The Ruby programming language)
            * Programming Ruby
        scripting (Scripting languages)
          ruby (The Ruby programming language)
            * Programming Ruby
          perl (The Perl programming language)

The tree would look quite different if we had these topics
additionally in the description file:

    /book (Books)
    /book/programming (Programming Books)
    /book/programming/ruby (Ruby books)
    /book/publisher (Book Publishers)
    /programming/languages/favorite (Favorite programming languages)
    /programming/languages/favorite/ruby

And if we add these topics:

    /book/**/ruby
    /book/publisher/addison-wesley (Addison-Wesley)

The topic tree would now be:

    programming (Programming)
      languages (Programming languages)
        compiled (Compiled languages)
          c (The C programming language)
        favorite (Favorite programming languages)
          ruby (The Ruby programming language)
            * Programming Ruby
        object-oriented (OO languages)
          ruby (The Ruby programming language)
            * Programming Ruby
        scripting (Scripting languages)
          ruby (The Ruby programming language)
            * Programming Ruby
          perl (The Perl programming language)
    book (Books)
      programming (Programming Books)
        ruby (Ruby books)
          * Programming Ruby
      publisher (Book Publishers)
        addison-wesley (Addison-Wesley)
          * Programming Ruby

(See, how `favorite/ruby` adopts the title?)

Merging is not hard, since only absolute topics are allowed to create
new topics: Simple create a list of absolute topics.  After that, go
over each topic, get all topics that match, and add the document there.


Appendix: Adding Topical descriptions to documents
--------------------------------------------------

### E-Mails

The recommended way to mark RFC2822 messages is by using an unofficial
field, for example:

    X-Topical: /programming/**/ruby
    X-Topical: /author/**/chneukirchen (Christian Neukirchen)

### (X)HTML

In (X)HTML, you have two options of marking: document-wide, or by
section.

For documents, you simply can use a `<meta>` tag in the header:

    <head>
      ...
      <meta name="topical" content="/programming/**/ruby" />
      <meta name="topical" content="/author/**/chneukirchen" />
    </head>

[FIXME: define a profile?]

Alternatively, you can use the `class=` attribute to only mark
sections of the document:

    <p class="topical /programming/**/ruby;/author/**/chneukirchen">
      ...
    </p>

It is recommended to prefix the description with `topical` to make it
easier to find it.

[FIXME: define alternative syntax for better CSS matching?]


<!--
Local Variables:
mode:text
mode:auto-fill
mode:flyspell
compile-command:"md2html topical-spec.md >topical-spec.html"
End:
-->