Anatomy of an LOL page

A given LOL page might appear so:

Everything in the document prologue, including XML declaration, whatever processing instructions you might want (including pointers to stylesheets), or an XML DOCTYPE declaration, is optional here. But of particular importance are the attributes at the top level, which are required for the processor to be able to link the page correctly both to the CSS stylesheet that controls site-wide presentation, but also the coding of internal links:

threads="../../LMNLthreads.xml": The threads document mapping the site in which this page appears.
id="LOL": Refers to the thread or knot in the threads document matching this page (by means of its @which attribute).; If this is an index page, the @id also must correspond to the directory name. Accordingly, all directory names (because expressed as@id attributes here and @which attributes in the threads document) should be legal XML local names (i.e. no spaces etc.) just to keep things simple.
class="index": This attribute is optional, but should be present with value index for documents that serve as index pages in the thread architecture (that are represented by <thread> elements in the threads document). Presently, correct internal linking, including the tables of contents, depends on this value.

Get these right and you're on your way: the links in your document will come out properly.

If a document should appear with a broken link to a stylesheet, that's an indication that the threads document is missing or broken. If it appears looking okay but with broken tables of contents, check to see whether its @id and @class are correct.

The “threads” document

An LOL page can link directly, just like HTML pages, to other pages on the web. But it can also link internally by referring to an internal specification called the “threads” document. The threads document is essentially a map of the entire site. For example, as of the time of writing, the threads document for the LMNL site looks like this:

<thread which=".">
  <label>LMNL</label>
  <thread which="prose"><label>Prose</label>
    <thread which="tutorial"><label>Tutorial</label></thread>
    <thread which="data-model"><label>Data Model</label>
      <knot which="data-model-spec"><label>Data Model Spec</label></knot>
      <knot which="reified-LMNL"><label>Reified LMNL</label></knot>
    </thread>
    <thread which="syntax"><label>Syntax</label></thread>
    <thread which="APIs"><label>APIs</label>
      <knot which="LOM-core"><label>Core LOM</label></knot>
      <knot which="LOM-reified"><label>Reified LOM</label></knot>
    </thread>
  </thread>
  <thread which="list"><label>List</label></thread>
  <thread which="projects"><label>Projects</label>
    <thread which="LMNOP"><label>LMNOP</label></thread>
    <thread which="LOL"><label>LOL</label>
      <knot which="taglibrary"><label>Tag library</label></knot>
      <knot which="menagerie"><label>Tag menagerie</label></knot>
      <knot which="getstarted"><label>Getting started</label></knot>
    </thread>
  </thread>
  <knot which="contact"><label>Contact</label></knot>
</thread>

The threads document is used for two things:

If processed by a stylesheet, the threads document serves as a driver file for a site build
When either the entire site, or an individual page in it, is generated, the threads document is traversed to provide navigation information for site-internal linking

The basic idea is pretty simple. Subdirectories within the site are represented by <thread> elements; pages linking from the subdirectories' indexes are represented by <knot> elements. <label> elements provide a short label (for tables of contents) for pages (regular pages for knots, index pages for threads). @which attributes provide a unique identifier corresponding to the directory name. So the knot with label “Getting started” will correspond to the page ./projects/LOL/getstarted.xml, and can be located to generate the appropriate link (to XML or HTML page as required) whenever necessary.

Read about the individual elements in the threads document in the Tag Library.

Getting started with LOL

An LOL XML page

Anatomy of an LOL page

The “threads” document