Please try to restrict your HTML usage to the following tags (all only for the original logical purpose, and not whatever visual effect you see): <html>, <title>, <head>, <body>, <h1>, <h2, <h3>, <ol>, <ul>, <dl>, <li>, <dt>, <dd>, <p>, <code>, <img>, <blockquote>, <a>, <cite>, <div>, <span>, <strong>, <em>, <pre>, <q>, <table>,<tr>, <td> and <th>.
Please avoid using the quote sign (") for quoting, and use the relevant html tags (<q></q>) -- it is impossible to distinguish right and left quotes with the quote sign, and some more sophisticated output methods work better with that distinction.
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:
python
<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.
python-interpreter
<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!"
shell
<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.
You may also use the base attribute in conjuction
with a class of API
to indicate the module that should be prepended
to the module or classname. This is to help keep the documentation
clearer and less cluttered by allowing links to API docs that don't
need the module name.
<p>
To add a <code class="API">twisted.web.widgets.Widget</code>
instance to a <code class="API"
base="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>
To add a twisted.web.widgets.Widget
instance to a Gadget
instance, do
myGadget.putWidget("widgetPath", MyWidget()).
(implementation note: the widgets are stored in the gadgetInstance.widgets attribute,
which is a
list.)
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. :-)
Footnotes are enclosed inside
<span class="footnote"></span>. They must not
contain any markup.
Use hlint to check your documentation is not
broken. hlint will never change your HTML, but
it will complain if it doesn't like it.
Don't use tables for formatting. 'nuff said.