Lore documents are a special subset of XHTML documents. They use specific subset of XHTML, together with custom classes, to allow a wide variety of document elements, including some Python-specific ones. Lore documents, in particular, are well-formed XML documents. XML can be written using a wide variety of tools: from run of the mill editors such as vi, through editors with XML help like EMACS and ending with XML specific tools like (need name of XML editor here). Here, we will not cover the specifics of writing XML documents, except for a very broad overview.
XML documents contain elements, which are delimited by an opening
tag which looks like <tag-name attribute="value">
and ends with a closing tag, which looks
like </tag-name> . If an elements happen to contain
nothing, it can be shortened to <tag-name /> . Elements can contain other elements, or text. Text can
contain any characters except <, > and &. These characters
are rendered by <, > and &, respectively.
A Lore document is a single html element. Inside this
element, there are exactly two top-level elements: head
and body . The head element must contain
exactly one element: title , containing the title of the
document. Most of the document will be contained in
the body element. The body element must
start with an h1 (top-level header) element, which
contains the exact same content as the title element.
Thus, a fairly minimal Lore document might look like:
<html>
<head><title>Title</title></head>
<body><h1>Title</h1></body>
</html>
Element |
Description |
|---|---|
|
The paragraph element. Most of the document should be inside paragraphs. |
|
The span element is an element which has no meaning – unless it has a
special
|
|
The div element is equivalent to a span, except it always appears outside paragraphs. The following classes have the given meanings:
|
|
This element can have several meanings, depending on the attributes:
|
|
A list. It can be enumerated or bulleted. Inside a list, the
element |
|
Second- and third-level section headings. |
|
A string which has meaning to the computer. There are many possible classes:
|
|
Preformatted text, usually for file listings. It can be used with
the |
|
Insert the image indicated by the |
|
The quote signs ( |
|
Emphasise (or strongly emphasise) text. |
|
Tabular data. Inside a table, use the |
|
A long quote which should be properly separated from the main text. |
|
Cite a resource. |
|
Subscripts and superscripts. |
|
Currently, the only |
One of Lore’s output formats is XHTML. Lore itself is very markup-light, but the output XHTML is much more markup intensive. Part of the auto-generated markup is directed by a special template.
The output of Lore is inserted into template in the following way:
The title is appended into each element with class title .
The body is inserted into the first element that has class
body .
The table of contents is inserted into the first element that has class
toc .
In particular, most of the header is not tampered with – so it is easy to indicate a CSS stylesheet in the template.
After having written a template, the easiest way to build HTML from the Lore document is by:
% lore --config template=mytemplate.tpl mydocument.xhtml
This will create a file called mydocument.html .
For example, to generate the HTML version of the Twisted docs from a SVN checkout, do:
% lore --config template=doc/core/howto/template.tpl doc/core/howto/*.xhtml
In order to generate files with a different extension, use the --config commandline flag to tell the HTML output plugin to
use a different extension:
% lore --config ext=.html doc/core/howto/*.xhtml
% lore --output latex mydocument.xhtml
Have a Lore file for each section. Then, have a LaTeX file which inputs all the given LaTeX files. Generate all the LaTeX files by using
% lore --output latex --config section *.xhtml
in the relevant directory.
Lore can also be used to generate slides for presentations. The start of a new slide is indicated by use of an h2 tag, with the content between the opening and closing tags the title of the slide. Slides are generated by
% lore --input lore-slides myslides.xhtml
This, by default, will produce HTML output with one HTML file for
each slide. For our example, the files would be named
myslides-<number>.html, where number is the slide number,
starting with 0 for the title slide. Lore will look for a template
file, either indicated by the --config template=mytemplate.tpl or the default template.tpl in the
current directory. An example slide template is found
in doc/examples/slides-template.tpl
The slides module currently supports three major output types: HTML, Magic Point, and LaTeX. The options for the latter two will be covered individually.
Lore supports outputting to the Magic Point file format.
Magicpoint is a presentation program for X, which can be installed on
Debian by apt-get install mgp or by visiting the Magic Point homepage
otherwise. A template file is required, template.mgp is
shipped in the twisted/lore directory. Magic Point
slides are generated by
% lore --input lore-slides --output mgp \
--config template=~/Twisted/twisted/lore/template.mgp \
myslides.xhtml
That will produce myslides.mgp .
Lore can also produce slides in LaTeX format. It supports three
main styles: one slide per page, two per page, and Prosper format,
with the --config parameters
being page , twopage ,
and prosper respectively. Prosper is a LaTeX class for
creating slides, which can be installed on Debian by apt-get install prosper or by
visiting theProsper SourceForge page . LaTeX format slides (using the Prosper
option, for example) are generated by
% lore --input lore-slides --output latex \
--config prosper myslides.xhtml
This will generate myslides.tex file that can be processed
with latex or pdftex or the appropriate
LaTeX processing command.
% lore --output lint mydocument.xhtml
This will generate compiler-style (file:line:column:message) warnings. It is possible to integrate these warnings into a smart editor such as EMACS, but it has not been done yet.