docutils.writers.html4css1.HTMLTranslator

Package docutils :: Package writers :: Module html4css1 :: Class HTMLTranslator |
[show private | hide private]
[frames | no frames]

## Class HTMLTranslator

    NodeVisitor --+
                  |
                 HTMLTranslator

This HTML writer has been optimized to produce visually compact lists (less vertical whitespace). HTML's mixed content models allow list items to contain "<li><p>body elements</p></li>" or "<li>just text</li>" or even "<li>text<p>and body elements</p>combined</li>", each with different effects. It would be best to stick with strict body elements in list items, but they affect vertical spacing in browsers (although they really shouldn't).

Here is an outline of the optimization:

- Check for and omit <p> tags in "simple" lists: list items contain either a single paragraph, a nested simple list, or a paragraph followed by a nested simple list. This means that this list can be compact:

  > - Item 1.
  > - Item 2.

  But this list cannot be compact:

  > - Item 1.

  >   This second paragraph forces space between list items.

  > - Item 2.

- In non-list contexts, omit <p> tags on a paragraph if that paragraph is the only child of its parent (footnotes & citations are allowed a label first).

- Regardless of the above, in definitions, table cells, field bodies, option descriptions, and list items, mark the first child with 'class="first"' and the last child with 'class="last"'. The stylesheet sets the margins (top & bottom respecively) to 0 for these elements.

The `no_compact_lists` setting (`--no-compact-lists` command-line option) disables list whitespace optimization.

