docutils.writers.html4css1 package

Simple HyperText Markup Language document tree Writer.

The output conforms to the XHTML version 1.0 Transitional DTD (almost strict). The output contains a minimum of formatting information. The cascading style sheet “html4css1.css” is required for proper viewing with a modern graphical browser.

class Writer

Bases: Writer

supported = ('html', 'html4', 'html4css1', 'xhtml', 'xhtml10')

Formats this writer supports.

default_stylesheets = ['html4css1.css']

default_stylesheet_dirs = ['.', '/home/docs/checkouts/readthedocs.org/user_builds/sphinx-docutils/envs/latest/lib/python3.12/site-packages/docutils/writers/html4css1', '/home/docs/checkouts/readthedocs.org/user_builds/sphinx-docutils/envs/latest/lib/python3.12/site-packages/docutils/writers/html5_polyglot']

default_template = '/home/docs/checkouts/readthedocs.org/user_builds/sphinx-docutils/envs/latest/lib/python3.12/site-packages/docutils/writers/html4css1/template.txt'

settings_spec = ('HTML Writer Options', None, (('Template file. (UTF-8 encoded, default: "/home/docs/checkouts/readthedocs.org/user_builds/sphinx-docutils/envs/latest/lib/python3.12/site-packages/docutils/writers/html4css1/template.txt")', ['--template'], {'default': '/home/docs/checkouts/readthedocs.org/user_builds/sphinx-docutils/envs/latest/lib/python3.12/site-packages/docutils/writers/html4css1/template.txt', 'metavar': '<file>'}), ('Comma separated list of stylesheet URLs. Overrides previous --stylesheet and --stylesheet-path settings.', ['--stylesheet'], {'metavar': '<URL[,URL,...]>', 'overrides': 'stylesheet_path', 'validator': <function validate_comma_separated_list>}), ('Comma separated list of stylesheet paths. Relative paths are expanded if a matching file is found in the --stylesheet-dirs. With --link-stylesheet, the path is rewritten relative to the output HTML file. (default: "html4css1.css")', ['--stylesheet-path'], {'default': ['html4css1.css'], 'metavar': '<file[,file,...]>', 'overrides': 'stylesheet', 'validator': <function validate_comma_separated_list>}), ('Comma-separated list of directories where stylesheets are found. Used by --stylesheet-path when expanding relative path arguments. (default: ".,/home/docs/checkouts/readthedocs.org/user_builds/sphinx-docutils/envs/latest/lib/python3.12/site-packages/docutils/writers/html4css1,/home/docs/checkouts/readthedocs.org/user_builds/sphinx-docutils/envs/latest/lib/python3.12/site-packages/docutils/writers/html5_polyglot")', ['--stylesheet-dirs'], {'default': ['.', '/home/docs/checkouts/readthedocs.org/user_builds/sphinx-docutils/envs/latest/lib/python3.12/site-packages/docutils/writers/html4css1', '/home/docs/checkouts/readthedocs.org/user_builds/sphinx-docutils/envs/latest/lib/python3.12/site-packages/docutils/writers/html5_polyglot'], 'metavar': '<dir[,dir,...]>', 'validator': <function validate_comma_separated_list>}), ('Embed the stylesheet(s) in the output HTML file.  The stylesheet files must be accessible during processing. (default)', ['--embed-stylesheet'], {'action': 'store_true', 'default': 1, 'validator': <function validate_boolean>}), ('Link to the stylesheet(s) in the output HTML file. ', ['--link-stylesheet'], {'action': 'store_false', 'dest': 'embed_stylesheet'}), ('Specify the initial header level. Does not affect document title & subtitle (see --no-doc-title). (default: 1 for "<h1>")', ['--initial-header-level'], {'choices': ['1', '2', '3', '4', '5', '6'], 'default': '1', 'metavar': '<level>'}), ('Format for footnote references: one of "superscript" or "brackets". (default: "brackets")', ['--footnote-references'], {'choices': ['superscript', 'brackets'], 'default': 'brackets', 'metavar': '<format>', 'overrides': 'trim_footnote_reference_space'}), ('Format for block quote attributions: one of "dash" (em-dash prefix), "parentheses"/"parens", or "none". (default: "dash")', ['--attribution'], {'choices': ['dash', 'parentheses', 'parens', 'none'], 'default': 'dash', 'metavar': '<format>'}), ('Remove extra vertical whitespace between items of "simple" bullet lists and enumerated lists. (default)', ['--compact-lists'], {'action': 'store_true', 'default': True, 'validator': <function validate_boolean>}), ('Disable compact simple bullet and enumerated lists.', ['--no-compact-lists'], {'action': 'store_false', 'dest': 'compact_lists'}), ('Remove extra vertical whitespace between items of simple field lists. (default)', ['--compact-field-lists'], {'action': 'store_true', 'default': True, 'validator': <function validate_boolean>}), ('Disable compact simple field lists.', ['--no-compact-field-lists'], {'action': 'store_false', 'dest': 'compact_field_lists'}), ('Added to standard table classes. Defined styles: borderless, booktabs, align-left, align-center, align-right, colwidths-auto, colwidths-grid.', ['--table-style'], {'default': ''}), ('Math output format (one of "MathML", "HTML", "MathJax", or "LaTeX") and option(s). (default: "HTML math.css")', ['--math-output'], {'default': 'HTML math.css'}), ('Prepend an XML declaration (default). ', ['--xml-declaration'], {'action': 'store_true', 'default': True, 'validator': <function validate_boolean>}), ('Omit the XML declaration.', ['--no-xml-declaration'], {'action': 'store_false', 'dest': 'xml_declaration'}), ('Obfuscate email addresses to confuse harvesters while still keeping email links usable with standards-compliant browsers.', ['--cloak-email-addresses'], {'action': 'store_true', 'validator': <function validate_boolean>})), 'HTML4 Writer Options', '', (('Specify the maximum width (in characters) for one-column field names.  Longer field names will span an entire row of the table used to render the field list.  Default is 14 characters.  Use 0 for "no limit".', ['--field-name-limit'], {'default': 14, 'metavar': '<level>', 'validator': <function validate_nonnegative_int>}), ('Specify the maximum width (in characters) for options in option lists.  Longer options will span an entire row of the table used to render the option list.  Default is 14 characters.  Use 0 for "no limit".', ['--option-limit'], {'default': 14, 'metavar': '<level>', 'validator': <function validate_nonnegative_int>})))

