Mercurial > repos > shellac > sam_consensus_v3
comparison env/lib/python3.9/site-packages/docutils/writers/html5_polyglot/__init__.py @ 0:4f3585e2f14b draft default tip
"planemo upload commit 60cee0fc7c0cda8592644e1aad72851dec82c959"
author | shellac |
---|---|
date | Mon, 22 Mar 2021 18:12:50 +0000 |
parents | |
children |
comparison
equal
deleted
inserted
replaced
-1:000000000000 | 0:4f3585e2f14b |
---|---|
1 # .. coding: utf-8 | |
2 # $Id: __init__.py 8410 2019-11-04 21:14:43Z milde $ | |
3 # :Author: Günter Milde <milde@users.sf.net> | |
4 # Based on the html4css1 writer by David Goodger. | |
5 # :Maintainer: docutils-develop@lists.sourceforge.net | |
6 # :Copyright: © 2005, 2009, 2015 Günter Milde, | |
7 # portions from html4css1 © David Goodger. | |
8 # :License: Released under the terms of the `2-Clause BSD license`_, in short: | |
9 # | |
10 # Copying and distribution of this file, with or without modification, | |
11 # are permitted in any medium without royalty provided the copyright | |
12 # notice and this notice are preserved. | |
13 # This file is offered as-is, without any warranty. | |
14 # | |
15 # .. _2-Clause BSD license: http://www.spdx.org/licenses/BSD-2-Clause | |
16 | |
17 # Use "best practice" as recommended by the W3C: | |
18 # http://www.w3.org/2009/cheatsheet/ | |
19 | |
20 """ | |
21 Plain HyperText Markup Language document tree Writer. | |
22 | |
23 The output conforms to the `HTML 5` specification. | |
24 | |
25 The cascading style sheet "minimal.css" is required for proper viewing, | |
26 the style sheet "plain.css" improves reading experience. | |
27 """ | |
28 __docformat__ = 'reStructuredText' | |
29 | |
30 import os.path | |
31 import docutils | |
32 from docutils import frontend, nodes, writers, io | |
33 from docutils.transforms import writer_aux | |
34 from docutils.writers import _html_base | |
35 | |
36 class Writer(writers._html_base.Writer): | |
37 | |
38 supported = ('html', 'html5', 'html4', 'xhtml', 'xhtml10') | |
39 """Formats this writer supports.""" | |
40 | |
41 default_stylesheets = ['minimal.css', 'plain.css'] | |
42 default_stylesheet_dirs = ['.', os.path.abspath(os.path.dirname(__file__))] | |
43 | |
44 default_template = 'template.txt' | |
45 default_template_path = os.path.join( | |
46 os.path.dirname(os.path.abspath(__file__)), default_template) | |
47 | |
48 settings_spec = ( | |
49 'HTML-Specific Options', | |
50 None, | |
51 (('Specify the template file (UTF-8 encoded). Default is "%s".' | |
52 % default_template_path, | |
53 ['--template'], | |
54 {'default': default_template_path, 'metavar': '<file>'}), | |
55 ('Comma separated list of stylesheet URLs. ' | |
56 'Overrides previous --stylesheet and --stylesheet-path settings.', | |
57 ['--stylesheet'], | |
58 {'metavar': '<URL[,URL,...]>', 'overrides': 'stylesheet_path', | |
59 'validator': frontend.validate_comma_separated_list}), | |
60 ('Comma separated list of stylesheet paths. ' | |
61 'Relative paths are expanded if a matching file is found in ' | |
62 'the --stylesheet-dirs. With --link-stylesheet, ' | |
63 'the path is rewritten relative to the output HTML file. ' | |
64 'Default: "%s"' % ','.join(default_stylesheets), | |
65 ['--stylesheet-path'], | |
66 {'metavar': '<file[,file,...]>', 'overrides': 'stylesheet', | |
67 'validator': frontend.validate_comma_separated_list, | |
68 'default': default_stylesheets}), | |
69 ('Embed the stylesheet(s) in the output HTML file. The stylesheet ' | |
70 'files must be accessible during processing. This is the default.', | |
71 ['--embed-stylesheet'], | |
72 {'default': 1, 'action': 'store_true', | |
73 'validator': frontend.validate_boolean}), | |
74 ('Link to the stylesheet(s) in the output HTML file. ' | |
75 'Default: embed stylesheets.', | |
76 ['--link-stylesheet'], | |
77 {'dest': 'embed_stylesheet', 'action': 'store_false'}), | |
78 ('Comma-separated list of directories where stylesheets are found. ' | |
79 'Used by --stylesheet-path when expanding relative path arguments. ' | |
80 'Default: "%s"' % default_stylesheet_dirs, | |
81 ['--stylesheet-dirs'], | |
82 {'metavar': '<dir[,dir,...]>', | |
83 'validator': frontend.validate_comma_separated_list, | |
84 'default': default_stylesheet_dirs}), | |
85 ('Specify the initial header level. Default is 1 for "<h1>". ' | |
86 'Does not affect document title & subtitle (see --no-doc-title).', | |
87 ['--initial-header-level'], | |
88 {'choices': '1 2 3 4 5 6'.split(), 'default': '1', | |
89 'metavar': '<level>'}), | |
90 ('Format for footnote references: one of "superscript" or ' | |
91 '"brackets". Default is "brackets".', | |
92 ['--footnote-references'], | |
93 {'choices': ['superscript', 'brackets'], 'default': 'brackets', | |
94 'metavar': '<format>', | |
95 'overrides': 'trim_footnote_reference_space'}), | |
96 ('Format for block quote attributions: one of "dash" (em-dash ' | |
97 'prefix), "parentheses"/"parens", or "none". Default is "dash".', | |
98 ['--attribution'], | |
99 {'choices': ['dash', 'parentheses', 'parens', 'none'], | |
100 'default': 'dash', 'metavar': '<format>'}), | |
101 ('Remove extra vertical whitespace between items of "simple" bullet ' | |
102 'lists and enumerated lists. Default: enabled.', | |
103 ['--compact-lists'], | |
104 {'default': True, 'action': 'store_true', | |
105 'validator': frontend.validate_boolean}), | |
106 ('Disable compact simple bullet and enumerated lists.', | |
107 ['--no-compact-lists'], | |
108 {'dest': 'compact_lists', 'action': 'store_false'}), | |
109 ('Remove extra vertical whitespace between items of simple field ' | |
110 'lists. Default: enabled.', | |
111 ['--compact-field-lists'], | |
112 {'default': True, 'action': 'store_true', | |
113 'validator': frontend.validate_boolean}), | |
114 ('Disable compact simple field lists.', | |
115 ['--no-compact-field-lists'], | |
116 {'dest': 'compact_field_lists', 'action': 'store_false'}), | |
117 ('Added to standard table classes. ' | |
118 'Defined styles: borderless, booktabs, ' | |
119 'align-left, align-center, align-right, colwidths-auto. ' | |
120 'Default: ""', | |
121 ['--table-style'], | |
122 {'default': ''}), | |
123 ('Math output format (one of "MathML", "HTML", "MathJax", ' | |
124 'or "LaTeX") and option(s). ' | |
125 'Default: "HTML math.css"', | |
126 ['--math-output'], | |
127 {'default': 'HTML math.css'}), | |
128 ('Prepend an XML declaration. (Thwarts HTML5 conformance.) ' | |
129 'Default: False', | |
130 ['--xml-declaration'], | |
131 {'default': False, 'action': 'store_true', | |
132 'validator': frontend.validate_boolean}), | |
133 ('Omit the XML declaration.', | |
134 ['--no-xml-declaration'], | |
135 {'dest': 'xml_declaration', 'action': 'store_false'}), | |
136 ('Obfuscate email addresses to confuse harvesters while still ' | |
137 'keeping email links usable with standards-compliant browsers.', | |
138 ['--cloak-email-addresses'], | |
139 {'action': 'store_true', 'validator': frontend.validate_boolean}),)) | |
140 | |
141 config_section = 'html5 writer' | |
142 | |
143 def __init__(self): | |
144 self.parts = {} | |
145 self.translator_class = HTMLTranslator | |
146 | |
147 | |
148 class HTMLTranslator(writers._html_base.HTMLTranslator): | |
149 """ | |
150 This writer generates `polyglot markup`: HTML5 that is also valid XML. | |
151 | |
152 Safe subclassing: when overriding, treat ``visit_*`` and ``depart_*`` | |
153 methods as a unit to prevent breaks due to internal changes. See the | |
154 docstring of docutils.writers._html_base.HTMLTranslator for details | |
155 and examples. | |
156 """ | |
157 | |
158 # <acronym> tag obsolete in HTML5. Use the <abbr> tag instead. | |
159 def visit_acronym(self, node): | |
160 # @@@ implementation incomplete ("title" attribute) | |
161 self.body.append(self.starttag(node, 'abbr', '')) | |
162 def depart_acronym(self, node): | |
163 self.body.append('</abbr>') | |
164 | |
165 # no standard meta tag name in HTML5, use separate "author" meta tags | |
166 # https://www.w3.org/TR/html5/document-metadata.html#standard-metadata-names | |
167 def visit_authors(self, node): | |
168 self.visit_docinfo_item(node, 'authors', meta=False) | |
169 for subnode in node: | |
170 self.add_meta('<meta name="author" content="%s" />\n' % | |
171 self.attval(subnode.astext())) | |
172 def depart_authors(self, node): | |
173 self.depart_docinfo_item() | |
174 | |
175 # no standard meta tag name in HTML5, use dcterms.rights | |
176 # see https://wiki.whatwg.org/wiki/MetaExtensions | |
177 def visit_copyright(self, node): | |
178 self.visit_docinfo_item(node, 'copyright', meta=False) | |
179 self.add_meta('<meta name="dcterms.rights" content="%s" />\n' | |
180 % self.attval(node.astext())) | |
181 def depart_copyright(self, node): | |
182 self.depart_docinfo_item() | |
183 | |
184 # no standard meta tag name in HTML5, use dcterms.date | |
185 def visit_date(self, node): | |
186 self.visit_docinfo_item(node, 'date', meta=False) | |
187 self.add_meta('<meta name="dcterms.date" content="%s" />\n' | |
188 % self.attval(node.astext())) | |
189 def depart_date(self, node): | |
190 self.depart_docinfo_item() | |
191 | |
192 # TODO: use HTML5 <footer> element? | |
193 # def visit_footer(self, node): | |
194 # def depart_footer(self, node): | |
195 | |
196 # TODO: use the new HTML5 element <aside>? (Also for footnote text) | |
197 # def visit_footnote(self, node): | |
198 # def depart_footnote(self, node): | |
199 | |
200 # Meta tags: 'lang' attribute replaced by 'xml:lang' in XHTML 1.1 | |
201 # HTML5/polyglot recommends using both | |
202 def visit_meta(self, node): | |
203 if node.hasattr('lang'): | |
204 node['xml:lang'] = node['lang'] | |
205 # del(node['lang']) | |
206 meta = self.emptytag(node, 'meta', **node.non_default_attributes()) | |
207 self.add_meta(meta) | |
208 def depart_meta(self, node): | |
209 pass | |
210 | |
211 # no standard meta tag name in HTML5 | |
212 def visit_organization(self, node): | |
213 self.visit_docinfo_item(node, 'organization', meta=False) | |
214 def depart_organization(self, node): | |
215 self.depart_docinfo_item() | |
216 | |
217 # TODO: use the new HTML5 element <section>? | |
218 # def visit_section(self, node): | |
219 # def depart_section(self, node): |