Method Summary
| `__init__(self, document)`
| `astext(self)`
| ``attval`(self, text, whitespace)` Cleanse, HTML encode, and return attribute value text.
| ``check_simple_list`(self, node)` Check for a simple list that can be rendered compactly.
| `depart_abbreviation(self, node)`
| `depart_acronym(self, node)`
| `depart_address(self, node)`
| `depart_admonition(self, node)`
| `depart_attention(self, node)`
| `depart_attribution(self, node)`
| `depart_author(self, node)`
| `depart_authors(self, node)`
| `depart_block_quote(self, node)`
| `depart_bullet_list(self, node)`
| `depart_caption(self, node)`
| `depart_caution(self, node)`
| `depart_citation(self, node)`
| `depart_citation_reference(self, node)`
| `depart_classifier(self, node)`
| `depart_colspec(self, node)`
| `depart_contact(self, node)`
| `depart_copyright(self, node)`
| `depart_danger(self, node)`
| `depart_date(self, node)`
| `depart_decoration(self, node)`
| `depart_definition(self, node)`
| `depart_definition_list(self, node)`
| `depart_definition_list_item(self, node)`
| `depart_description(self, node)`
| `depart_docinfo(self, node)`
| `depart_docinfo_item(self)`
| `depart_doctest_block(self, node)`
| `depart_document(self, node)`
| `depart_emphasis(self, node)`
| `depart_entry(self, node)`
| `depart_enumerated_list(self, node)`
| `depart_error(self, node)`
| `depart_field(self, node)`
| `depart_field_body(self, node)`
| `depart_field_list(self, node)`
| `depart_field_name(self, node)`
| `depart_figure(self, node)`
| `depart_footer(self, node)`
| `depart_footnote(self, node)`
| `depart_footnote_reference(self, node)`
| `depart_generated(self, node)`
| `depart_header(self, node)`
| `depart_hint(self, node)`
| `depart_image(self, node)`
| `depart_important(self, node)`
| `depart_inline(self, node)`
| `depart_label(self, node)`
| `depart_legend(self, node)`
| `depart_line_block(self, node)`
| `depart_list_item(self, node)`
| `depart_literal_block(self, node)`
| `depart_meta(self, node)`
| `depart_note(self, node)`
| `depart_option(self, node)`
| `depart_option_argument(self, node)`
| `depart_option_group(self, node)`
| `depart_option_list(self, node)`
| `depart_option_list_item(self, node)`
| `depart_option_string(self, node)`
| `depart_organization(self, node)`
| `depart_paragraph(self, node)`
| `depart_problematic(self, node)`
| `depart_reference(self, node)`
| `depart_revision(self, node)`
| `depart_row(self, node)`
| `depart_rubric(self, node)`
| `depart_section(self, node)`
| `depart_sidebar(self, node)`
| `depart_status(self, node)`
| `depart_strong(self, node)`
| `depart_subscript(self, node)`
| `depart_subtitle(self, node)`
| `depart_superscript(self, node)`
| `depart_system_message(self, node)`
| `depart_table(self, node)`
| `depart_target(self, node)`
| `depart_tbody(self, node)`
| ``depart_term`(self, node)` Leave the end tag to `self.visit_definition()`, in case there's a classifier.
| `depart_Text(self, node)`
| `depart_tgroup(self, node)`
| `depart_thead(self, node)`
| `depart_tip(self, node)`
| `depart_title(self, node)`
| `depart_title_reference(self, node)`
| `depart_topic(self, node)`
| `depart_transition(self, node)`
| `depart_version(self, node)`
| `depart_warning(self, node)`
| ``emptytag`(self, node, tagname, suffix, **attributes)` Construct and return an XML-compatible empty tag.
| ``encode`(self, text)` Encode special characters in `text` & return.
| `footnote_backrefs(self, node)`
| `get_stylesheet_reference(self, relative_to)`
| ``starttag`(self, node, tagname, suffix, infix, **attributes)` Construct and return a start tag given a node (id & class attributes are extracted), tag name, and optional attributes.
| `unimplemented_visit(self, node)`
| `visit_abbreviation(self, node)`
| `visit_acronym(self, node)`
| `visit_address(self, node)`
| `visit_admonition(self, node, name)`
| `visit_attention(self, node)`
| `visit_attribution(self, node)`
| `visit_author(self, node)`
| `visit_authors(self, node)`
| `visit_block_quote(self, node)`
| `visit_bullet_list(self, node)`
| `visit_caption(self, node)`
| `visit_caution(self, node)`
| `visit_citation(self, node)`
| `visit_citation_reference(self, node)`
| `visit_classifier(self, node)`
| `visit_colspec(self, node)`
| ``visit_comment`(self, node, sub)` Escape double-dashes in comment text.
| `visit_contact(self, node)`
| `visit_copyright(self, node)`
| `visit_danger(self, node)`
| `visit_date(self, node)`
| `visit_decoration(self, node)`
| `visit_definition(self, node)`
| `visit_definition_list(self, node)`
| `visit_definition_list_item(self, node)`
| `visit_description(self, node)`
| `visit_docinfo(self, node)`
| `visit_docinfo_item(self, node, name, meta)`
| `visit_doctest_block(self, node)`
| `visit_document(self, node)`
| `visit_emphasis(self, node)`
| `visit_entry(self, node)`
| ``visit_enumerated_list`(self, node)` The 'start' attribute does not conform to HTML 4.01's strict.dtd, but CSS1 doesn't help.
| `visit_error(self, node)`
| `visit_field(self, node)`
| `visit_field_body(self, node)`
| `visit_field_list(self, node)`
| `visit_field_name(self, node)`
| `visit_figure(self, node)`
| `visit_footer(self, node)`
| `visit_footnote(self, node)`
| `visit_footnote_reference(self, node)`
| `visit_generated(self, node)`
| `visit_header(self, node)`
| `visit_hint(self, node)`
| `visit_image(self, node)`
| `visit_important(self, node)`
| `visit_inline(self, node)`
| `visit_label(self, node)`
| `visit_legend(self, node)`
| `visit_line_block(self, node)`
| `visit_list_item(self, node)`
| ``visit_literal`(self, node)` Process text to prevent tokens from wrapping.
| `visit_literal_block(self, node)`
| `visit_meta(self, node)`
| `visit_note(self, node)`
| `visit_option(self, node)`
| `visit_option_argument(self, node)`
| `visit_option_group(self, node)`
| `visit_option_list(self, node)`
| `visit_option_list_item(self, node)`
| `visit_option_string(self, node)`
| `visit_organization(self, node)`
| `visit_paragraph(self, node)`
| `visit_problematic(self, node)`
| `visit_raw(self, node)`
| `visit_reference(self, node)`
| `visit_revision(self, node)`
| `visit_row(self, node)`
| `visit_rubric(self, node)`
| `visit_section(self, node)`
| `visit_sidebar(self, node)`
| `visit_status(self, node)`
| `visit_strong(self, node)`
| `visit_subscript(self, node)`
| ``visit_substitution_definition`(self, node)` Internal only.
| `visit_substitution_reference(self, node)`
| `visit_subtitle(self, node)`
| `visit_superscript(self, node)`
| `visit_system_message(self, node)`
| `visit_table(self, node)`
| `visit_target(self, node)`
| `visit_tbody(self, node)`
| `visit_term(self, node)`
| `visit_Text(self, node)`
| `visit_tgroup(self, node)`
| `visit_thead(self, node)`
| `visit_tip(self, node)`
| ``visit_title`(self, node)` Only 6 section levels are supported by HTML.
| `visit_title_reference(self, node)`
| `visit_topic(self, node)`
| `visit_transition(self, node)`
| `visit_version(self, node)`
| `visit_warning(self, node)`
| `write_colspecs(self)`
Inherited from `NodeVisitor`: `unknown_departure`, `unknown_visit`

