# HTML Documentation Standard for Twisted

## Multi-line Code Snippets

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">
        &gt;&gt;&gt; from twisted.web import resource
        &gt;&gt;&gt; class MyResource(resource.Resource):
        ...     def render(self, request):
        ...         return "Hello, world!"
        ...
        &gt;&gt;&gt; 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

## Code inside paragraph text

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>

## Headers

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

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>`

## Tag Case

All tags will be done in lower-case. XHTML demands this, and so do I. :-)

## Suggestions

(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.