Multi-line code snippets should be delimited with a <pre> tag, with a mandatory 'class' attribute. The conventionalized classes are "python", "python-interpreter", and "shell". For example:
<p> For example, this is how one defines a Resource: </p> <pre class="python"> from twisted.web import resource class MyResource(resource.Resource): def render(self, request): return "Hello, world!" </pre>
For example, this is how one defines a Resource:
from twisted.web import resource class MyResource(resource.Resource): def render(self, request): return "Hello, world!"
Note that you should never have leading indentation inside a <pre> block -- this makes it hard for readers to copy/paste the code.
<pre class="python-interpreter"> >>> from twisted.web import resource >>> class MyResource(resource.Resource): ... def render(self, request): ... return "Hello, world!" ... >>> MyResource().render(None) "Hello, world!" </pre>
>>> from twisted.web import resource >>> class MyResource(resource.Resource): ... def render(self, request): ... return "Hello, world!" ... >>> MyResource().render(None) "Hello, world!"
<pre class="shell"> $ mktap web --path /var/www </pre>
$ mktap web --path /var/www
For single-line code-snippets and attribute, method, class, and module names, use the <code> tag, with a class of "API" or "python". During processing, module or class-names with class "API" will automatically be looked up in the API reference and have a link placed around it referencing the actual API documents for that module/classname. If you wish to reference an API document, then make sure you at least have a single module-name so that the processing code will be able to figure out which module or class you're referring to.
<p> To add a <code class="API">twisted.web.widgets.Widget</code> instance to a <code class="API">twisted.web.widgets.Gadget</code> instance, do <code class="python">myGadget.putWidget("widgetPath", MyWidget())</code>. </p> <p> (implementation note: the widgets are stored in the <code class="python">gadgetInstance.widgets</code> attribute, which is a list.) </p>
It goes without mentioning that you should use <hN> in a sane way -- <h1> should only appear once in the document, to specify the title. Sections of the document should use <h2>, sub-headers <h3>, and so on.
XHTML is mandatory. That means tags that don't have a
closing tag need a '/'; for example, <hr />
. Also, tags which have "optional" closing tags in HTML
need to be closed in XHTML; for example,
<li>foo</li>
All tags will be done in lower-case. XHTML demands this, and so do I. :-)
(Tidy seems to be causing more harm than good right now, so this next suggestion is on hold for the time being...)
Use 'tidy -e -xml foo.html' before every commit!
Also, tidy can be utilized in other ways to auto-correct your XHTML (or
convert HTML to XHTML), but can sometimes cause undesirable
effects, like converting some </p>
s to
<br />
s.
Don't use tables for formatting. 'nuff said.