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>