Created: 2015-05 2017-09-09
Author: Dr. O. Hoffmann (German web-page)This module belongs to the Literature Markup Language Version 2.0
The main idea is to provide semantic information about the structure of an archive or work.
This contains only structure information and references to content documents in literature
documents and maybe other formats like raster images or SVG.
On the one hand this should be simpler than the related files in EPUB,
but the semantic information more detailed and sophisticated.
Often literature is not only one document maybe embedding some more graphics.
Media like digital books typically consist of more than one document.
Therefore there is a need to describe the relations of the contained documents and the structure of such a document relation.
A document collection here means a local group of documents of finite and known number, which can be put in an archive of type tar or zip or within a subfilesystem.
The contained documents may reference other content outside of this group as well, but such external resources are not considered as part of the collection.
Therefore within such a group or archive, there are only relative path references to other files of the collection
or absolute path references to external content, not part of the collection.
Typically the content of media like digital books is split into different documents,
containing fractions of content with a separate function and semantic meaning.
Only this needs to have a specific markup.
There is no urgent need to describe the fragments of documents by referencing fragment identifiers with the syntax defined in this section.
However, another purpose of this approach is to construct a table of content or a navigation structure
for the complete archive with direct access to all major structures.
This is possible with additional fragment identifiers for navigation in larger documents within the archive as well,
not only complete documents.
But it is expected, that there is already sufficient markup to indicate semantics within a single document.
This element collection is only intended to indicate the meaning and relation of each document of such a book
like collection or archive and to provide a navigation structure.
LML in version 1.0 has already the capability for this
within the meta
element.
The alternative approach here follows more the tradition to provide navigation directly as content information,
not as separated meta information.
To ensure automatic access to an archive and automatic detection of such an archive type, the following name structure should be used: *.lmla.?
? represents the typical archive indication like 'zip' or 'tar' or 'tgz' or 'tar.gz'
* represents the individual name part of the archive, such as 'DrOHoffmann-MyBookAboutEverything'
Examples: 'DrOHoffmann-MyBookAboutEverything.lmla.zip', 'MyBook.lmla.tar', 'AboutEverything-Hoffmann.lmla.tgz'
To indicate a subfilesystem to be of the such a type, the name of the parent directory should have the following structure: *.lmla
* represents the individual name part of the archive, such as 'DrOHoffmann-MyBookAboutEverything'
Example: 'DrOHoffmann-MyBookAboutEverything.lmla
Within an archive it is recommended to name the root document 'archive.xml'
(or 'archive.lml' if there is a media type available for LML related to such a file extension).
To ensure automatic access to the content of an archive the core archive document must have this name.
Such a root document has another functionality than normal literature documents of LML.
Instead to markup the content of a work directly, this type of document provides mainly directly displayed meta information
about the collection or archive.
Therefore it has another root element and another content model
than normal documents with literature
as root element.
Within normal literature
root element one can provide information
about other documents as well, but the approach for archives and collections is especially focused on this issue
to describe this local archive as an independent solitary digital object.
The root element for such a description of the structure of a collection is the element archive
.
Elements belonging to the content model of the archive collection belong to the type 'Archive'.
Some of the other elements, not belonging to the type 'Archive' can appear as well,
especially the element meta
is available as well for the normal collection of elements, therefore it's content is normal content as well, no special archive collection content.
The root element archive
and subelements have a content model,
described here in short notation with the following symbols and meaning:
Type: Archive
Root element for the archive collection, describing the structure of a document collection.
title
?, meta
, manifest
?, frontmatter
?, (alternative
| collection
| series
| book
| anthology
| encyclopaedia
| dictionary
| article
), backmatter
?
It is recommended to set the attribute xml:lang
on the root element,
if the complete document is in one language, respectively to set it properly on subelements,
if more than one language is used.
As for the other root element literature
is is recommended
to use the attribute version
.
Because archive
is not available in version 1.0, the value is "2.0"
for version 2.0.
Type: Attribute
The value of the attribute media
is the default media type for referenced documents.
The attribute can be used with the same meaning for all elements of the Archive type.
If an element like item
or start
directly references a document, this applies directly, else the default media type inherits to the children.
As long as there is no registered media type for LML "application/x-lml+xml" is used.
Type: Attribute
Indicate the default numbering method for titles within derived navigation list items.
Navigation list items are all subelements of a child element of an archive except meta
and manifest
.
Value 'no' (default) - no automatic numbering, if list items are not empty.
Value 'nt' numbering, first number than text from the content of the list item, typically useful,
if the content of the ah
provides information
about the content of the structure for example 'Writing Novels', this results in something like '8.2. Writing Novels'
Value 'tn' numbering, first text from the content of the list item than number, typically useful,
if the content of the list item provides only structural information like 'Chapter' or 'Section',
this results for example in 'Chapter 4.' or 'Section 7.3.'
If a list item is empty, numbering is always applied and the only heading information.
The numbering has to take into account nesting automatically,
this means, that numbering is done automatically according to the order of subelements and nesting.
For example a capitulum
is number '4.'
and a children section
is number '4.3'
a children subsection
can be '4.3.7' and so on.
The numbering method inherits to the children.
The attribute can be used with the same meaning for all elements
of the Archive type except manifest
and children.
Type: Archive
Within the manifest one can provide a complete list of documents belonging to the archive.
This can help to test, whether all content is available or not or if there is more content in the archive
as mentioned in the manifest
.
This element is optional in archive
, if not provided, creators of the archive should take care,
that especially nothing is missing and all documents in the archive are available to the audience somehow.
There is no need to mention the archive document itself, the manifest
is noted in.
manifest
is no table of content and the order of referenced documents in it is arbitrary.
This is not meaningful as a table of content, but might be used by viewers to indicate on demand,
which documents the archive contains, it can be used as well to check completeness of the archive.
Comparable to the element no
it is not directly presented within the normal flow.
item
+
manifest
Type: Archive
item
references an document within the manifest
.
Each item
needs an identifier noted in the attribute xml:id
,
if this item
is referenced by other content within the document.
The attribute link
is required.
The attribute media
is recommended, if a media type is available for the referenced document.
Empty (or alternative approach, see below)
Type: Attribute
The value of the attribute link
is a relative path to a content document of the archive collection.
Alternative approach 1: Attributes for simple links from XLink can be used as well,
especially the attribute href
.
Alternative approach 2: A content of an item
element can be an element
a
from XHTML as well.
item
Type: Archive
Indicates, that the archive is a general collection of different works without explicitly indicated relations.
Type: Archive
Indicates, that the archive contains a series of different works with some order and relation to each other.
(alternative
| book
| work
| part
| volume
| module
| article
)+
Type: Archive
Indicates, that the archive contains an anthology of different works with some order and relation to each other. The works have a common theme.
alternative
| (( work
| article
), (work
| article
)+)
An anthology
contains more than one work
or article
, therefore there have to be at least two of them as content.
Type: Archive
A series
often has different volumes.
The element volume
provides such a separation mechanism.
ah
?, (alternative
| book
|article
| work
| part
| division
| capitulum
| section
| start
| guide
| fragment
)+
Type: Archive
A work sometimes is split in modules with related, but different themes.
The element module
provides such a separation mechanism.
ah
?, (alternative
| article
| work
| part
| division
| capitulum
| section
| start
| guide
| fragment
)+
Type: Archive
Sometimes book like objects have more than one part to separate different issues or related, but different themes.
The element part
provides such a separation mechanism.
ah
?, (alternative
| article
| work
| division
| capitulum
| section
| start
| guide
| fragment
)+
Type: Archive
Indicates an independent solitary digital work within a collection
, series
, anthology
or book
.
Typically such collections contain different work
s from different authors.
Therefore one can separate such works clearly from each other.
meta
?, ah
?, (alternative
| division
| capitulum
| section
| start
| guide
| fragment
)+
Type: Archive
Indicates one complete digital book as content.
If this does appear directly as a children of the archive
,
there is no other content expected in the archive.
In such a case, the subelement meta
still is allowed, but it is
recommended to use the meta
element of the root element itself.
The same applies for the subelements ah
, frontmatter
and backmatter
.
meta
?, ah
?, frontmatter
?, (alternative
| part
| module
| work
| article
| division
| capitulum
| section
| start
| guide
| fragment
)+, backmatter
?
Type: Archive
article
is typically an independent solitary digital work with simpler substructure than a book
.
If this does appear directly as a children of the archive
,
there is no other content expected in the archive.
In such a case, the subelement meta
still is allowed, but it is
recommended to use the meta
element of the root element itself.
The same applies for the subelements ah
, frontmatter
and backmatter
.
meta
?, ah
?, frontmatter
?, (alternative
| capitulum
| section
| start
| guide
| fragment
)+, backmatter
?
Type: Archive
encyclopaedia
is for encyclopaedic content.
Typically such content consists of smaller articles without a specific order.
This is non linear content with only minimalistic further structure, however,
it is not really important, that the content is non linear, this means,
at least in classical books this is somehow ordered, for example in alphabetical order.
(alternative
| part
| article
| division
| start
| guide
| fragment
)+
Type: Archive
dictionary
is for dictionary content, for example to translate words from one language to another.
Typically such content consists of smaller articles without a specific order.
This is non linear content with only minimalistic further structure, however,
it is not really important, that the content is non linear, this means,
at least in classical books this is somehow ordered, for example in alphabetical order.
(alternative
| part
| article
| division
| start
| guide
| fragment
)+
Type: Archive
A major structural division of a work, if one level of abstraction above capitulum
is required.
ah
?, (alternative
|capitulum
| section
| start
| guide
| fragment
)+
Type: Archive
Indicates a chapter.
Type: Archive
Indicates a section.
ah
?, (alternative
| subsection
| start
| guide
| fragment
)+
Type: Archive
Indicates a subsection.
ah
?, (alternative
| subsection
| start
| guide
| fragment
)+
Type: Archive
fragment
s provide no information with of semantic relevant.
They should be only used, if no other fragmentation according to semantic structures like chapters or sections is
available. Typically one will not use single sentences or paragraphs as structures on a document level.
But if a work has no further substructure, but nevertheless has content of several hundreds of megabyte,
one may want to split this for technical reasons in two or more documents, but this splitting has not
meaning for the content itself.
To indicate such a technical splitting, fragment
can be used.
It should not be used to reflect arbitrary splitting to pages for printed books however,
this is for digital works no useful splitting at all.
If such a fragment
is done, it should be avoided to split within available structures like
paragraphs or sentences, every fragment
should contain only complete substructures like
paragraphs or sentences. Because there is no more larger structure, typically elements within such a
fragment
document are on the same abstraction level, for there are only paragraphs as
children of the element literature
.
ah
?, (alternative
| start
| guide
| fragment
)+
Type: Archive (Block)
This represents a heading or title of a substructure like a capitulum
, section
, subsection
or corresponding structures referencing content documents.
These elements can be used to generate a table of content or a structure model of the archive.
Such a title can be narrative, but it can be a numbered order as well.
For automatic numbering according to the nesting, one can add the attribute n
.
If only this numbering is required, the element can be empty as well.
Interpreted Text only.
Type: Archive
guide
provides a list of starting points into a work or a part of it.
This is especially useful for non linear works with an own navigation mechanism.
This is useful as well for a simple selection between alternatives.
The list items are alternative starting points to start reading without any preference by the order of the items.
An advanced model for alternatives is provided with the element alternative
.
guide
Type: Archive
start
indicates an item to start reading.
Non linear works may have only one start
and an internal navigation.
For linear works it is expected, that every content document is referenced with an element start
.
It is possible as well to reference fragments of documents to get them in the navigation structure.
The content of the element is a heading, with the same meaning as ah
.
Another use case for start
is, if there is some content before other substructures, for example
capitulum
content before the first section
.
In such a case one may have the first content of the capitulum
in one
document, but the section
s in other documents.
In this case start
is useful to reference the beginning of the capitulum
with the start
.
For a similar reason one may have some content of the structure after the last substructure, for example
within a capitulum
after the last section
within another element. For this one can use the start
as well.
Even more exotic will be to provide such additional content between substructure, as for example text on
the capitulum
level between to section
.
It is not discussed here, whether it is useful or not to have such a content on the same level as present substructures or not, but if required on can arrange it with this element as well.
Interpreted text or inline elements to note a heading for the referenced structure.
If empty, the parent elements has to provide text or numbering with an element ah
.
Type: Attribute
The value of the attribute link
can either reference the fragment identifier of the item
referencing the document with the chapter,
if a manifest
is provided or it can reference
with a relative path a content document of the archive collection with the chapter directly.
Alternative approach 1: Attributes for simple links from XLink can be used as well,
especially the attribute href
.
Alternative approach 2: A content of a start
element can be an element
a
from XHTML as well.
Both alternative approaches can provide navigation and hyperlinking functionality, even if LML itself is not interpreted, but XLink, respectively XHTML is. With additional styling with CSS, this can be already sufficient to provide a navigation document for the archive content.
itemref
Type: Archive
frontmatter
is related to content or meta information, in classical printed books typically provided before the normal content of the book. But this can be the preface or foreword of a book as well or a dedication and so on.
ah
?, (alternative
| matter
)+
Type: Archive
backmatter
is related to content or meta information, in classical printed books typically provided after the normal content of the book. But this can be the appendix or afterword of a book as well or a registry and so on.
ah
?, (alternative
| matter
)+
Type: Archive
matter
references content for frontmatter
, respectively backmatter
.
ah
, (alternative
| section
| start
| guide
| fragment
)+
Type: Attribute
The value of the attribute type
indicates the type of matter.
Usually each type appears only once within one work.
Due to the long history and different tradition of written word, several of the values
cover similar or the same purposes, therefore often only a matter of taste how to call it,
therefore here only attribute vales, no extra elements for frontmatter
and backmatter
Only for frontmatter
it is one of the following strings:
Only for backmatter
it is one of the following strings:
Possible for both frontmatter
and backmatter
:
Type: Archive
Non linear works or those with different versions or reading, different languages need a switch between different
alternative
s or renditions.
This element allows such a switch between the different renditions.
The reason for switching is provided by the attribute alt
.
The content is intended as a list of alternatives in arbitrary order to select one item of the provided options,
the opposite to an ordered list for reading it all.
Often there is only one switching with alternative
per parent structure meaningful,
but more than one is typically not excluded.
meta
?, ah
?, rendition
, rendition
+
Type: Attribute
The value of the attribute alt
is a string for the switching condition.
Available values are:
xml:lang
on the children elements rendition
to switch.
A viewer may have an option to allow automatic selection due to the preferred language of the user,
default behaviour is manual selection however. This applies as well, if no language alternative fits to the preferences.media
on the children elements rendition
to switch.
A viewer may have an option to allow automatic selection due to the preferred core media of the user or due to interpreted media by the viewer, default behaviour is manual selection however.
This applies as well, if no media alternative fits to the preferences.meta
,
in this case both required for the alternative
and the rendition
children elementsah
,
in this case both required for the alternative
and the rendition
children elementsguide
, this means ah
or meta
of the rendition
or its content has to be explored, to get some information about the alternative.Type: Archive
An alternative rendition
of a work or fragment.
# The content is a list of elements of the same type, whatever the parent element of the parent alternative
allows for itself, except the already enabled
meta
and ah
.
This means, there has to be not more than one meta
and ah
per rendition
.
guide
to select between two alternative forms, long or short version)