← Back to branch summary

~soren/nova/iptables-security-groups

« back to all changes in this revision

Viewing changes to vendor/Twisted-10.0.0/doc/historic/2003/pycon/lore/lore-slides.html

  • 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-slides.html
 
1
<html>
 
2
        <head><title>Lore: A Document Generation System</title></head>
 
3
 
 
4
        <body>
 
5
        <h1>Lore: A Document Generation System</h1>
 
6
 
 
7
    <div class="author">Andrew Bennetts &lt;andrew@puzzling.org&gt;</div>
 
8
    <div class="author">(Twisted Lore maintainer)</div>
 
9
 
 
10
    <h2>Introduction</h2>
 
11
    <ul>
 
12
          <li>Document generation system</li>
 
13
          <li>Input format is essentially a subset of XHTML</li>
 
14
          <li>Outputs nicely formatted HTML and LaTeX</li>
 
15
          <li>Used to generate &gt;200 pages of Twisted documentation</li>
 
16
    </ul>
 
17
 
 
18
    <h2>History</h2>
 
19
    <ul>
 
20
          <li>Twisted needed documentation  -- and a format</li>
 
21
          <li>We didn't want to depend on a big system
 
22
              <ul>
 
23
                  <li>The lower the barrier for documentation contributions, the
 
24
                      better</li>
 
25
              </ul>
 
26
          </li>
 
27
          <li>We wanted something quick and easy 
 
28
              <ul>
 
29
                  <li>Lots of people already know simple HTML</li>
 
30
                  <li>People were already using HTML to write docs</li>
 
31
              </ul>
 
32
          </li>
 
33
          <li>Our needs matured: table of contents, printable version</li>
 
34
          <li>So we created Lore</li>
 
35
    </ul>
 
36
 
 
37
    <h2>Goals</h2>
 
38
    <ul>
 
39
          <li>Easy to use for authors</li>
 
40
          <li>Easy to install</li>
 
41
          <li>(Uncommon) Source format should be readable
 
42
              <ul>
 
43
                  <li>Even to non-hackers</li>
 
44
              </ul>
 
45
          </li>
 
46
    </ul>
 
47
 
 
48
    <h2>Small Example</h2>
 
49
        <pre>
 
50
&lt;html&gt;
 
51
&lt;head&gt;
 
52
&lt;title&gt;Example&lt;/title&gt;
 
53
&lt;/head&gt;
 
54
&lt;body&gt;
 
55
&lt;h1&gt;Example&lt;/h1&gt;
 
56
&lt;p&gt;Simple paragraph&lt;span class="footnote"&gt;footnote&lt;/span&gt;&lt;/p&gt;
 
57
&lt;/body&gt;
 
58
&lt;/html&gt;
 
59
</pre>
 
60
 
 
61
    <h2>Contents</h2>
 
62
    <ul>
 
63
          <li>twisted.lore Python package</li>
 
64
          <li><code class="shell">lore</code> command-line program</li>
 
65
          <li>Comes with every Twisted installation</li>
 
66
          <li>In particular -- works on Linux, Win32, Mac</li>
 
67
          <li>In particular -- supports Python 2.1, 2.2, 2.3 alpha</li>
 
68
    </ul>
 
69
 
 
70
    <h2>Alternatives - HTML</h2>
 
71
    <ul>
 
72
          <li>Too flexible</li>
 
73
          <li>No support for needed idioms
 
74
                 <ul>
 
75
                 <li>Special-purpose Python markup</li>
 
76
                 <li>Tables of contents</li>
 
77
                 <li>Inlining</li>
 
78
                 </ul>
 
79
          </li>
 
80
          <li>Renders badly to dead trees with current tools</li>
 
81
    </ul>
 
82
 
 
83
    <h2>Alternatives - LaTeX</h2>
 
84
    <ul>
 
85
          <li>Very good at printed results</li>
 
86
          <li>LaTeX's design makes alternative parsers near-impossible</li>
 
