← Back to branch summary

~justin-fathomdb/nova/justinsb-openstack-api-volumes

« back to all changes in this revision

Viewing changes to vendor/Twisted-10.0.0/doc/historic/2003/pycon/lore/lore-presentation

  • Committer: Jesse Andrews
  • Date: 2010-05-28 06:05:26 UTC
  • Revision ID: git-v1:bf6e6e718cdc7488e2da87b21e258ccc065fe499
initial commit

Show diffs side-by-side

added added

removed removed

Lines of Context:
vendor/Twisted-10.0.0/doc/historic/2003/pycon/lore/lore-presentation
 
1
#!/usr/bin/python2.2
 
2
# Moshe -- current content is estimated at about 15 minutes
 
3
from slides import NumSlide, Slide, Bullet, SubBullet, PRE, URL
 
4
from twslides import Lecture
 
5
 
 
6
 
 
7
lecture = Lecture(
 
8
    "Lore: A Document Generation System",
 
9
    Slide("Introduction",
 
10
          Bullet("Document generation system"),
 
11
          Bullet("Input a strict subset of XHTML"),
 
12
          Bullet("Output -- nicely formatted HTML and LaTeX"),
 
13
          Bullet("Used to generate >200 pages of Twisted documentation"),
 
14
    ),
 
15
    Slide("History",
 
16
          Bullet("Twisted needed documentation -- and a format"),
 
17
          Bullet("Reluctance to add dependence on a big system"),
 
18
          Bullet("Wanted something quick and easy -- subset of HTML!"),
 
19
          Bullet("Needs matured: table of contents, printed version"),
 
20
          Bullet("Enter Lore"),
 
21
    ),
 
22
    Slide("Goals",
 
23
          Bullet("Easy to use for authors"),
 
24
          Bullet("Easy to install"),
 
25
          Bullet("(Uncommon) Source format should be readable"),
 
26
    ),
 
27
    Slide("Contents",
 
28
          Bullet("twisted.lore Python package"),
 
29
          Bullet("'lore' command-line program"),
 
30
          Bullet("Comes with every Twisted installation"),
 
31
          Bullet("In particular -- works on Linux, Win32, Mac"),
 
32
          Bullet("In particular -- supports Python 2.1, 2.2, 2.3 alpha"),
 
33
    ),
 
34
    Slide("Alternatives - HTML",
 
35
          Bullet("Too flexible"),
 
36
          Bullet("No support for needed idioms", SubBullet(
 
37
                 Bullet("Special-purpose Python markup"),
 
38
                 Bullet("Tables of contents"),
 
39
                 Bullet("Inlining")),
 
40
          ),
 
41
          Bullet("Renders badly to dead trees with current tools"),
 
42
    ),
 
43
    Slide("Alternatives - LaTeX",
 
44
          Bullet("Very good at printed results"),
 
45
          Bullet("Model makes alternative parsers near-impossible"),
 
46
          Bullet("Renderers to HTML are buggy and fragile"),
 
47
    ),
 
48
    Slide("Alternatives - Docbook",
 
49
          Bullet("Using correctly requires too much work", SubBullet(
 
50
                 Bullet("Write a DTD with special elements"),
 
51
                 Bullet("Write Jade stylesheets"))),
 
52
          Bullet("Lore is probably smaller than docbook specialization"),
 
53
    ),
 
54
    Slide("Alternatives - Texinfo",
 
55
          Bullet("Next slide, please"),
 
56
    ),
 
57
    Slide("Lore goodies",
 
58
          Bullet("Special tag to mark classes/modules/functions", SubBullet(
 
59
                 Bullet("Can be made to point to auto-generated docs")),
 
60
          ),
 
61
          Bullet("Inline code-examples", SubBullet(
 
62
                 Bullet("No need to escape all those <, > and &")),
 
63
          ),
 
64
          Bullet("Syntax-highlight Python code"),
 
65
    ),
 
66
    Slide("hlint - A lint-like program",
 
67
          Bullet("Checks for many common errors"),
 
68
          Bullet("Unhandled elements"),
 
69
          Bullet("Misspelled (or miscased) class names"),
 
70
          Bullet("Checks Python code for syntax errors"),
 
71
    ),
 
72
    Slide("Extending Lore",
 
73
           Bullet("Easily done with some Python code"),
 
74
           Bullet("Input-enhancements decide which output formats to handle"),
 
75
           Bullet("Example: math-lore, Lore with LaTeX formulae"),
 
76
    ),
 
77
    Slide("HTML Output",
 
78
          Bullet("HTML is a flexible output format"),
 
79
          Bullet("Documents often have to integrate with a site"),
 
80
          Bullet("Lore produces HTML documents based on a template"),
 
81
          Bullet("Lore uses only HTML 'class' attributes, never 'font'",
 
82
                 SubBullet(Bullet("Plays nice with CSS")),
 
83
          ),
 
84
    ),
 
85
    Slide("Man Pages",
 
86
          Bullet("Lore has a program to convert man pages to Lore documents"),
 
87
          Bullet("Man pages are written anyway"),
 
88
          Bullet("No man output: the format is too limited"),
 
89
    ),
 
90
    Slide("Small Example",
 
91
          PRE("""\
 
92
<html>
 
93
<head>
 
94
<title>Example</title>
 
95
</head>
 
96
<body>
 
97
<h1>Example</h1>
 
98
<p>Simple paragraph<span class="footnote">footnote</span></p>
 
99
</body>
 
100
</html>
 
101
""")),
 
102
    Slide("Future Directions",
 
103
          Bullet("More output formats"),
 
104
          Bullet("Some more classes - abstract, bibliography"),
 
105
     ),
 
106
)
 
107
 
 
108
lecture.renderHTML(".", "lore-%d.html", css="main.css")