#!/usr/bin/python2.2
# Moshe -- current content is estimated at about 15 minutes
from slides import PRE, URL, Bullet, NumSlide, Slide, SubBullet
from twslides import Lecture

lecture = Lecture(
    "Lore: A Document Generation System",
    Slide(
        "Introduction",
        Bullet("Document generation system"),
        Bullet("Input a strict subset of XHTML"),
        Bullet("Output -- nicely formatted HTML and LaTeX"),
        Bullet("Used to generate >200 pages of Twisted documentation"),
    ),
    Slide(
        "History",
        Bullet("Twisted needed documentation -- and a format"),
        Bullet("Reluctance to add dependence on a big system"),
        Bullet("Wanted something quick and easy -- subset of HTML!"),
        Bullet("Needs matured: table of contents, printed version"),
        Bullet("Enter Lore"),
    ),
    Slide(
        "Goals",
        Bullet("Easy to use for authors"),
        Bullet("Easy to install"),
        Bullet("(Uncommon) Source format should be readable"),
    ),
    Slide(
        "Contents",
        Bullet("twisted.lore Python package"),
        Bullet("'lore' command-line program"),
        Bullet("Comes with every Twisted installation"),
        Bullet("In particular -- works on Linux, Win32, Mac"),
        Bullet("In particular -- supports Python 2.1, 2.2, 2.3 alpha"),
    ),
    Slide(
        "Alternatives - HTML",
        Bullet("Too flexible"),
        Bullet(
            "No support for needed idioms",
            SubBullet(
                Bullet("Special-purpose Python markup"),
                Bullet("Tables of contents"),
                Bullet("Inlining"),
            ),
        ),
        Bullet("Renders badly to dead trees with current tools"),
    ),
    Slide(
        "Alternatives - LaTeX",
        Bullet("Very good at printed results"),
        Bullet("Model makes alternative parsers near-impossible"),
        Bullet("Renderers to HTML are buggy and fragile"),
    ),
    Slide(
        "Alternatives - Docbook",
        Bullet(
            "Using correctly requires too much work",
            SubBullet(
                Bullet("Write a DTD with special elements"),
                Bullet("Write Jade stylesheets"),
            ),
        ),
        Bullet("Lore is probably smaller than docbook specialization"),
    ),
    Slide(
        "Alternatives - Texinfo",
        Bullet("Next slide, please"),
    ),
    Slide(
        "Lore goodies",
        Bullet(
            "Special tag to mark classes/modules/functions",
            SubBullet(Bullet("Can be made to point to auto-generated docs")),
        ),
        Bullet(
            "Inline code-examples",
            SubBullet(Bullet("No need to escape all those <, > and &")),
        ),
        Bullet("Syntax-highlight Python code"),
    ),
    Slide(
        "hlint - A lint-like program",
        Bullet("Checks for many common errors"),
        Bullet("Unhandled elements"),
        Bullet("Misspelled (or miscased) class names"),
        Bullet("Checks Python code for syntax errors"),
    ),
    Slide(
        "Extending Lore",
        Bullet("Easily done with some Python code"),
        Bullet("Input-enhancements decide which output formats to handle"),
        Bullet("Example: math-lore, Lore with LaTeX formulae"),
    ),
    Slide(
        "HTML Output",
        Bullet("HTML is a flexible output format"),
        Bullet("Documents often have to integrate with a site"),
        Bullet("Lore produces HTML documents based on a template"),
        Bullet(
            "Lore uses only HTML 'class' attributes, never 'font'",
            SubBullet(Bullet("Plays nice with CSS")),
        ),
    ),
    Slide(
        "Man Pages",
        Bullet("Lore has a program to convert man pages to Lore documents"),
        Bullet("Man pages are written anyway"),
        Bullet("No man output: the format is too limited"),
    ),
    Slide(
        "Small Example",
        PRE(
            """\
<html>
<head>
<title>Example</title>
</head>
<body>
<h1>Example</h1>
<p>Simple paragraph<span class="footnote">footnote</span></p>
</body>
</html>
"""
        ),
    ),
    Slide(
        "Future Directions",
        Bullet("More output formats"),
        Bullet("Some more classes - abstract, bibliography"),
    ),
)

lecture.renderHTML(".", "lore-%d.html", css="main.css")