87
          <li>Renderers to HTML are buggy and fragile
 
88
             <ul>
 
89
                 <li>Although the Python Standard Library seems to cope :-)</li>
 
90
            </ul>
 
91
         </li>
 
92
    </ul>
 
93
 
 
94
    <h2>Alternatives - Docbook</h2>
 
95
    <ul>
 
96
          <li>Using correctly requires too much work
 
97
             <ul>
 
98
             <li>Write a DTD with special elements</li>
 
99
             <li>Write Jade stylesheets</li>
 
100
                 </ul>
 
101
          </li>
 
102
          <li>Lore is probably smaller than docbook specialization</li>
 
103
    </ul>
 
104
 
 
105
    <h2>Alternatives - Texinfo</h2>
 
106
    <ul>
 
107
          <li>Next slide, please</li>
 
108
    </ul>
 
109
 
 
110
    <h2>Lore goodies</h2>
 
111
    <ul>
 
112
          <li>Special tag to mark classes/modules/functions
 
113
             <ul>
 
114
             <li>Can be made to point to auto-generated docs</li>
 
115
                 </ul>
 
116
          </li>
 
117
 
 
118
          <li>Inline code-examples
 
119
             <ul>
 
120
             <li>No need to escape all those &lt;, &gt; and &amp;</li>
 
121
             </ul>
 
122
          </li>
 
123
 
 
124
          <li>Syntax-highlight Python code</li>
 
125
    </ul>
 
126
 
 
127
    <h2>'lore -o lint': A lint-like tool</h2>
 
128
    <ul>
 
129
          <li>Checks for many common errors
 
130
             <ul>
 
131
              <li>Invalid XML</li>
 
132
              <li>Unhandled elements</li>
 
133
              <li>Misspelled (or miscased) class names</li>
 
134
              <li>Checks Python code for syntax errors</li>
 
135
             </ul>
 
136
          </li>
 
137
    </ul>
 
138
 
 
139
    <h2>Extending Lore</h2>
 
140
    <ul>
 
141
           <li>Easily done with some Python code</li>
 
142
           <li>Input-enhancements decide which output formats to handle</li>
 
143
           <li>Example: math-lore, Lore with LaTeX formulae</li>
 
144
    </ul>
 
145
 
 
146
    <h2>Extending Lore (cont'd)</h2>
 
147
    <div class="pause" />
 
148
    <ul>
 
149
          <li>Another example: These slides!</li>
 
150
          <li>The <code>lore-slides</code> plugin can output to
 
151
              <ul>
 
152
                  <li>Magicpoint</li>
 
153
                  <li>HTML (one page per slide)</li>
 
154
                  <li>HTML (one big page)</li>
 
155
              </ul>
 
156
          </li>
 
157
    </ul>
 
158
 
 
159
    <h2>HTML Output</h2>
 
160
    <ul>
 
161
          <li>HTML is a flexible output format</li>
 
162
          <li>Documents often have to integrate with a site</li>
 
163
          <li>Lore produces HTML documents based on a template</li>
 
164
          <li>Lore uses only HTML <code>class</code> attributes, never <code>font</code>
 
165
              <ul>
 
166
                  <li>Plays nice with CSS</li>
 
167
              </ul>
 
168
          </li>
 
169
    </ul>
 
170
 
 
171
    <h2>Man Pages</h2>
 
172
    <ul>
 
173
          <li>Lore has a program to convert man pages to Lore documents</li>
 
174
          <li>Man pages are written anyway</li>
 
175
          <li>No man output: the format is too limited</li>
 
176
    </ul>
 
177
 
 
178
    <h2>Future Directions</h2>
 
179
    <ul>
 
180
          <li>More output formats</li>
 
181
          <li>Some more classes -- abstract, bibliography</li>
 
182
          <li>Index</li>
 
183
    </ul>
 
184
 
 
185
        </body>
 
186
</html>
 
187