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>
p
: The paragraph element. Most of the document should be inside
paragraphs.
span
: The span element is an element which has no meaning
-- unless it has a special class
attributes.
The following classes have the stated meanings:
footnote
manhole-output
span
value
. That attribute should be an index term, in the
format of generic!specific!more specific
. Usually,
you will only have one level, in which case value="term"
works.div
: The div element is equivalent to a span, except it always
appears outside paragraphs. The following classes have the given meanings:
note
doit
boxed
a
: This element can have several meanings, depending on
the attributes:
name
attributehref=URL
href=relative-path
, href=relative-path#label
or
href=#label
.html
files are changed to point to a .xhtml
file.
If you need a link to a local non-Lore .html file, use
class=absolute
to make Lore treat it as an absolute link.href=relative-path
with class=py-listing
or
class=html-listing
ol
, ul
: A list. It can be enumerated or
bulleted. Inside a list, the element li
(for a list element)
is valid.
h2
, h3
: Second- and third-level section
headings.
code
: a string which has meaning to the computer.
There are many possible classes:
API
base
attribute is necessary.
Example:
<code class="API" base="urllib">urlencode<code>
.shell
python
py-prototype
py-filename
py-src-string
py-signature
py-src-parameter
py-src-identifier
py-src-keyword
pre
: Preformatted text, usually for file listings. It can
be used with the python
class to indicate Python syntax coloring. Other possible classes are
shell
(to indicate a shell-transcript) or
python-interpreter
(to indicate an interactive interpreter
transcript).
img
: Insert the image indicated by the src
attribute.
q
: The quote signs ("
) are not recommended
except in preformatted or code environment. Instead, quote by using the
q
element which allows nested quotes and properly distinguishes
opening quote from closing quote.
em
, strong
: Emphasise (or strongly emphasise)
text.
table
: Tabular data. Inside a table, use the tr
element for each rows, and inside it use either td
for a regular
table cell or th
for a table header (column or row).
blockquote
: A long quote which should be properly seperated
from the main text.
cite
: Cite a resource.
sub
, sup
: subscripts and superscripts.
link
: currently, the only link
elements supported
are for for indicating authorship. <link rel="author"
href="author-address@examples.com" title="Author Name" />
should be used to indicate authorship. Multiple instances
are allowed, and indicate shared authorship.
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:
title
.body
.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.html
This will create a file called mydocument.xhtml
.
For example, to generate the HTML version of the Twisted docs from a CVS
checkout, do:See also the
admin/process-docs
script.
% lore --config template=doc/howto/template.tpl doc/howto/*.html
% lore --output latex mydocument.html
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 *.html
in the relevant directory.
% lore --output lint mydocument.html
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.