You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
214 lines
8.9 KiB
214 lines
8.9 KiB
# .. coding: utf8 |
|
# $Id: __init__.py 8041 2017-03-01 11:02:33Z milde $ |
|
# :Author: Günter Milde <milde@users.sf.net> |
|
# Based on the html4css1 writer by David Goodger. |
|
# :Maintainer: docutils-develop@lists.sourceforge.net |
|
# :Copyright: © 2005, 2009, 2015 Günter Milde, |
|
# portions from html4css1 © David Goodger. |
|
# :License: Released under the terms of the `2-Clause BSD license`_, in short: |
|
# |
|
# Copying and distribution of this file, with or without modification, |
|
# are permitted in any medium without royalty provided the copyright |
|
# notice and this notice are preserved. |
|
# This file is offered as-is, without any warranty. |
|
# |
|
# .. _2-Clause BSD license: http://www.spdx.org/licenses/BSD-2-Clause |
|
|
|
# Use "best practice" as recommended by the W3C: |
|
# http://www.w3.org/2009/cheatsheet/ |
|
|
|
""" |
|
Plain HyperText Markup Language document tree Writer. |
|
|
|
The output conforms to the `HTML5` specification. |
|
|
|
The cascading style sheet "minimal.css" is required for proper viewing, |
|
the style sheet "plain.css" improves reading experience. |
|
""" |
|
__docformat__ = 'reStructuredText' |
|
|
|
import os.path |
|
import docutils |
|
from docutils import frontend, nodes, writers, io |
|
from docutils.transforms import writer_aux |
|
from docutils.writers import _html_base |
|
|
|
class Writer(writers._html_base.Writer): |
|
|
|
supported = ('html', 'html5', 'html4', 'xhtml', 'xhtml10') |
|
"""Formats this writer supports.""" |
|
|
|
default_stylesheets = ['minimal.css','plain.css'] |
|
default_stylesheet_dirs = ['.', os.path.abspath(os.path.dirname(__file__))] |
|
|
|
default_template = 'template.txt' |
|
default_template_path = os.path.join( |
|
os.path.dirname(os.path.abspath(__file__)), default_template) |
|
|
|
settings_spec = ( |
|
'HTML-Specific Options', |
|
None, |
|
(('Specify the template file (UTF-8 encoded). Default is "%s".' |
|
% default_template_path, |
|
['--template'], |
|
{'default': default_template_path, 'metavar': '<file>'}), |
|
('Comma separated list of stylesheet URLs. ' |
|
'Overrides previous --stylesheet and --stylesheet-path settings.', |
|
['--stylesheet'], |
|
{'metavar': '<URL[,URL,...]>', 'overrides': 'stylesheet_path', |
|
'validator': frontend.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: "%s"' % ','.join(default_stylesheets), |
|
['--stylesheet-path'], |
|
{'metavar': '<file[,file,...]>', 'overrides': 'stylesheet', |
|
'validator': frontend.validate_comma_separated_list, |
|
'default': default_stylesheets}), |
|
('Embed the stylesheet(s) in the output HTML file. The stylesheet ' |
|
'files must be accessible during processing. This is the default.', |
|
['--embed-stylesheet'], |
|
{'default': 1, 'action': 'store_true', |
|
'validator': frontend.validate_boolean}), |
|
('Link to the stylesheet(s) in the output HTML file. ' |
|
'Default: embed stylesheets.', |
|
['--link-stylesheet'], |
|
{'dest': 'embed_stylesheet', 'action': 'store_false'}), |
|
('Comma-separated list of directories where stylesheets are found. ' |
|
'Used by --stylesheet-path when expanding relative path arguments. ' |
|
'Default: "%s"' % default_stylesheet_dirs, |
|
['--stylesheet-dirs'], |
|
{'metavar': '<dir[,dir,...]>', |
|
'validator': frontend.validate_comma_separated_list, |
|
'default': default_stylesheet_dirs}), |
|
('Specify the initial header level. Default is 1 for "<h1>". ' |
|
'Does not affect document title & subtitle (see --no-doc-title).', |
|
['--initial-header-level'], |
|
{'choices': '1 2 3 4 5 6'.split(), 'default': '1', |
|
'metavar': '<level>'}), |
|
('Format for footnote references: one of "superscript" or ' |
|
'"brackets". Default is "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 is "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: enabled.', |
|
['--compact-lists'], |
|
{'default': True, 'action': 'store_true', |
|
'validator': frontend.validate_boolean}), |
|
('Disable compact simple bullet and enumerated lists.', |
|
['--no-compact-lists'], |
|
{'dest': 'compact_lists', 'action': 'store_false'}), |
|
('Remove extra vertical whitespace between items of simple field ' |
|
'lists. Default: enabled.', |
|
['--compact-field-lists'], |
|
{'default': True, 'action': 'store_true', |
|
'validator': frontend.validate_boolean}), |
|
('Disable compact simple field lists.', |
|
['--no-compact-field-lists'], |
|
{'dest': 'compact_field_lists', 'action': 'store_false'}), |
|
('Added to standard table classes. ' |
|
'Defined styles: borderless, booktabs, ' |
|
'align-left, align-center, align-right, colwidths-auto. ' |
|
'Default: ""', |
|
['--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. (Thwarts HTML5 conformance.) ' |
|
'Default: False', |
|
['--xml-declaration'], |
|
{'default': False, 'action': 'store_true', |
|
'validator': frontend.validate_boolean}), |
|
('Omit the XML declaration.', |
|
['--no-xml-declaration'], |
|
{'dest': 'xml_declaration', 'action': 'store_false'}), |
|
('Obfuscate email addresses to confuse harvesters while still ' |
|
'keeping email links usable with standards-compliant browsers.', |
|
['--cloak-email-addresses'], |
|
{'action': 'store_true', 'validator': frontend.validate_boolean}),)) |
|
|
|
config_section = 'html5 writer' |
|
|
|
def __init__(self): |
|
self.parts = {} |
|
self.translator_class = HTMLTranslator |
|
|
|
|
|
class HTMLTranslator(writers._html_base.HTMLTranslator): |
|
""" |
|
This writer generates `polyglot markup`: HTML5 that is also valid XML. |
|
|
|
Safe subclassing: when overriding, treat ``visit_*`` and ``depart_*`` |
|
methods as a unit to prevent breaks due to internal changes. See the |
|
docstring of docutils.writers._html_base.HTMLTranslator for details |
|
and examples. |
|
""" |
|
|
|
# <acronym> tag not supported in HTML5. Use the <abbr> tag instead. |
|
def visit_acronym(self, node): |
|
# @@@ implementation incomplete ("title" attribute) |
|
self.body.append(self.starttag(node, 'abbr', '')) |
|
def depart_acronym(self, node): |
|
self.body.append('</abbr>') |
|
|
|
# no meta tag in HTML5 |
|
def visit_authors(self, node): |
|
self.visit_docinfo_item(node, 'authors', meta=False) |
|
def depart_authors(self, node): |
|
self.depart_docinfo_item() |
|
|
|
# no meta tag in HTML5 |
|
def visit_copyright(self, node): |
|
self.visit_docinfo_item(node, 'copyright', meta=False) |
|
def depart_copyright(self, node): |
|
self.depart_docinfo_item() |
|
|
|
# no meta tag in HTML5 |
|
def visit_date(self, node): |
|
self.visit_docinfo_item(node, 'date', meta=False) |
|
def depart_date(self, node): |
|
self.depart_docinfo_item() |
|
|
|
# TODO: use HTML5 <footer> element? |
|
# def visit_footer(self, node): |
|
# def depart_footer(self, node): |
|
|
|
# TODO: use the new HTML5 element <aside>? (Also for footnote text) |
|
# def visit_footnote(self, node): |
|
# def depart_footnote(self, node): |
|
|
|
# Meta tags: 'lang' attribute replaced by 'xml:lang' in XHTML 1.1 |
|
# HTML5/polyglot recommends using both |
|
def visit_meta(self, node): |
|
if node.hasattr('lang'): |
|
node['xml:lang'] = node['lang'] |
|
# del(node['lang']) |
|
meta = self.emptytag(node, 'meta', **node.non_default_attributes()) |
|
self.add_meta(meta) |
|
def depart_meta(self, node): |
|
pass |
|
|
|
# no meta tag in HTML5 |
|
def visit_organization(self, node): |
|
self.visit_docinfo_item(node, 'organization', meta=False) |
|
def depart_organization(self, node): |
|
self.depart_docinfo_item() |
|
|
|
# TODO: use the new HTML5 element <section>? |
|
# def visit_section(self, node): |
|
# def depart_section(self, node): |
|
|
|
# TODO: use the new HTML5 element <aside>? |
|
# def visit_topic(self, node): |
|
# def depart_topic(self, node):
|
|
|