Class Variable Summary
`dict` | `attribution_formats` = `{'dash': ('&mdash;', ''), 'parens'...`
`str` | `content_type` = `'<meta http-equiv="Content-Type" content=...`
`str` | `doctype` = `'<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 ...`
`str` | `embedded_stylesheet` = `'<style type="text/css"><!--\n\n%s...`
`str` | `generator` = `'<meta name="generator" content="Docutils %s...`
`str` | `html_head` = `'<html xmlns="http://www.w3.org/1999/xhtml" ...`
`dict` | `named_tags` = `{'a': 1, 'map': 1, 'applet': 1, 'form': 1, ...`
`str` | `stylesheet_link` = `'<link rel="stylesheet" href="%s" type...`
`SRE_Pattern` | `words_and_spaces` = `\S+| +|\n`
`str` | `xml_declaration` = `'<?xml version="1.0" encoding="%s" ?>\...`

Method Details

### attval(self, text, whitespace=<_sre.SRE_Pattern object at 0x81c5570>) Cleanse, HTML encode, and return attribute value text.

### check_simple_list(self, node) Check for a simple list that can be rendered compactly.

### depart_term(self, node) Leave the end tag to `self.visit_definition()`, in case there's a classifier.

### emptytag(self, node, tagname, suffix='\n', **attributes) Construct and return an XML-compatible empty tag.

### encode(self, text) Encode special characters in `text` & return.

### starttag(self, node, tagname, suffix='\n', infix='', **attributes) Construct and return a start tag given a node (id & class attributes are extracted), tag name, and optional attributes.

### visit_comment(self, node, sub=<built-in method sub of _sre.SRE_Pattern object at 0x8366...) Escape double-dashes in comment text.

### visit_enumerated_list(self, node) The 'start' attribute does not conform to HTML 4.01's strict.dtd, but CSS1 doesn't help. CSS2 isn't widely enough supported yet to be usable.

### visit_literal(self, node) Process text to prevent tokens from wrapping.

### visit_substitution_definition(self, node) Internal only.

### visit_title(self, node) Only 6 section levels are supported by HTML.

Class Variable Details

    ### attribution_formats Type: `dict` Value:
        {'dash': ('&mdash;', ''),
         'none': ('', ''),
         'parens': ('(', ')'),
         'parentheses': ('(', ')')}

    ### content_type Type: `str` Value:
        '''<meta http-equiv="Content-Type" content="text/html; charset=%s" />
        '''

    ### doctype Type: `str` Value:
        '''<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "htt\
        p://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
        '''

    ### embedded_stylesheet Type: `str` Value:
        '''<style type="text/css"><!--

        %s
        --></style>
        '''

    ### generator Type: `str` Value:
        '''<meta name="generator" content="Docutils %s: http://docutils.source\
        forge.net/" />
        '''

    ### html_head Type: `str` Value:
        '''<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="%s" lang="%s">
        <head>
        '''

    ### named_tags Type: `dict` Value:
        {'a': 1, 'map': 1, 'applet': 1, 'form': 1, 'iframe': 1, 'img': 1, 'fra\
        me': 1}

    ### stylesheet_link Type: `str` Value:
        '''<link rel="stylesheet" href="%s" type="text/css" />
        '''

    ### words_and_spaces Type: `SRE_Pattern` Value:
        \S+| +|\n

    ### xml_declaration Type: `str` Value:
        '''<?xml version="1.0" encoding="%s" ?>
        '''

Generated by Epydoc 2.1 on Sat Mar 20 17:46:13 2004 | http://epydoc.sf.net