← Back to branch summary

~ntt-pf-lab/nova/monkey_patch_notification

« back to all changes in this revision

Viewing changes to vendor/Twisted-10.0.0/doc/historic/2003/europython/lore.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/europython/lore.html
 
1
<html><head><title>Lore</title></head><body>
 
2
 
 
3
<h1>Lore</h1>
 
4
<h2>Lore - A Document Generation System</h2><ul>
 
5
<li>Gimmick -- Gilmore girls quotes</li>
 
6
 
 
7
<li>Goal - take something which is easy to write, transforms to something easy to read</li>
 
8
 
 
9
<li>For correct definitions of 'easy', of course</li>
 
10
 
 
11
</ul>
 
12
<hr />
 
13
<em>Rory (Concert Interruptus, season 1) -- Yeah, well I've always thought easy is completely overrated.</em>
 
14
<h2>Source Format</h2><ul>
 
15
<li>Subset of XHTML 1.0<ul><li>Except for some new attributes</li>
 
16
 
 
17
<li>Shouldn't bother browsers</li>
 
18
</ul></li>
 
19
 
 
20
<li>Slanted towards logical markup</li>
 
21
 
 
22
</ul>
 
23
<hr />
 
24
<em>Alex (I Solemnly Swear, season 3) -- That would've been far too logical.</em>
 
25
 
 
26
<h2>Output Formats</h2><ul>
 
27
<li>Screen and paper<ul><li>Screen - 'fancy HTML'</li>
 
28
 
 
29
<li>Paper - LaTeX<ul><li>Use LaTeX to produce PDF or PostScript</li>
 
30
</ul></li>
 
31
</ul></li>
 
32
 
 
33
</ul>
 
34
<hr />
 
