Ticket #4571: lore.xhtml.path

File lore.xhtml.path, 9.5 KB (added by jdb, 4 years ago)
Line 
1diff --git a/doc/lore/howto/extend-lore.xhtml b/doc/lore/howto/extend-lore.xhtml
2index b04c899..d47d455 100644
3--- a/doc/lore/howto/extend-lore.xhtml
4+++ b/doc/lore/howto/extend-lore.xhtml
5@@ -24,14 +24,15 @@ can be solved by creating an extension.</p>
6 
7 <h2>Inputs and Outputs</h2>
8 
9-<p>Lore works by reading the HTML source of your document, and producing
10-whatever output the user specifies on the command line.  If the HTML document
11-is well-formed XML that meets a certain minimum standard, Lore will be able to
12-to produce some output.  All Lore extensions will be written to redefine the
13-<em>input</em>, and most will redefine the output in some way.  The name of
14-the default input is <q>lore</q>.  When you write your extension, you will
15-come up with a new name for your input, telling Lore what rules to use to
16-process the file.</p>
17+<p>Lore works by reading the HTML source of your document, and
18+producing whatever output the user specifies on the command line.  If
19+the HTML document is well-formed XML that meets a certain minimum
20+standard, Lore will be able to to produce some output.  All Lore
21+extensions will be written to redefine the <em>input</em>, and most
22+will redefine the output in some way.  The name of the default input
23+is <q>lore</q>.  When you write your extension, you will come up with
24+a new name for your input, telling Lore what rules to use to process
25+the file.</p>
26 
27 <p>Lore can produce XHTML, LaTeX, and DocBook document formats, which can be
28 displayed directly if you have a user agent capable of viewing them, or
29@@ -91,19 +92,18 @@ classes.  To make LaTeX and lint work, we start by creating a plugin.</p>
30 <a href="listings/lore/factory.py-1" class="py-listing">Listing 2: The Input
31   Factory</a>
32 
33-<p>In Listing 2, we create a subclass of ProcessingFunctionFactory.  This
34-class provides a hook for you, a class variable named
35-<code>latexSpitters</code>.  This variable tells Lore
36-what new class will be generating LaTeX from your input format.  We redefine
37-<code>latexSpitters</code> to <code>MyLatexSpitter</code> in the subclass
38-because this
39-class knows what to do with the new input we have already defined.  Last, you
40-must define the module-level variable <code
41-    class="py-src-identifier">factory</code>.  It should be an instance with
42-  the same
43-interface as <code class="py-src-identifier">ProcessingFunctionFactory</code>
44-(e.g. an instance of a subclass, in this case, <code
45-    class="py-src-identifier">MyProcessingFunctionFactory</code>).</p>
46+<p>In Listing 2, we create a subclass of ProcessingFunctionFactory.
47+This class provides a hook for you, a class variable
48+named <code>latexSpitters</code>.  This variable tells Lore what new
49+class will be generating LaTeX from your input format.  We
50+redefine <code>latexSpitters</code> to <code>MyLatexSpitter</code> in
51+the subclass because this class knows what to do with the new input we
52+have already defined.  Last, you must define the module-level
53+variable <code class="py-src-identifier">factory</code>.  It should be
54+an instance with the same interface
55+as <code class="py-src-identifier">ProcessingFunctionFactory</code>
56+(e.g. an instance of a subclass, in this
57+case, <code class="py-src-identifier">MyProcessingFunctionFactory</code>).</p>
58 
59 <p>Now let's actually write some code to generate the LaTeX.  Doing this
60 requires at least a familiarity with the LaTeX language.  Search Google for
61@@ -113,11 +113,11 @@ resources.</p>
62 <a href="listings/lore/spitters.py-1" class="py-listing">Listing 3:
63   spitters.py</a>
64 
65-<p>The method <code>visitNode_span_productname</code> is
66-our handler for &lt;span&gt; tags with the <code>class="productname"</code>
67-identifier.  Lore knows to try methods <code>visitNode_span_*</code> and
68-<code>visitNode_div_*</code> whenever it encounters a new
69-class in one of these tags.  This is why the class names have to be valid
70+<p>The method <code>visitNode_span_productname</code> is our handler
71+for &lt;span&gt; tags with the <code>class="productname"</code>
72+identifier.  Lore knows to try methods <code>visitNode_span_*</code>
73+and <code>visitNode_div_*</code> whenever it encounters a new class in
74+one of these tags.  This is why the class names have to be valid
75 Python identifiers.</p>
76 
77 <p>Now let's see what Lore does with these new classes with the following
78diff --git a/doc/lore/howto/lore.xhtml b/doc/lore/howto/lore.xhtml
79index 7e6a19c..cc70398 100644
80--- a/doc/lore/howto/lore.xhtml
81+++ b/doc/lore/howto/lore.xhtml
82@@ -17,22 +17,23 @@ with XML help like EMACS and ending with XML specific tools like (need name
83 of XML editor here). Here, we will not cover the specifics of writing XML
84 documents, except for a very broad overview.</p>
85 
86-<p>XML documents contain elements, which are delimited by an opening tag
87-which looks like <code>&lt;tag-name attribute="value"&gt;</code> and ends with
88-a closing tag, which looks like <code>&lt;/tag-name&gt;</code>. If an
89-elements happen to contain nothing, it can be shortened to
90-<code>&lt;tag-name /&gt;</code>. Elements can contain other elements, or
91-text. Text can contain any characters except &lt;, &gt; and &amp;. These
92-characters are rendered by &amp;lt;, &amp;gt; and &amp;amp;, respectively.</p>
93-
94-<p>A Lore document is a single <code>html</code> element. Inside this element,
95-there are exactly two top-level elements: <code>head</code> and
96-<code>body</code>. The <code>head</code> element must contain exactly one
97-element: <code>title</code>, containing the title of the document.
98-Most of the document will be contained in the <code>body</code> element.
99-The <code>body</code> element must start with an <code>h1</code> (top-level
100-header) element, which contains the exact same content as the
101-<code>title</code> element.</p>
102+<p>XML documents contain elements, which are delimited by an opening
103+tag which looks like <code>&lt;tag-name attribute="value"&gt;</code>
104+and ends with a closing tag, which looks
105+like <code>&lt;/tag-name&gt;</code>. If an elements happen to contain
106+nothing, it can be shortened to <code>&lt;tag-name
107+/&gt;</code>. Elements can contain other elements, or text. Text can
108+contain any characters except &lt;, &gt; and &amp;. These characters
109+are rendered by &amp;lt;, &amp;gt; and &amp;amp;, respectively.</p>
110+
111+<p>A Lore document is a single <code>html</code> element. Inside this
112+element, there are exactly two top-level elements: <code>head</code>
113+and <code>body</code>. The <code>head</code> element must contain
114+exactly one element: <code>title</code>, containing the title of the
115+document.  Most of the document will be contained in
116+the <code>body</code> element.  The <code>body</code> element must
117+start with an <code>h1</code> (top-level header) element, which
118+contains the exact same content as the <code>title</code> element.</p>
119 
120 <p>Thus, a fairly minimal Lore document might look like:</p>
121 
122@@ -117,8 +118,8 @@ paragraphs. The following classes have the given meanings:
123 
124 <tr>
125 <td><code>ol</code>, <code>ul</code></td>
126-<td>A list. It can be enumerated or bulleted. Inside a list, the element
127-<code>li</code> (for a list element) is valid.</td>
128+<td>A list. It can be enumerated or bulleted. Inside a list, the
129+element <code>li</code> (for a list element) is valid.</td>
130 </tr>
131 
132 <tr>
133@@ -159,11 +160,11 @@ classes:
134 
135 <tr>
136 <td><code>pre</code></td>
137-<td>Preformatted text, usually for file listings. It can be used with the
138-<code>python</code> class to indicate Python syntax coloring. Other possible
139-classes are <code>shell</code> (to indicate a shell-transcript) or
140-<code>python-interpreter</code> (to indicate an interactive interpreter
141-transcript).</td>
142+<td>Preformatted text, usually for file listings. It can be used with
143+the <code>python</code> class to indicate Python syntax
144+coloring. Other possible classes are <code>shell</code> (to indicate a
145+shell-transcript) or <code>python-interpreter</code> (to indicate an
146+interactive interpreter transcript).</td>
147 </tr>
148 
149 <tr>
150@@ -298,8 +299,8 @@ myslides-&lt;number&gt;.html, where number is the slide number,
151 starting with 0 for the title slide.  Lore will look for a template
152 file, either indicated by the <code>--config
153 template=mytemplate.tpl</code> or the default template.tpl in the
154-current directory.  An example slide template is found in
155-<code>doc/examples/slides-template.tpl</code></p>
156+current directory.  An example slide template is found
157+in <code>doc/examples/slides-template.tpl</code></p>
158 
159 <p>The slides module currently supports three major output types:
160 HTML, Magic Point, and LaTeX.  The options for the latter two will be
161@@ -327,13 +328,14 @@ slides are generated by </p>
162 
163 <p>Lore can also produce slides in LaTeX format.  It supports three
164 main styles: one slide per page, two per page, and Prosper format,
165-with the <code>--config</code> parameters being <code>page</code>,
166-<code>twopage</code>, and <code>prosper</code> respectively. Prosper
167-is a LaTeX class for creating slides, which can be installed on Debian
168-by <code>apt-get install prosper</code> or by visiting <a
169-href="http://sourceforge.net/projects/prosper/">the Prosper SourceForge page</a>.
170-LaTeX format slides (using the Prosper option, for example) are
171-generated by</p>
172+with the <code>--config</code> parameters
173+being <code>page</code>, <code>twopage</code>,
174+and <code>prosper</code> respectively. Prosper is a LaTeX class for
175+creating slides, which can be installed on Debian by <code>apt-get
176+install prosper</code> or by
177+visiting <a href="http://sourceforge.net/projects/prosper/">the
178+Prosper SourceForge page</a>.  LaTeX format slides (using the Prosper
179+option, for example) are generated by</p>
180 
181 <pre class="shell">
182 % lore --input lore-slides --output latex \