1
<html><head><title>Lore</title></head><body>
4
<h2>Lore - A Document Generation System</h2><ul>
5
<li>Gimmick -- Gilmore girls quotes</li>
7
<li>Goal - take something which is easy to write, transforms to something easy to read</li>
9
<li>For correct definitions of 'easy', of course</li>
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>
17
<li>Shouldn't bother browsers</li>
20
<li>Slanted towards logical markup</li>
24
<em>Alex (I Solemnly Swear, season 3) -- That would've been far too logical.</em>
26
<h2>Output Formats</h2><ul>
27
<li>Screen and paper<ul><li>Screen - 'fancy HTML'</li>
29
<li>Paper - LaTeX<ul><li>Use LaTeX to produce PDF or PostScript</li>
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>
39
<head><title>Title</title></head>
40
<body><h1>Title</h1></body>
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>
48
<li>h1 element in head -- a must<ul><li>Must have same content</li>
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>
57
<li>Advantage -- test your examples</li>
59
<li>Example:<ul><li><code><a class="python-listing" href="/usr/lib/python2.2/os.py">os.py</a></code>
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>
69
<li>[optional] Write stylesheet</li>
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 --> produces file.tex</li>
79
<li>Default is to create an 'article'</li>
81
<li>Creating PostScript<ul><li>latex file.tex</li>
83
<li>latex file.tex</li>
85
<li>dvips -o file.ps file.dvi</li>
88
<li>Creating PDF<li>latex file.tex</li>
89
<li>pdflatex file.tex</li>
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>
98
<li>lore -n -olint doc/howto/*.html #no output except warnings</li>
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>
106
<li>Howto -- doc/howto/lore.xhtml</li>
108
<li>Extending howto -- doc/howto/extending-lore.xhtml</li>
110
<li>Documentation standard -- doc/howto/doc-standard.xhtml</li>
112
<li>Lore paper -- doc/historic/2003/pycon/lore/lore.html</li>
116
<em>Paris (The Bracebridge Dinner, season 2) -- Rereading the Iliad a third time is not not doing anything</em>
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>
124
<li>Model makes alternative parsers near-impossible</li>
126
<li>Renderers to HTML are buggy and fragile</li>
128
<li>People find it hard to use</li>
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>
136
<li>No support for needed idioms<ul><li>Special-purpose Python markup</li>
138
<li>Tables of contents</li>
145
<li>Renders badly to dead trees with current tools</li>
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>
153
<li>Write Jade stylesheets</li>
156
<li>Lore is probably smaller than docbook specialisation</li>
158
<li>People find it hard to use</li>
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>
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>
172
<li>Hard to add new tags</li>
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>
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><p>paragraph</p></code>
189
<li><code><em>emphasis</em></code>
192
<li><code><strong>strong emphasis</strong></code>
195
<li>Headers<ul><li><h2>sectionheader</h2></li><li><h3>subsection</h3></li></ul></li>
197
<li>Lists<ul><li><ol><li>ordered list item</li></ol></li><li><ul><li>unordered list item</li></ul></li></ul></li>
199
<li><code><img src="http://example.com/img.png" /></code>
200
<ul><li>Note '/' at end!</li>
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 -- <link rel="author" href="author@example.com" title="Author Name" /></li>
209
<li>Put in <head></li>
211
<li>sub/sup -- subscripts, superscripts</li>
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><a name="label-name" /></code>
220
<li>Reference in file<ul><li><code><a href="#label-name">reference text</a></code></li>
223
<li>Reference in other file<ul><li><code><a href="file-name#label-name">reference text</a></code></li>
226
<li>Refer to URL<ul><li><code><a href="http://example.com">reference text</a></code></li>
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>
235
<li><div class="note">note</a> -- notes</li>
237
<li><div class="doit">doit</a> -- something not implemented</li>
239
<li><span class="footnote">footnote</a> -- put in a footnote</li>
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><code class="API">urllib</code></code>
248
<li><code><code base="urllib" class="API">urlencode</code></code>
251
<li><code><code base="twisted" class="API">copyright.version</code></code>
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>
260
<li>Generate links to auto-generated docs</li>
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 <pre></li>
268
<li>Possible classes: python, shell, python-interpreter</li>
274
<pre class="python">
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 <code></li>
283
<li>Possible classes: python, shell, py-signature</li>
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>
293
<li>Put in reference to stylesheet -- head is mostly kept as is</li>
295
<li>Title will be prepended to document's title</li>
297
<li><div class="toc" /> will be replaced by table of contents</li>
299
<li><div class="body" /> will be replaced by processed body</li>
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>
307
<li>Basic format: lore file.html --> outputs file.xhtml<ul><li>--config template=template.tpl to use different template</li>
309
<li>--config baseurl=format-string for the url of the auto-generated docstring docs</li>
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>
318
<li>lore --docsdir doc/howto/</li>
320
<li>lore -p --docsdir doc/howto/ # use plain progress</li>
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>
328
<li>lore --ext='' foo.html # produce 'foo' as output</li>
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>
336
<li>The stylesheet Twisted uses can be used as example<ul><li>Especially the .py-src-* classes: used for syntax highlighting</li>
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>
345
<li>lore -olatex --config book file.html</li>
347
<li>lore -olatex --config section --docsdir doc/howto/</li>
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: <element hlint="off">mistake</element></li>
355
<li>But usually the linter is right</li>
357
<li>lint exits with non-zero status iff some document was not clean -- useful in shell scripts</li>
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>
365
<li>Line/column always point to start/end of element</li>
367
<li>Some justifications:<ul><li><pre> with >80 characters/line renders badly, both in HTML and in LaTeX</li>
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>
376
<li>lore -ilore-slides -oprosper file.html for prosper</li>
378
<li>lore -ilore-slides -ohtml file.html for HTML next/prev</li>
380
<li>Splits on 'h2'</li>
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>
390
<li>Change how documents are processed</li>
392
<li>Add more output formats</li>
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: <span class="blink"></li>
400
<li>Modify HTML output</li>
402
<li>Modify lint output</li>
404
<li>Make it 'small caps' in LaTeX</li>
406
<li>Distribute as package 'blinker'</li>
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>
414
from twisted.lore import tree
415
from twisted.web import microdom, domhelpers
417
def doBlink(document):
418
for node in domhelpers.findElementsWithAttribute(document, 'class',
420
newNode = microdom.Element('blink')
421
newNode.children = node.children
422
node.parentNode.replaceChild(newNode, node)
424
def doFile(fn, docsdir, ext, url, templ, linkrel=''):
425
doc = tree.parseFileAndReport(fn)
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'))
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>
437
class BlinkerLatexSpitter(latex.LatexSpitter):
439
def visitNode_span_blink(self, node):
441
self.visitNodeDefault(node)
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>
450
from blinker import html, latex
451
from twisted.lore import default
453
class ProcessingFunctionFactory(default.ProcessingFunctionFactory):
457
latexSpitters = {None: latex.BlinkLatexSpitter}
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
467
factory = ProcessingFunctionFactory()
470
# blinker/plugins.tml
471
register("Blink-Lore",
473
description="Lore format with blink",
477
<p>...and that's it!</p>
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>
484
<li>Man->Lore conversion</li>
486
<li>lore -iman -olint file.1 --> generates file.html</li>
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>
494
<li>Man->Lore conversion</li>
496
<li>lore -iman -olint file.1 --> generates file.html</li>
500
<em>Lorelai (Concert Interruptus, season 1) -- would you like to write out some sort of instruction manual to go with the dishes?</em>