# 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
  - Even to non-hackers

## 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

- Next slide, please

## 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`
  - Plays nice with CSS

## 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