Lore: A Document Generation System
Andrew Bennetts <andrew@puzzling.org>
(Twisted Lore maintainer)
Introduction
- Document generation system
- Input format is essentially a subset of XHTML
- Outputs nicely formatted HTML and LaTeX
- Used to generate >200 pages of Twisted documentation
History
- Twisted needed documentation -- and a format
- We didn't want to depend on a big system
- The lower the barrier for documentation contributions, the
better
- We wanted something quick and easy
- Lots of people already know simple HTML
- People were already using HTML to write docs
- Our needs matured: table of contents, printable version
- So we created Lore
Goals
- Easy to use for authors
- Easy to install
- (Uncommon) Source format should be readable
Small Example
<html>
<head>
<title>Example</title>
</head>
<body>
<h1>Example</h1>
<p>Simple paragraph<span class="footnote">footnote</span></p>
</body>
</html>
Contents
- twisted.lore Python package
lore command-line program- Comes with every Twisted installation
- In particular -- works on Linux, Win32, Mac
- In particular -- supports Python 2.1, 2.2, 2.3 alpha
Alternatives - HTML
- Too flexible
- No support for needed idioms
- Special-purpose Python markup
- Tables of contents
- Inlining
- Renders badly to dead trees with current tools
Alternatives - LaTeX
- Very good at printed results
- LaTeX's design makes alternative parsers near-impossible
- Renderers to HTML are buggy and fragile
- Although the Python Standard Library seems to cope :-)
Alternatives - Docbook
- Using correctly requires too much work
- Write a DTD with special elements
- Write Jade stylesheets
- Lore is probably smaller than docbook specialization
Alternatives - Texinfo
Lore goodies
- Special tag to mark classes/modules/functions
- Can be made to point to auto-generated docs
- Inline code-examples
- No need to escape all those <, > and &
- Syntax-highlight Python code
'lore -o lint': A lint-like tool
- Checks for many common errors
- Invalid XML
- Unhandled elements
- Misspelled (or miscased) class names
- Checks Python code for syntax errors
Extending Lore
- Easily done with some Python code
- Input-enhancements decide which output formats to handle
- Example: math-lore, Lore with LaTeX formulae
Extending Lore (cont'd)
- Another example: These slides!
- The
lore-slides plugin can output to
- Magicpoint
- HTML (one page per slide)
- HTML (one big page)
HTML Output
- HTML is a flexible output format
- Documents often have to integrate with a site
- Lore produces HTML documents based on a template
- Lore uses only HTML
class attributes, never font
Man Pages
- Lore has a program to convert man pages to Lore documents
- Man pages are written anyway
- No man output: the format is too limited
Future Directions
- More output formats
- Some more classes -- abstract, bibliography
- Index