From abb1e49e6258c16ea052a14c1b3a3950b48cffe7 Mon Sep 17 00:00:00 2001
From: milde <milde@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Wed, 1 Mar 2017 10:57:46 +0000
Subject: [PATCH] Document and use safe subclassing.

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk@8040 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 .../docutils/writers/html5_polyglot/__init__.py    | 23 ++++++++++++++++++----
 1 file changed, 19 insertions(+), 4 deletions(-)

diff --git a/docutils/docutils/writers/html5_polyglot/__init__.py b/docutils/docutils/writers/html5_polyglot/__init__.py
index 0d5d14a8c..0f461acac 100644
--- a/docutils/docutils/writers/html5_polyglot/__init__.py
+++ b/docutils/docutils/writers/html5_polyglot/__init__.py
@@ -148,29 +148,37 @@ class Writer(writers._html_base.Writer):
 class HTMLTranslator(writers._html_base.HTMLTranslator):
     """
     This writer generates `polyglot markup`: HTML5 that is also valid XML.
-    """
-    # def __init__(self, document):
-    #     writers._html_base.HTMLTranslator.__init__(self, document)
 
+    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):
@@ -178,6 +186,7 @@ class HTMLTranslator(writers._html_base.HTMLTranslator):
 
     # 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
@@ -187,13 +196,19 @@ class HTMLTranslator(writers._html_base.HTMLTranslator):
             # 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):
-- 
2.11.4.GIT