Runtime settings specification. Override in subclasses.

Defines runtime settings and associated command-line options, as used by docutils.frontend.OptionParser. This is a tuple of:

• Option group title (string or None which implies no group, just a list of single options).

• Description (string or None).

• A sequence of option tuples. Each consists of:

  • Help text (string)

  • List of option strings (e.g. ['-Q', '--quux']).

  • Dictionary of keyword arguments sent to the OptionParser/OptionGroup add_option method.

    Runtime setting names are derived implicitly from long option names (’–a-setting’ becomes settings.a_setting) or explicitly from the ‘dest’ keyword argument.

    Most settings will also have a ‘validator’ keyword & function. The validator function validates setting values (from configuration files and command-line option arguments) and converts them to appropriate types. For example, the docutils.frontend.validate_boolean function, required by all boolean settings, converts true values (‘1’, ‘on’, ‘yes’, and ‘true’) to 1 and false values (‘0’, ‘off’, ‘no’, ‘false’, and ‘’) to 0. Validators need only be set once per setting. See the docutils.frontend.validate_* functions.

    See the optparse docs for more details.

• More triples of group title, description, options, as many times as needed. Thus, settings_spec tuples can be simply concatenated.

config_section = 'html4css1 writer'

The name of the config file section specific to this component (lowercase, no brackets). Override in subclasses.

class HTMLTranslator(document)

Bases: HTMLTranslator

The html4css1 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 older browsers (although they really shouldn’t). The html5_polyglot writer solves this using CSS2.

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 respectively) to 0 for these elements.

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

doctype = '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">\n'

content_type = '<meta http-equiv="Content-Type" content="text/html; charset=%s" />\n'

content_type_mathml = '<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=%s" />\n'

special_characters = {34: '&quot;', 38: '&amp;', 60: '&lt;', 62: '&gt;', 64: '&#64;', 160: '&nbsp;'}

Character references for characters with a special meaning in HTML.

attribution_formats = {'dash': ('&mdash;', ''), 'none': ('', ''), 'parens': ('(', ')'), 'parentheses': ('(', ')')}

set_first_last(node)

visit_address(node)

depart_address(node)

visit_admonition(node)

depart_admonition(node=None)

visit_author(node)

depart_author(node)

visit_authors(node)

depart_authors(node)

visit_colspec(node)

depart_colspec(node)

is_compactable(node)

visit_citation(node)

depart_citation(node)

visit_citation_reference(node)

depart_citation_reference(node)

visit_classifier(node)

depart_classifier(node)

visit_compound(node)

depart_compound(node)

visit_definition(node)

depart_definition(node)

visit_definition_list(node)

depart_definition_list(node)

visit_definition_list_item(node)

depart_definition_list_item(node)

visit_description(node)

depart_description(node)

visit_docinfo(node)

depart_docinfo(node)

visit_docinfo_item(node, name, meta=True)

depart_docinfo_item()

visit_doctest_block(node)

depart_doctest_block(node)

visit_entry(node)

depart_entry(node)

visit_enumerated_list(node)

The ‘start’ attribute does not conform to HTML 4.01’s strict.dtd, but cannot be emulated in CSS1 (HTML 5 reincludes it).

depart_enumerated_list(node)

visit_field(node)

depart_field(node)

visit_field_body(node)

depart_field_body(node)

visit_field_list(node)

depart_field_list(node)

visit_field_name(node)

depart_field_name(node)

visit_footnote(node)

footnote_backrefs(node)

depart_footnote(node)

visit_footnote_reference(node)

depart_footnote_reference(node)

visit_generated(node)

object_image_types = {'.svg': 'image/svg+xml', '.swf': 'application/x-shockwave-flash'}

visit_image(node)

depart_image(node)

visit_label(node)

depart_label(node)

visit_list_item(node)

depart_list_item(node)

visit_literal(node)

depart_literal(node)

visit_literal_block(node)

depart_literal_block(node)

visit_option_group(node)

depart_option_group(node)

visit_option_list(node)

depart_option_list(node)

visit_option_list_item(node)

depart_option_list_item(node)

should_be_compact_paragraph(node)

Determine if the <p> tags around paragraph node can be omitted.

visit_paragraph(node)

depart_paragraph(node)

visit_sidebar(node)

depart_sidebar(node)

visit_subscript(node)

depart_subscript(node)

visit_subtitle(node)

depart_subtitle(node)

visit_superscript(node)

depart_superscript(node)

visit_system_message(node)

depart_system_message(node)

visit_table(node)

depart_table(node)

visit_tbody(node)

depart_tbody(node)

visit_term(node)

depart_term(node)

visit_thead(node)

depart_thead(node)

section_title_tags(node)

class SimpleListChecker(document)

Bases: SimpleListChecker

Raise nodes.NodeFound if non-simple list item is encountered.

Here “simple” means a list item containing nothing other than a single paragraph, a simple list, or a paragraph followed by a simple list.

visit_list_item(node)

visit_paragraph(node)

visit_definition_list(node)

visit_docinfo(node)