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