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>