:LastChangedDate: $LastChangedDate$
:LastChangedRevision: $LastChangedRevision$
:LastChangedBy: $LastChangedBy$
Using the Lore Documentation System
===================================
Writing Lore Documents
----------------------
Overview
~~~~~~~~
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 ``
urlencode`` . |
| | |
| | ``shell`` |
| | |
| | Shell (usually Bourne) code. |
| | |
| | ``python`` |
| | |
| | Python code. |
| | |
| | ``py-prototype`` |
| | |
| | Function prototype. |
| | |
| | ``py-filename`` |
| | |
| | Python file. |
| | |
| | ``py-src-string`` |
| | |
| | Python string. |
| | |
| | ``py-signature`` |
| | |
| | Function signature. |
| | |
| | ``py-src-parameter`` |
| | |
| | Parameter. |
| | |
| | ``py-src-identifier`` |
| | |
| | Identifier. |
| | |
| | ``py-src-keyword`` |
| | |
| | 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 separated from the main text. |
+---------------------+----------------------------------------------------------------------------------------------------------------------+
| ``cite`` | Cite a resource. |
+---------------------+----------------------------------------------------------------------------------------------------------------------+
| ``sub`` , ``sup`` | Subscripts and superscripts. |
+---------------------+----------------------------------------------------------------------------------------------------------------------+
| ``link`` | Currently, the only ``link`` elements supported |
| | are for indicating authorship. ```` |
| | should be used to indicate authorship. Multiple instances |
| | are allowed, and indicate shared authorship. |
+---------------------+----------------------------------------------------------------------------------------------------------------------+
Writing Lore XHTML Templates
----------------------------
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.
Using Lore to Generate HTML
---------------------------
After having written a template, the easiest way to build HTML from the Lore
document is by:
.. code-block:: console
% 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:
.. code-block:: console
% 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:
.. code-block:: console
% lore --config ext=.html doc/core/howto/*.xhtml
Using Lore to Generate LaTex
----------------------------
Articles
~~~~~~~~
.. code-block:: console
% lore --output latex mydocument.xhtml
Books
~~~~~
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
.. code-block:: console
% lore --output latex --config section *.xhtml
in the relevant directory.
Using Lore to Generate Slides
-----------------------------
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
.. code-block:: console
% 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-.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.
Magic Point Output
~~~~~~~~~~~~~~~~~~
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
.. code-block:: console
% lore --input lore-slides --output mgp \
--config template=~/Twisted/twisted/lore/template.mgp \
myslides.xhtml
That will produce ``myslides.mgp`` .
LaTeX Output
~~~~~~~~~~~~
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
.. code-block:: console
% 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.
Linting
-------
::
% 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.