?  search:
summary | log | graphiclog1 | graphiclog2 | commit | commitdiff | tree | refs | edit | fork
blame | history | raw | HEAD
Reconcile Docutils DTD and Document Tree documentation.
[docutils.git] / docutils / docutils / writers / html5_polyglot / __init__.py
blob6005c22ac48fbc4fe4a8b8b2e486394320f50320
1 # $Id$
2 # :Author: Günter Milde <milde@users.sf.net>
3 # Based on the html4css1 writer by David Goodger.
4 # :Maintainer: docutils-develop@lists.sourceforge.net
5 # :Copyright: © 2005, 2009, 2015 Günter Milde,
6 # portions from html4css1 © David Goodger.
7 # :License: Released under the terms of the `2-Clause BSD license`_, in short:
8 #
9 # Copying and distribution of this file, with or without modification,
10 # are permitted in any medium without royalty provided the copyright
11 # notice and this notice are preserved.
12 # This file is offered as-is, without any warranty.
13 #
14 # .. _2-Clause BSD license: https://opensource.org/licenses/BSD-2-Clause
15
16 # Use "best practice" as recommended by the W3C:
17 # http://www.w3.org/2009/cheatsheet/
18
19 """
20 Plain HyperText Markup Language document tree Writer.
21
22 The output conforms to the `HTML 5` specification.
23
24 The cascading style sheet "minimal.css" is required for proper viewing,
25 the style sheet "plain.css" improves reading experience.
26 """
27 __docformat__ = 'reStructuredText'
28
29 from pathlib import Path
30
31 from docutils import frontend, nodes
32 from docutils.writers import _html_base
33
34
35 class Writer(_html_base.Writer):
36
37 supported = ('html5', 'xhtml', 'html')
38 """Formats this writer supports."""
39
40 default_stylesheets = ['minimal.css', 'plain.css']
41 default_stylesheet_dirs = ['.', str(Path(__file__).parent)]
42 default_template = Path(__file__).parent / 'template.txt'
43
44 # use a copy of the parent spec with some modifications
45 settings_spec = frontend.filter_settings_spec(
46 _html_base.Writer.settings_spec,
47 template=(
48 f'Template file. (UTF-8 encoded, default: "{default_template}")',
49 ['--template'],
50 {'default': default_template, 'metavar': '<file>'}),
51 stylesheet_path=(
52 'Comma separated list of stylesheet paths. '
53 'Relative paths are expanded if a matching file is found in '
54 'the --stylesheet-dirs. With --link-stylesheet, '
55 'the path is rewritten relative to the output HTML file. '
56 '(default: "%s")' % ','.join(default_stylesheets),
57 ['--stylesheet-path'],
58 {'metavar': '<file[,file,...]>', 'overrides': 'stylesheet',
59 'validator': frontend.validate_comma_separated_list,
60 'default': default_stylesheets}),
61 stylesheet_dirs=(
62 'Comma-separated list of directories where stylesheets are found. '
63 'Used by --stylesheet-path when expanding relative path '
64 'arguments. (default: "%s")' % ','.join(default_stylesheet_dirs),
65 ['--stylesheet-dirs'],
66 {'metavar': '<dir[,dir,...]>',
67 'validator': frontend.validate_comma_separated_list,
68 'default': default_stylesheet_dirs}),
69 initial_header_level=(
70 'Specify the initial header level. Does not affect document '
71 'title & subtitle (see --no-doc-title). (default: 2 for "<h2>")',
72 ['--initial-header-level'],
73 {'choices': '1 2 3 4 5 6'.split(), 'default': '2',
74 'metavar': '<level>'}),
75 no_xml_declaration=(
76 'Omit the XML declaration (default).',
77 ['--no-xml-declaration'],
78 {'dest': 'xml_declaration', 'action': 'store_false'}),
79 )
80 settings_spec = settings_spec + (
81 'HTML5 Writer Options',
82 '',
83 ((frontend.SUPPRESS_HELP, # Obsoleted by "--image-loading"
84 ['--embed-images'],
85 {'action': 'store_true',
86 'validator': frontend.validate_boolean}),
87 (frontend.SUPPRESS_HELP, # Obsoleted by "--image-loading"
88 ['--link-images'],
89 {'dest': 'embed_images', 'action': 'store_false'}),
90 ('Suggest at which point images should be loaded: '
91 '"embed", "link" (default), or "lazy".',
92 ['--image-loading'],
93 {'choices': ('embed', 'link', 'lazy'),
94 # 'default': 'link' # default set in _html_base.py
95 }),
96 ('Append a self-link to section headings.',
97 ['--section-self-link'],
98 {'default': False, 'action': 'store_true'}),
99 ('Do not append a self-link to section headings. (default)',
100 ['--no-section-self-link'],
101 {'dest': 'section_self_link', 'action': 'store_false'}),
102 )
103 )
104
105 config_section = 'html5 writer'
106
107 def __init__(self):
108 self.parts = {}
109 self.translator_class = HTMLTranslator
110
111
112 class HTMLTranslator(_html_base.HTMLTranslator):
113 """
114 This writer generates `polyglot markup`: HTML5 that is also valid XML.
115
116 Safe subclassing: when overriding, treat ``visit_*`` and ``depart_*``
117 methods as a unit to prevent breaks due to internal changes. See the
118 docstring of docutils.writers._html_base.HTMLTranslator for details
119 and examples.
120 """
121
122 # self.starttag() arguments for the main document
123 documenttag_args = {'tagname': 'main'}
124
125 # add meta tag to fix rendering in mobile browsers
126 def __init__(self, document):
127 super().__init__(document)
128 self.meta.append('<meta name="viewport" '
129 'content="width=device-width, initial-scale=1" />\n')
130
131 # <acronym> tag obsolete in HTML5. Use the <abbr> tag instead.
132 def visit_acronym(self, node):
133 # @@@ implementation incomplete ("title" attribute)
134 self.body.append(self.starttag(node, 'abbr', ''))
135
136 def depart_acronym(self, node):
137 self.body.append('</abbr>')
138
139 # no standard meta tag name in HTML5, use separate "author" meta tags
140 # https://www.w3.org/TR/html5/document-metadata.html#standard-metadata-names
141 def visit_authors(self, node):
142 self.visit_docinfo_item(node, 'authors', meta=False)
143 for subnode in node:
144 self.meta.append('<meta name="author" content='
145 f'"{self.attval(subnode.astext())}" />\n')
146
147 def depart_authors(self, node):
148 self.depart_docinfo_item()
149
150 # use the <figcaption> semantic tag.
151 def visit_caption(self, node):
152 if isinstance(node.parent, nodes.figure):
153 self.body.append('<figcaption>\n')
154 self.body.append(self.starttag(node, 'p', ''))
155
156 def depart_caption(self, node):
157 self.body.append('</p>\n')
158 # <figcaption> is closed in depart_figure(), as legend may follow.
159
160 # use HTML block-level tags if matching class value found
161 supported_block_tags = {'ins', 'del'}
162
163 def visit_container(self, node):
164 # If there is exactly one of the "supported block tags" in
165 # the list of class values, use it as tag name:
166 classes = node['classes']
167 tags = [cls for cls in classes
168 if cls in self.supported_block_tags]
169 if len(tags) == 1:
170 node.html5tagname = tags[0]
171 classes.remove(tags[0])
172 else:
173 node.html5tagname = 'div'
174 self.body.append(self.starttag(node, node.html5tagname,
175 CLASS='docutils container'))
176
177 def depart_container(self, node):
178 self.body.append(f'</{node.html5tagname}>\n')
179 del node.html5tagname
180
181 # no standard meta tag name in HTML5, use dcterms.rights
182 # see https://wiki.whatwg.org/wiki/MetaExtensions
183 def visit_copyright(self, node):
184 self.visit_docinfo_item(node, 'copyright', meta=False)
185 self.meta.append('<meta name="dcterms.rights" '
186 f'content="{self.attval(node.astext())}" />\n')
187
188 def depart_copyright(self, node):
189 self.depart_docinfo_item()
190
191 # no standard meta tag name in HTML5, use dcterms.date
192 def visit_date(self, node):
193 self.visit_docinfo_item(node, 'date', meta=False)
194 self.meta.append('<meta name="dcterms.date" '
195 f'content="{self.attval(node.astext())}" />\n')
196
197 def depart_date(self, node):
198 self.depart_docinfo_item()
199
200 # use new HTML5 <figure> and <figcaption> elements
201 def visit_figure(self, node):
202 atts = {}
203 if node.get('width'):
204 atts['style'] = f"width: {node['width']}"
205 if node.get('align'):
206 atts['class'] = f"align-{node['align']}"
207 self.body.append(self.starttag(node, 'figure', **atts))
208
209 def depart_figure(self, node):
210 if len(node) > 1:
211 self.body.append('</figcaption>\n')
212 self.body.append('</figure>\n')
213
214 # use HTML5 <footer> element
215 def visit_footer(self, node):
216 self.context.append(len(self.body))
217
218 def depart_footer(self, node):
219 start = self.context.pop()
220 footer = [self.starttag(node, 'footer')]
221 footer.extend(self.body[start:])
222 footer.append('</footer>\n')
223 self.footer.extend(footer)
224 self.body_suffix[:0] = footer
225 del self.body[start:]
226
227 # use HTML5 <header> element
228 def visit_header(self, node):
229 self.context.append(len(self.body))
230
231 def depart_header(self, node):
232 start = self.context.pop()
233 header = [self.starttag(node, 'header')]
234 header.extend(self.body[start:])
235 header.append('</header>\n')
236 self.body_prefix.extend(header)
237 self.header.extend(header)
238 del self.body[start:]
239
240 # use HTML text-level tags if matching class value found
241 supported_inline_tags = {'code', 'kbd', 'dfn', 'samp', 'var',
242 'bdi', 'del', 'ins', 'mark', 'small',
243 'b', 'i', 'q', 's', 'u'}
244
245 # Use `supported_inline_tags` if found in class values
246 def visit_inline(self, node):
247 classes = node['classes']
248 node.html5tagname = 'span'
249 # Special handling for "code" directive content
250 if (isinstance(node.parent, nodes.literal_block)
251 and 'code' in node.parent.get('classes')
252 or isinstance(node.parent, nodes.literal)
253 and getattr(node.parent, 'html5tagname', None) == 'code'):
254 if classes == ['ln']:
255 # line numbers are not part of the "fragment of computer code"
256 if self.body[-1] == '<code>':
257 del self.body[-1]
258 else:
259 self.body.append('</code>')
260 node.html5tagname = 'small'
261 else:
262 tags = [cls for cls in self.supported_inline_tags
263 if cls in classes]
264 if len(tags):
265 node.html5tagname = tags[0]
266 classes.remove(node.html5tagname)
267 self.body.append(self.starttag(node, node.html5tagname, ''))
268
269 def depart_inline(self, node):
270 self.body.append(f'</{node.html5tagname}>')
271 if (node.html5tagname == 'small' and node.get('classes') == ['ln']
272 and isinstance(node.parent, nodes.literal_block)):
273 self.body.append(f'<code data-lineno="{node.astext()}">')
274 del node.html5tagname
275
276 # place inside HTML5 <figcaption> element (together with caption)
277 def visit_legend(self, node):
278 if not isinstance(node.parent[1], nodes.caption):
279 self.body.append('<figcaption>\n')
280 self.body.append(self.starttag(node, 'div', CLASS='legend'))
281
282 def depart_legend(self, node):
283 self.body.append('</div>\n')
284 # <figcaption> closed in visit_figure()
285
286 # use HTML5 text-level tags if matching class value found
287 def visit_literal(self, node):
288 classes = node['classes']
289 html5tagname = 'span'
290 tags = [cls for cls in self.supported_inline_tags
291 if cls in classes]
292 if len(tags):
293 html5tagname = tags[0]
294 classes.remove(html5tagname)
295 if html5tagname == 'code':
296 node.html5tagname = html5tagname
297 self.body.append(self.starttag(node, html5tagname, ''))
298 return
299 self.body.append(
300 self.starttag(node, html5tagname, '', CLASS='docutils literal'))
301 text = node.astext()
302 # remove hard line breaks (except if in a parsed-literal block)
303 if not isinstance(node.parent, nodes.literal_block):
304 text = text.replace('\n', ' ')
305 # Protect text like ``--an-option`` and the regular expression
306 # ``[+]?(\d+(\.\d*)?|\.\d+)`` from bad line wrapping
307 for token in self.words_and_spaces.findall(text):
308 if token.strip() and self.in_word_wrap_point.search(token):
309 self.body.append(
310 f'<span class="pre">{self.encode(token)}</span>')
311 else:
312 self.body.append(self.encode(token))
313 self.body.append(f'</{html5tagname}>')
314 # Content already processed:
315 raise nodes.SkipNode
316
317 def depart_literal(self, node):
318 # skipped unless literal element is from "code" role:
319 self.depart_inline(node)
320
321 # Meta tags: 'lang' attribute replaced by 'xml:lang' in XHTML 1.1
322 # HTML5/polyglot recommends using both
323 def visit_meta(self, node):
324 if node.hasattr('lang'):
325 node['xml:lang'] = node['lang']
326 self.meta.append(self.emptytag(node, 'meta',
327 **node.non_default_attributes()))
328
329 def depart_meta(self, node):
330 pass
331
332 # no standard meta tag name in HTML5
333 def visit_organization(self, node):
334 self.visit_docinfo_item(node, 'organization', meta=False)
335
336 def depart_organization(self, node):
337 self.depart_docinfo_item()
338
339 # use the new HTML5 element <section>
340 def visit_section(self, node):
341 self.section_level += 1
342 self.body.append(
343 self.starttag(node, 'section'))
344
345 def depart_section(self, node):
346 self.section_level -= 1
347 self.body.append('</section>\n')
348
349 # use the new HTML5 element <aside>
350 def visit_sidebar(self, node):
351 self.body.append(
352 self.starttag(node, 'aside', CLASS='sidebar'))
353 self.in_sidebar = True
354
355 def depart_sidebar(self, node):
356 self.body.append('</aside>\n')
357 self.in_sidebar = False
358
359 # Use new HTML5 element <aside> or <nav>
360 # Add class value to <body>, if there is a ToC in the document
361 # (see responsive.css how this is used for a navigation sidebar).
362 def visit_topic(self, node):
363 atts = {'classes': ['topic']}
364 if 'contents' in node['classes']:
365 node.html5tagname = 'nav'
366 del atts['classes']
367 if isinstance(node.parent, nodes.document):
368 atts['role'] = 'doc-toc'
369 self.body_prefix[0] = '</head>\n<body class="with-toc">\n'
370 elif 'abstract' in node['classes']:
371 node.html5tagname = 'div'
372 atts['role'] = 'doc-abstract'
373 elif 'dedication' in node['classes']:
374 node.html5tagname = 'div'
375 atts['role'] = 'doc-dedication'
376 else:
377 node.html5tagname = 'aside'
378 self.body.append(self.starttag(node, node.html5tagname, **atts))
379
380 def depart_topic(self, node):
381 self.body.append(f'</{node.html5tagname}>\n')
382 del node.html5tagname
383
384 # append self-link
385 def section_title_tags(self, node):
386 start_tag, close_tag = super().section_title_tags(node)
387 ids = node.parent['ids']
388 if (ids and getattr(self.settings, 'section_self_link', None)
389 and not isinstance(node.parent, nodes.document)):
390 self_link = ('<a class="self-link" title="link to this section"'
391 f' href="#{ids[0]}"></a>')
392 close_tag = close_tag.replace('</h', self_link + '</h')
393 return start_tag, close_tag
docutils git mirror