35
<em>Madelaine (The Lorelais' First Day at Chilton, season 1) -- You don't know she's going out for the paper.</em>
 
36
<h2>Minimal Lore Document</h2>
 
37
<pre>
 
38
&lt;html&gt;
 
39
&lt;head&gt;&lt;title&gt;Title&lt;/title&gt;&lt;/head&gt;
 
40
&lt;body&gt;&lt;h1&gt;Title&lt;/h1&gt;&lt;/body&gt;
 
41
&lt;/html&gt;</pre>
 
42
 
 
43
<hr />
 
44
<em>Luke (There's the Rub, season 2) -- You said minimal</em>
 
45
<h2>Minimal Lore Document Explained</h2><ul>
 
46
<li>title element in head -- a must</li>
 
47
 
 
48
<li>h1 element in head -- a must<ul><li>Must have same content</li>
 
49
</ul></li>
 
50
 
 
51
</ul>
 
52
<hr />
 
53
<em>Tom (There's the Rub, season 2) -- Hey, this is minimal</em>
 
54
<h2>External Listings</h2><ul>
 
55
<li>Advantage -- no need to quote</li>
 
56
 
 
57
<li>Advantage -- test your examples</li>
 
58
 
 
59
<li>Example:<ul><li><code>&lt;a class="python-listing" href="/usr/lib/python2.2/os.py"&gt;os.py&lt;/a&gt;</code>
 
60
</li>
 
61
</ul></li>
 
62
 
 
63
</ul>
 
64
<hr />
 
65
<em>Kirk (Red Light on the Wedding Night, season 2) -- I include it as an example of the excellence I aspire to.</em>
 
66
<h2>Using Lore to Generate HTML</h2><ul>
 
67
<li>Write template</li>
 
68
 
 
69
<li>[optional] Write stylesheet</li>
 
70
 
 
71
<li>Run lore</li>
 
72
 
 
73
</ul>
 
74
<hr />
 
75
<em>Paris (Run Away, Little Boy, season 2) -- I went on the web and found this site</em>
 
76
<h2>Generating LaTeX</h2><ul>
 
77
<li>lore -olatex file.html --&gt; produces file.tex</li>
 
78
 
 
79
<li>Default is to create an 'article'</li>
 
80
 
 
81
<li>Creating PostScript<ul><li>latex file.tex</li>
 
82
 
 
83
<li>latex file.tex</li>
 
84
 
 
85
<li>dvips -o file.ps file.dvi</li>
 
86
</ul></li>
 
87
 
 
88
<li>Creating PDF<li>latex file.tex</li>
 
89
<li>pdflatex file.tex</li>
 
90
</li>
 
91
 
 
92
</ul>
 
93
<hr />
 
94
<em>Rory (Christopher Returns, season 1) -- He had already printed like a million</em>
 
95
<h2>Using Lint</h2><ul>
 
96
<li>lore -olint doc/howto/*.html</li>
 
97
 
 
98
<li>lore -n -olint doc/howto/*.html #no output except warnings</li>
 
99
 
 
100
</ul>
 
101
<hr />
 
102
<em>Max (The Deer-Hunters, season 1) -- I know a D seems pretty dismal</em>
 
103
<h2>Further Reading</h2><ul>
 
104
<li>Man page -- doc/man/lore.xhtml</li>
 
105
 
 
106
<li>Howto -- doc/howto/lore.xhtml</li>
 
107
 
 
108
<li>Extending howto -- doc/howto/extending-lore.xhtml</li>
 
109
 
 
110
<li>Documentation standard -- doc/howto/doc-standard.xhtml</li>
 
111
 
 
112
<li>Lore paper -- doc/historic/2003/pycon/lore/lore.html</li>
 
113
 
 
114
</ul>
 
115
<hr />
 
116
<em>Paris (The Bracebridge Dinner, season 2) -- Rereading the Iliad a third time is not not doing anything</em>
 
117
<h2>Questions?</h2>
 
118
<em>Lorelai (Forgiveness and Stuff, season 1) -- A person needs details.</em>
 
119
<h2>Bonus Slides</h2>
 
120
<em>Miss James (The Lorelais' First Day at Chilton, season 1) -- If you do it in Latin you get extra credit.</em>
 
121
<h2>Lore Alternatives - LaTeX</h2><ul>
 
122
<li>Very good at printed results</li>
 
123
 
 
124
<li>Model makes alternative parsers near-impossible</li>
 
125
 
 
126
<li>Renderers to HTML are buggy and fragile</li>
 
127
 
 
128
<li>People find it hard to use</li>
 
129
 
 
130
</ul>
 
131
<hr />
 
132
<em>Michel (Love, Daisies and Troubadors, season 1) -- It increases my ennui</em>
 
133
<h2>Lore Alternatives - HTML</h2><ul>
 
134
<li>Too flexible</li>
 
135
 
 
136
<li>No support for needed idioms<ul><li>Special-purpose Python markup</li>
 
137
 
 
138
<li>Tables of contents</li>
 
139
 
 
140
<li>Inlining</li>
 
141
 
 
142
<li>Footnotes</li>
 
143
</ul></li>
 
144
 
 
145
<li>Renders badly to dead trees with current tools</li>
 
146
 
 
147
</ul>
 
148
<hr />
 
149
<em>Lorelai (Love, Daisies and Troubadors, season 1) -- It was broken [...] I'm not crazy</em>
 
150
<h2>Lore Alternatives - Docbook</h2><ul>
 
151
<li>Using correctly requires too much work<ul><li>Write a DTD with special elements</li>
 
152
 
 
153
<li>Write Jade stylesheets</li>
 
154
</ul></li>
 
155
 
 
156
<li>Lore is probably smaller than docbook specialisation</li>
 
157
 
 
158
<li>People find it hard to use</li>
 
159
 
 
160
</ul>
 
161
<hr />
 
162
<em>Rory (Hammers and Veils, season 2) -- What do you want me to do it?</em>
 
163
<h2>Lore Alternatives - Texinfo</h2><ul>
 
164
<li>Next slide, please</li>
 
165
 
 
166
</ul>
 
167
<hr />
 
168
<em>Man (Hammers and Veils, season 2) -- There's a ton of hurt that almost happened here.</em>
 
169
<h2>Lore Alternatives - reST</h2><ul>
 
170
<li>Completely new language (no editor support)</li>
 
171
 
 
172
<li>Hard to add new tags</li>
 
173
 
 
174
<li>No linter</li>
 
175
 
 
176
</ul>
 
177
<hr />
 
178
<em>Emily (Hammers and Veils, season 2) -- And this is what we need to discuss right now?</em>
 
179
<h2>Lore Alternatives - LyX</h2><ul>
 
180
<li>Dependent on GUI</li>
 
181
 
 
182
</ul>
 
183
<hr />
 
184
<em>Rory (Hammers and Veils, season 2) -- Well, it's just dressed up a little.</em>
 
185
<h2>Some Standard Tags -- XHTML Primer</h2><ul>
 
186
<li><code>&lt;p&gt;paragraph&lt;/p&gt;</code>
 
187
</li>
 
188
 
 
189
<li><code>&lt;em&gt;emphasis&lt;/em&gt;</code>
 
190
</li>
 
191
 
 
192
<li><code>&lt;strong&gt;strong emphasis&lt;/strong&gt;</code>
 
193
</li>
 
194
 
 
195
<li>Headers<ul><li>&lt;h2&gt;sectionheader&lt;/h2&gt;</li><li>&lt;h3&gt;subsection&lt;/h3&gt;</li></ul></li>
 
196
 
 
197
<li>Lists<ul><li>&lt;ol&gt;&lt;li&gt;ordered list item&lt;/li&gt;&lt;/ol&gt;</li><li>&lt;ul&gt;&lt;li&gt;unordered list item&lt;/li&gt;&lt;/ul&gt;</li></ul></li>
 
198
 
 
199
<li><code>&lt;img src="http://example.com/img.png" /&gt;</code>
 
200
<ul><li>Note '/' at end!</li>
 
201
</ul></li>
 
202
 
 
203
</ul>
 
204
<hr />
 
205
<em>Rory (Kiss and Tell, season 1) -- See, even a little information in your hands is dangerous.</em>
 
206
<h2>More HTML</h2><ul>
 
207
<li>Indicating authorship -- &lt;link rel="author" href="author@example.com" title="Author Name" /&gt;</li>
 
208
 
 
209
<li>Put in &lt;head&gt;</li>
 
210
 
 
211
<li>sub/sup -- subscripts, superscripts</li>
 
212
 
 
213
</ul>
 
214
<hr />
 
215
<em>Max (The Lorelais' First Day at Chilton, season 1) -- Tolstoy's favourite author, for instance, was...</em>
 
216
<h2>More HTML -- cross references</h2><ul>
 
217
<li>Label<ul><code>&lt;a name="label-name" /&gt;</code>
 
218
</ul></li>
 
219
 
 
220
<li>Reference in file<ul><li><code>&lt;a href="#label-name"&gt;reference text&lt;/a&gt;</code></li>
 
221
</ul></li>
 
222
 
 
223
<li>Reference in other file<ul><li><code>&lt;a href="file-name#label-name"&gt;reference text&lt;/a&gt;</code></li>
 
224
</ul></li>
 
225
 
 
226
<li>Refer to URL<ul><li><code>&lt;a href="http://example.com"&gt;reference text&lt;/a&gt;</code></li>
 
227
</ul></li>
 
228
 
 
229
</ul>
 
230
<hr />
 
231
<em>Christopher (Christopher Returns, season 1) -- It's just a weird reference.</em>
 
232
<h2>Special Markup</h2><ul>
 
233
<li>Things not in XHTML are done with div/span classes</li>
 
234
 
 
235
<li>&lt;div class="note"&gt;note&lt;/a&gt; -- notes</li>
 
236
 
 
237
<li>&lt;div class="doit"&gt;doit&lt;/a&gt; -- something not implemented</li>
 
238
 
 
239
<li>&lt;span class="footnote"&gt;footnote&lt;/a&gt; -- put in a footnote</li>
 
240
 
 
241
</ul>
 
242
<hr />
 
243
<em>Taylor (Take The Deviled Eggs, season 3) -- Out attention spans are gnat-like tonight</em>
 
244
<h2>API References</h2><ul>
 
245
<li><code>&lt;code class="API"&gt;urllib&lt;/code&gt;</code>
 
246
</li>
 
247
 
 
248
<li><code>&lt;code base="urllib" class="API"&gt;urlencode&lt;/code&gt;</code>
 
249
</li>
 
250
 
 
251
<li><code>&lt;code base="twisted" class="API"&gt;copyright.version&lt;/code&gt;</code>
 
252
</li>
 
253
 
 
254
</ul>
 
255
<hr />
 
256
<em>Lorelai (The Road Trip To Harvard, season 2) -- We're just kinda hanging out between classes</em>
 
257
<h2>API References Explained</h2><ul>
 
258
<li>Integrate with systems for docstring generation</li>
 
259
 
 
260
<li>Generate links to auto-generated docs</li>
 
261
 
 
262
</ul>
 
263
<hr />
 
264
<em>Luke (Love and War and Snow, season 1) -- How do you know? Do you have written documentation?</em>
 
265
<h2>Inline Listings</h2><ul>
 
266
<li>Use &lt;pre&gt;</li>
 
267
 
 
268
<li>Possible classes: python, shell, python-interpreter</li>
 
269
 
 
270
<li>Example:</li>
 
271
 
 
272
</ul>
 
273
<pre>
 
274
&lt;pre class="python"&gt;
 
275
def foo():
 
276
    return forbnicate(4)
 
277
&lt;/pre&gt;</pre>
 
278
<hr />
 
279
<em>Taylor (Take The Deviled Eggs, season 3) -- That's not even English.</em>
 
280
<h2>Inline Listings -- short</h2><ul>
 
281
<li>Use &lt;code&gt;</li>
 
282
 
 
283
<li>Possible classes: python, shell, py-signature</li>
 
284
 
 
285
<li>...and more</li>
 
286
 
 
287
</ul>
 
288
<hr />
 
289
<em>Rory (Double Date, season 1) -- It's like this weird code thing with her.</em>
 
290
<h2>Generating HTML -- writing templates</h2><ul>
 
291
<li>Templates are XHTML documents</li>
 
292
 
 
293
<li>Put in reference to stylesheet -- head is mostly kept as is</li>
 
294
 
 
295
<li>Title will be prepended to document's title</li>
 
296
 
 
297
<li>&lt;div class="toc" /&gt; will be replaced by table of contents</li>
 
298
 
 
299
<li>&lt;div class="body" /&gt; will be replaced by processed body</li>
 
300
 
 
301
</ul>
 
302
<hr />
 
303
<em>Paris (I Can't Get Started, season 2) -- How's this sound for a template?</em>
 
304
<h2>Generating HTML -- using commandline</h2><ul>
 
305
<li>Full details: the lore manpage</li>
 
306
 
 
307
<li>Basic format: lore file.html --&gt; outputs file.xhtml<ul><li>--config template=template.tpl to use different template</li>
 
308
 
 
309
<li>--config baseurl=format-string for the url of the auto-generated docstring docs</li>
 
310
</ul></li>
 
311
 
 
312
</ul>
 
313
<hr />
 
314
<em>Richard (The Third Lorelai, season 1) -- Your wish is my command.</em>
 
315
<h2>Generating HTML -- using commandline -- examples</h2><ul>
 
316
<li>lore --config template=strange.tpl foo.html</li>
 
317
 
 
318
<li>lore --docsdir doc/howto/</li>
 
319
 
 
320
<li>lore -p --docsdir doc/howto/ # use plain progress</li>
 
321
 
 
322
</ul>
 
323
<hr />
 
324
<em>Jackson (A Deep-Fried Korean Thanksgiving, season 3) -- Deep-fried cake!</em>
 
325
<h2>Generating HTML -- using commandline -- examples (cont'd)</h2><ul>
 
326
<li>lore --docsdir doc/howto/ --config baseurl=../api/%s.html</li>
 
327
 
 
328
<li>lore --ext='' foo.html # produce 'foo' as output</li>
 
329
 
 
330
</ul>
 
331
<hr />
 
332
<em>Jackson (A Deep-Fried Korean Thanksgiving, season 3) -- Deep-fried shoe!</em>
 
333
<h2>Generating HTML -- notes about stylesheets</h2><ul>
 
334
<li>Many 'class's in the output</li>
 
335
 
 
336
<li>The stylesheet Twisted uses can be used as example<ul><li>Especially the .py-src-* classes: used for syntax highlighting</li>
 
337
</ul></li>
 
338
 
 
339
</ul>
 
340
<hr />
 
341
<em>Miss Patty (Cinnamon's Wake, season 1) -- If you had a better hair style I might consider dating</em>
 
342
<h2>Generating LaTeX -- examples</h2><ul>
 
343
<li>lore -olatex --config section file.html</li>
 
344
 
 
345
<li>lore -olatex --config book file.html</li>
 
346
 
 
347
<li>lore -olatex --config section --docsdir doc/howto/</li>
 
348
 
 
349
</ul>
 
350
<hr />
 
351
<em>Luke (Hammers and Veils, season 2) -- Just an example</em>
 
352
<h2>Using Lint -- notes</h2><ul>
 
353
<li>If there is an element which lint gives a warning you disagree with: &lt;element hlint="off"&gt;mistake&lt;/element&gt;</li>
 
354
 
 
355
<li>But usually the linter is right</li>
 
356
 
 
357
<li>lint exits with non-zero status iff some document was not clean -- useful in shell scripts</li>
 
358
 
 
359
</ul>
 
360
<hr />
 
361
<em>Paris (The Deer-Hunters, season 1) -- That would be cause for concern.</em>
 
362
<h2>Understanding Lint Warnings</h2><ul>
 
363
<li>Format: file:line:column:warning</li>
 
364
 
 
365
<li>Line/column always point to start/end of element</li>
 
366
 
 
367
<li>Some justifications:<ul><li>&lt;pre&gt; with &gt;80 characters/line renders badly, both in HTML and in LaTeX</li>
 
368
</ul></li>
 
369
 
 
370
</ul>
 
371
<hr />
 
372
<em>Jess (Teach Me Tonight, season 2) -- I appreciate the warning.</em>
 
373
<h2>Using Lore For Slides</h2><ul>
 
374
<li>lore -ilore-slides -omgp file.html for magic point</li>
 
375
 
 
376
<li>lore -ilore-slides -oprosper file.html for prosper</li>
 
377
 
 
378
<li>lore -ilore-slides -ohtml file.html for HTML next/prev</li>
 
379
 
 
380
<li>Splits on 'h2'</li>
 
381
 
 
382
<li>Dogfooding</li>
 
383
 
 
384
</ul>
 
385
<hr />
 
386
<em>Emily (Road Trip to Harvard, season 2) -- Why in the world do you insist on taking slides?</em>
 
387
<h2>Extending Lore</h2><ul>
 
388
<li>Accept more input tags</li>
 
389
 
 
390
<li>Change how documents are processed</li>
 
391
 
 
392
<li>Add more output formats</li>
 
393
 
 
394
</ul>
 
395
<hr />
 
396
<em>Rory (The Lorelais' First Day at Chilton, season 1) -- Well, add a couple of plaid skirts</em>
 
397
<h2>Extending Lore -- example</h2><ul>
 
398
<li>We want to add a way to blink: &lt;span class="blink"&gt;</li>
 
399
 
 
400
<li>Modify HTML output</li>
 
401
 
 
402
<li>Modify lint output</li>
 
403
 
 
404
<li>Make it 'small caps' in LaTeX</li>
 
405
 
 
406
<li>Distribute as package 'blinker'</li>
 
407
 
 
408
</ul>
 
409
<hr />
 
410
<em>Lorelai (Presenting Lorelai Gilmore, season 2) -- No, no, if you wanna do it, I'll help. It's just weird.</em>
 
411
<h2>Extending Lore -- example (cont'd)</h2>
 
412
<pre>
 
413
# blinker/html.py
 
414
from twisted.lore import tree
 
415
from twisted.web import microdom, domhelpers
 
416
 
 
417
def doBlink(document):
 
418
    for node in domhelpers.findElementsWithAttribute(document, 'class',
 
419
                                                    'blink'):
 
420
        newNode = microdom.Element('blink')
 
421
        newNode.children = node.children
 
422
        node.parentNode.replaceChild(newNode, node)
 
423
 
 
424
def doFile(fn, docsdir, ext, url, templ, linkrel=''):
 
425
    doc = tree.parseFileAndReport(fn)
 
426
    doBlink(doc)
 
427
    cn = templ.cloneNode(1)
 
428
    tree.munge(doc, cn, linkrel, docsdir, fn, ext, url)
 
429
    cn.writexml(open(os.path.splitext(fn)[0]+ext, 'wb'))
 
430
</pre>
 
431
 
 
432
<hr />
 
433
<em>Christopher (Presenting Lorelai Gilmore, season 2) -- I can't believe you're letting her do it.</em>
 
434
<h2>Extending Lore -- example (cont'd 2)</h2>
 
435
<pre>
 
436
# blinker/latex.py
 
437
class BlinkerLatexSpitter(latex.LatexSpitter):
 
438
 
 
439
    def visitNode_span_blink(self, node):
 
440
        self.writer('{\sc ')
 
441
        self.visitNodeDefault(node)
 
442
        self.writer('}')
 
443
</pre>
 
444
 
 
445
<hr />
 
446
<em>Lorelai (Presenting Lorelai Gilmore, season 2) -- I'm sorry, I meant what scenario on my planet</em>
 
447
<h2>Extending Lore -- example (cont'd 3)</h2>
 
448
<pre>
 
449
# blinker/factory.py
 
450
from blinker import html, latex
 
451
from twisted.lore import default
 
452
 
 
453
class ProcessingFunctionFactory(default.ProcessingFunctionFactory):
 
454
 
 
455
    doFile = [doFile]
 
456
 
 
457
    latexSpitters = {None: latex.BlinkLatexSpitter}
 
458
 
 
459
    def getLintChecker(self):
 
460
        checker = lint.getDefaultChecker()
 
461
        checker.allowedClasses = checker.allowedClasses.copy()
 
462
        oldSpan = checker.allowedClasses['span']
 
463
        checker.allowedClasses['span'] = (lambda x:oldSpan(x) or
 
464
                                                     x=='blink')
 
465
        return checker
 
466
 
 
467
factory = ProcessingFunctionFactory()
 
468
</pre>
 
469
<pre>
 
470
# blinker/plugins.tml
 
471
register("Blink-Lore",
 
472
         "blinker.factory",
 
473
         description="Lore format with blink",
 
474
         type="lore",
 
475
         tapname="blinklore")
 
476
</pre>
 
477
<p>...and that's it!</p>
 
478
 
 
479
<hr />
 
480
<em>Rory (Presenting Lorelai Gilmore, season 2) -- Sorry, we haven't tamed my wild ways yet.</em>
 
481
<h2>Man page support</h2><ul>
 
482
<li>No output</li>
 
483
 
 
484
<li>Man-&gt;Lore conversion</li>
 
485
 
 
486
<li>lore -iman -olint file.1 --&gt; generates file.html</li>
 
487
 
 
488
</ul>
 
489
<hr />
 
490
<em>Lorelai (Concert Interruptus, season 1) -- would you like to write out some sort of instruction manual to go with the dishes?</em>
 
491
<h2>Man page support</h2><ul>
 
492
<li>No output</li>
 
493
 
 
494
<li>Man-&gt;Lore conversion</li>
 
495
 
 
496
<li>lore -iman -olint file.1 --&gt; generates file.html</li>
 
497
 
 
498
</ul>
 
499
<hr />
 
500
<em>Lorelai (Concert Interruptus, season 1) -- would you like to write out some sort of instruction manual to go with the dishes?</em>
 
501
 
 
502
</body></html>