366 lines
14 KiB
HTML
366 lines
14 KiB
HTML
<?xml version="1.0" encoding="utf-8"?><!DOCTYPE html PUBLIC '-//W3C//DTD XHTML 1.0 Transitional//EN' 'http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd'><html lang="en" xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<title>Twisted Documentation: Using the Lore Documentation System</title>
|
|
<link href="stylesheet.css" rel="stylesheet" type="text/css"/>
|
|
</head>
|
|
|
|
<body bgcolor="white">
|
|
<h1 class="title">Using the Lore Documentation System</h1>
|
|
<div class="toc"><ol><li><a href="#auto0">Writing Lore Documents</a></li><ul><li><a href="#auto1">Overview</a></li><li><a href="#auto2">Elements and Their Uses</a></li></ul><li><a href="#auto3">Writing Lore XHTML Templates</a></li><li><a href="#auto4">Using Lore to Generate HTML</a></li><li><a href="#auto5">Using Lore to Generate LaTex</a></li><ul><li><a href="#auto6">Articles</a></li><li><a href="#auto7">Books</a></li></ul><li><a href="#auto8">Using Lore to Generate Slides</a></li><ul><li><a href="#auto9">Magic Point Output</a></li><li><a href="#auto10">LaTeX Output</a></li></ul><li><a href="#auto11">Linting</a></li></ol></div>
|
|
<div class="content">
|
|
<span/>
|
|
|
|
<h2>Writing Lore Documents<a name="auto0"/></h2>
|
|
|
|
<h3>Overview<a name="auto1"/></h3>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>XML documents contain elements, which are delimited by an opening tag
|
|
which looks like <code><tag-name attribute="value"></code> and ends with
|
|
a closing tag, which looks like <code></tag-name></code>. If an
|
|
elements happen to contain nothing, it can be shortened to
|
|
<code><tag-name /></code>. Elements can contain other elements, or
|
|
text. Text can contain any characters except <, > and &. These
|
|
characters are rendered by &lt;, &gt; and &amp;, respectively.</p>
|
|
|
|
<p>A Lore document is a single <code>html</code> element. Inside this element,
|
|
there are exactly two top-level elements: <code>head</code> and
|
|
<code>body</code>. The <code>head</code> element must contain exactly one
|
|
element: <code>title</code>, containing the title of the document.
|
|
Most of the document will be contained in the <code>body</code> element.
|
|
The <code>body</code> element must start with an <code>h1</code> (top-level
|
|
header) element, which contains the exact same content as the
|
|
<code>title</code> element.</p>
|
|
|
|
<p>Thus, a fairly minimal Lore document might look like:</p>
|
|
|
|
<pre xml:space="preserve">
|
|
<html>
|
|
<head><title>Title</title></head>
|
|
<body><h1>Title</h1></body>
|
|
</html>
|
|
</pre>
|
|
|
|
<h3>Elements and Their Uses<a name="auto2"/></h3>
|
|
|
|
<table border="2" cellpadding="7" cellspacing="0">
|
|
<tr>
|
|
<th colspan="1" rowspan="1">Element</th>
|
|
<th colspan="1" rowspan="1">Description</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td colspan="1" rowspan="1"><code>p</code></td>
|
|
<td colspan="1" rowspan="1">The paragraph element. Most of the document should be inside paragraphs.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td colspan="1" rowspan="1"><code>span</code></td>
|
|
<td colspan="1" rowspan="1">The span element is an element which has no meaning -- unless it has a
|
|
special <code>class</code> attributes. The following classes have the stated
|
|
meanings:
|
|
<dl>
|
|
<dt><code>footnote</code></dt>
|
|
<dd>a small comment which should not be inside the main text-flow.</dd>
|
|
<dt><code>manhole-output</code></dt>
|
|
<dd>This signifies, within a manhole transcript, that the enclosed text is
|
|
the output and not something the user has to input.</dd>
|
|
<dt><code>index</code></dt>
|
|
<dd>This should be an <em>empty</em> element, with an attribute
|
|
<code>value</code>. That attribute should be an index term, in the
|
|
format of <code>generic!specific!more specific</code>. Usually,
|
|
you will only have one level, in which case <code>value="term"</code>
|
|
works.</dd>
|
|
</dl></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td colspan="1" rowspan="1"><code>div</code></td>
|
|
<td colspan="1" rowspan="1">The div element is equivalent to a span, except it always appears outside
|
|
paragraphs. The following classes have the given meanings:
|
|
<dl>
|
|
<dt><code>note</code></dt>
|
|
<dd>A short note which is not necessary for the understanding of the text.</dd>
|
|
<dt><code>doit</code></dt>
|
|
<dd>An indication that the discussed feature is not complete or implemented
|
|
yet.</dd>
|
|
<dt><code>boxed</code></dt>
|
|
<dd>An indication that the text should be clearly separated from its
|
|
surroundings.</dd>
|
|
</dl></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td colspan="1" rowspan="1"><code>a</code></td>
|
|
<td colspan="1" rowspan="1">This element can have several meanings, depending on the attributes:
|
|
<dl>
|
|
<dt><code>name</code> attribute</dt>
|
|
<dd>Add a label to the current position, which might be used in this document
|
|
or other documents to refer to.</dd>
|
|
<dt><code>href=URL</code></dt>
|
|
<dd>Refer to some WWW resource.</dd>
|
|
<dt><code>href=relative-path</code>, <code>href=relative-path#label</code> or
|
|
<code>href=#label</code></dt>
|
|
<dd>Refer to a position in a Lore resource. By default, relative links to
|
|
<code>.xhtml</code> files are changed to point to a <code>.html</code> file.
|
|
If you need a link to a local non-Lore .xhtml file, use
|
|
<code>class=absolute</code> to make Lore treat it as an absolute link.</dd>
|
|
<dt><code>href=relative-path</code> with <code>class=py-listing</code> or
|
|
<code>class=html-listing</code></dt>
|
|
<dd>Indicate the given resource is a part of the text flow, and should be
|
|
inlined (and if possible, syntax highlighted).</dd>
|
|
</dl></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td colspan="1" rowspan="1"><code>ol</code>, <code>ul</code></td>
|
|
<td colspan="1" rowspan="1">A list. It can be enumerated or bulleted. Inside a list, the element
|
|
<code>li</code> (for a list element) is valid.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td colspan="1" rowspan="1"><code>h2</code>, <code>h3</code></td>
|
|
<td colspan="1" rowspan="1">Second- and third-level section headings.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td colspan="1" rowspan="1"><code>code</code></td>
|
|
<td colspan="1" rowspan="1">A string which has meaning to the computer. There are many possible
|
|
classes:
|
|
<dl>
|
|
<dt><code>API</code></dt>
|
|
<dd>A class, function or a module. It does not have to be a fully qualified
|
|
name -- but if it isn't, a <code>base</code> attribute is necessary.
|
|
<br/>Example:
|
|
<code><code class="API" base="urllib">urlencode<code></code>.</dd>
|
|
<dt><code>shell</code></dt>
|
|
<dd>Shell (usually Bourne) code.</dd>
|
|
<dt><code>python</code></dt>
|
|
<dd>Python code.</dd>
|
|
<dt><code>py-prototype</code></dt>
|
|
<dd>Function prototype.</dd>
|
|
<dt><code>py-filename</code></dt>
|
|
<dd>Python file.</dd>
|
|
<dt><code>py-src-string</code></dt>
|
|
<dd>Python string.</dd>
|
|
<dt><code>py-signature</code></dt>
|
|
<dd>Function signature.</dd>
|
|
<dt><code>py-src-parameter</code></dt>
|
|
<dd>Parameter.</dd>
|
|
<dt><code>py-src-identifier</code></dt>
|
|
<dd>Identifier.</dd>
|
|
<dt><code>py-src-keyword</code></dt>
|
|
<dd>Keyword.</dd>
|
|
</dl></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td colspan="1" rowspan="1"><code>pre</code></td>
|
|
<td colspan="1" rowspan="1">Preformatted text, usually for file listings. It can be used with the
|
|
<code>python</code> class to indicate Python syntax coloring. Other possible
|
|
classes are <code>shell</code> (to indicate a shell-transcript) or
|
|
<code>python-interpreter</code> (to indicate an interactive interpreter
|
|
transcript).</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td colspan="1" rowspan="1"><code>img</code></td>
|
|
<td colspan="1" rowspan="1">Insert the image indicated by the <code>src</code> attribute.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td colspan="1" rowspan="1"><code>q</code></td>
|
|
<td colspan="1" rowspan="1">The quote signs (<code>"</code>) are not recommended
|
|
except in preformatted or code environment. Instead, quote by using the
|
|
<code>q</code> element which allows nested quotes and properly distinguishes
|
|
opening quote from closing quote.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td colspan="1" rowspan="1"><code>em</code>, <code>strong</code></td>
|
|
<td colspan="1" rowspan="1">Emphasise (or strongly emphasise) text.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td colspan="1" rowspan="1"><code>table</code></td>
|
|
<td colspan="1" rowspan="1">Tabular data. Inside a table, use the <code>tr</code>
|
|
element for each rows, and inside it use either <code>td</code> for a regular
|
|
table cell or <code>th</code> for a table header (column or row).</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td colspan="1" rowspan="1"><code>blockquote</code></td>
|
|
<td colspan="1" rowspan="1">A long quote which should be properly seperated from the main text.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td colspan="1" rowspan="1"><code>cite</code></td>
|
|
<td colspan="1" rowspan="1">Cite a resource.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td colspan="1" rowspan="1"><code>sub</code>, <code>sup</code></td>
|
|
<td colspan="1" rowspan="1">Subscripts and superscripts.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td colspan="1" rowspan="1"><code>link</code></td>
|
|
<td colspan="1" rowspan="1">Currently, the only <code>link</code> elements supported
|
|
are for for indicating authorship. <code><link rel="author"
|
|
href="author-address@examples.com" title="Author Name" /></code>
|
|
should be used to indicate authorship. Multiple instances
|
|
are allowed, and indicate shared authorship.</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<h2>Writing Lore XHTML Templates<a name="auto3"/></h2>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>The output of Lore is inserted into template in the following way:</p>
|
|
|
|
<ul>
|
|
<li>The title is appended into each element with class <code>title</code>.</li>
|
|
<li>The body is inserted into the first element that has class
|
|
<code>body</code>.</li>
|
|
<li>The table of contents is inserted into the first element that has class
|
|
<code>toc</code>.</li>
|
|
</ul>
|
|
|
|
<p>In particular, most of the header is not tampered with -- so it is
|
|
easy to indicate a CSS stylesheet in the template.</p>
|
|
|
|
<h2>Using Lore to Generate HTML<a name="auto4"/></h2>
|
|
|
|
<p>After having written a template, the easiest way to build HTML from the Lore
|
|
document is by:</p>
|
|
|
|
<pre class="shell" xml:space="preserve">
|
|
% lore --config template=mytemplate.tpl mydocument.xhtml
|
|
</pre>
|
|
|
|
<p>This will create a file called <code class="shell">mydocument.html</code>.
|
|
</p>
|
|
|
|
<p>For example, to generate the HTML version of the Twisted docs from a SVN
|
|
checkout, do:</p>
|
|
|
|
<pre class="shell" xml:space="preserve">
|
|
% lore --config template=doc/howto/template.tpl doc/howto/*.xhtml
|
|
</pre>
|
|
|
|
<p>
|
|
In order to generate files with a different extension, use the <code class="shell">--config</code> commandline flag to tell the HTML output plugin to
|
|
use a different extension:
|
|
</p>
|
|
<pre class="shell" xml:space="preserve">
|
|
% lore --config ext=.html doc/howto/*.xhtml
|
|
</pre>
|
|
<h2>Using Lore to Generate LaTex<a name="auto5"/></h2>
|
|
|
|
<h3>Articles<a name="auto6"/></h3>
|
|
|
|
<pre class="shell" xml:space="preserve">
|
|
% lore --output latex mydocument.xhtml
|
|
</pre>
|
|
|
|
<h3>Books<a name="auto7"/></h3>
|
|
|
|
<p>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</p>
|
|
|
|
<pre class="shell" xml:space="preserve">
|
|
% lore --output latex --config section *.xhtml
|
|
</pre>
|
|
|
|
<p>in the relevant directory.</p>
|
|
|
|
<h2>Using Lore to Generate Slides<a name="auto8"/></h2>
|
|
|
|
<p>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</p>
|
|
|
|
<pre class="shell" xml:space="preserve">
|
|
% lore --input lore-slides myslides.xhtml
|
|
</pre>
|
|
|
|
<p>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 <code>--config
|
|
template=mytemplate.tpl</code> or the default template.tpl in the
|
|
current directory. An example slide template is found in
|
|
<code>doc/examples/slides-template.tpl</code></p>
|
|
|
|
<p>The slides module currently supports three major output types:
|
|
HTML, Magic Point, and LaTeX. The options for the latter two will be
|
|
covered individually.</p>
|
|
|
|
<h3>Magic Point Output<a name="auto9"/></h3>
|
|
|
|
<p>Lore supports outputting to the Magic Point file format.
|
|
Magicpoint is a presentation program for X, which can be installed on
|
|
Debian by <code>apt-get install mgp</code> or by visiting <a href="http://member.wide.ad.jp/wg/mgp/" shape="rect">the Magic Point homepage</a>
|
|
otherwise. A template file is required, <code>template.mgp</code> is
|
|
shipped in the <code>twisted/lore</code> directory. Magic Point
|
|
slides are generated by </p>
|
|
|
|
<pre class="shell" xml:space="preserve">
|
|
% lore --input lore-slides --output mgp \
|
|
--config template=~/Twisted/twisted/lore/template.mgp \
|
|
myslides.xhtml
|
|
</pre>
|
|
|
|
<p>That will produce <code>myslides.mgp</code>.</p>
|
|
|
|
<h3>LaTeX Output<a name="auto10"/></h3>
|
|
|
|
<p>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 <code>--config</code> parameters being <code>page</code>,
|
|
<code>twopage</code>, and <code>prosper</code> respectively. Prosper
|
|
is a LaTeX class for creating slides, which can be installed on Debian
|
|
by <code>apt-get install prosper</code> or by visiting <a href="http://sourceforge.net/projects/prosper/" shape="rect">the Prosper SourceForge page</a>.
|
|
LaTeX format slides (using the Prosper option, for example) are
|
|
generated by</p>
|
|
|
|
<pre class="shell" xml:space="preserve">
|
|
% lore --input lore-slides --output latex \
|
|
--config prosper myslides.xhtml
|
|
</pre>
|
|
|
|
<p> This will generate <code>myslides.tex</code> file that can be processed
|
|
with <code>latex</code> or <code>pdftex</code> or the appropriate
|
|
LaTeX processing command.</p>
|
|
|
|
<h2>Linting<a name="auto11"/></h2>
|
|
|
|
<pre xml:space="preserve">
|
|
% lore --output lint mydocument.xhtml
|
|
</pre>
|
|
|
|
<p>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.</p>
|
|
|
|
</div>
|
|
|
|
<p><a href="index.html">Index</a></p>
|
|
<span class="version">Version: 10.0.0</span>
|
|
</body>
|
|
</html> |