Merge pull request #5850 from jfbu/latex_sphinxmaketitle

LaTeX: ``\sphinxmaketitle`` and optional ``\sphinxbackoftitlepage``

CHANGES

@@ -13,6 +13,10 @@ Deprecated
 Features added
 --------------
 
+* LaTeX: it is possible to insert custom material to appear on back of title
+  page, see discussion of ``'maketitle'`` key of :confval:`latex_elements`
+  (``'manual'`` docclass only)
+
 Bugs fixed
 ----------
 
@@ -29,6 +33,8 @@ Bugs fixed
 * #5496 (again): C++, fix assertion in partial builds with duplicates.
 * #5724: quickstart: sphinx-quickstart fails when $LC_ALL is empty
 * #1956: Default conf.py is not PEP8-compliant
+* #5849: LaTeX: document class ``\maketitle`` is overwritten with no
+  possibility to use original meaning in place of Sphinx custom one
 * #5834: apidoc: wrong help for ``--tocfile``
 * #5800: todo: crashed if todo is defined in TextElement
 

doc/latex.rst

@@ -395,8 +395,20 @@ Macros
 
   .. versionchanged:: 1.5
      formerly, the meaning of ``\tableofcontents`` was modified by Sphinx.
-- the ``\maketitle`` command is redefined by the class files
-  :file:`sphinxmanual.cls` and :file:`sphinxhowto.cls`.
+- a custom ``\sphinxmaketitle`` is defined in the class files
+  :file:`sphinxmanual.cls` and :file:`sphinxhowto.cls` and is used as
+  default setting of ``'maketitle'`` :confval:`latex_elements` key.
+
+  .. versionchanged:: 1.8.3
+     formerly, ``\maketitle`` from LaTeX document class was modified by
+     Sphinx.
+- for ``'manual'`` docclass a macro ``\sphinxbackoftitlepage``, if it is
+  defined, gets executed at end of ``\sphinxmaketitle``, before the final
+  ``\clearpage``.  Use either the ``'maketitle'`` key or the ``'preamble'`` key
+  of :confval:`latex_elements` to add a custom definition of
+  ``\sphinxbackoftitlepage``.
+
+  .. versionadded:: 1.8.3
 - the citation reference is typeset via ``\sphinxcite`` which is a wrapper
   of standard ``\cite``.
 

doc/usage/configuration.rst

@@ -2172,10 +2172,22 @@ information.
            Previously this was done from inside :file:`sphinx.sty`.
 
      ``'maketitle'``
-        "maketitle" call, default ``'\\maketitle'`` (but it has been
-        redefined by the Sphinx ``manual`` and ``howto`` classes.) Override
-        if you want to generate a differently-styled title page.
+        "maketitle" call, default ``'\\sphinxmaketitle'``. Override
+        if you want to generate a differently styled title page.
 
+        .. hint::
+
+           If the key value is set to
+           ``r'\newcommand\sphinxbackoftitlepage{<Extra
+           material>}\sphinxmaketitle'``, then ``<Extra material>`` will be
+           typeset on back of title page (``'manual'`` docclass only).
+
+        .. versionchanged:: 1.8.3
+           Original ``\maketitle`` from document class is not overwritten,
+           hence is re-usable as part of some custom setting for this key.
+        .. versionadded:: 1.8.3
+           ``\sphinxbackoftitlepage`` optional macro.  It can also be defined
+           inside ``'preamble'`` key rather than this one.
      ``'releasename'``
         value that prefixes ``'release'`` element on title page, default
         ``'Release'``. As for *title* and *author* used in the tuples of

sphinx/texinputs/sphinxhowto.cls

@@ -3,7 +3,7 @@
 %
 
 \NeedsTeXFormat{LaTeX2e}[1995/12/01]
-\ProvidesClass{sphinxhowto}[2018/09/18 v1.8.1 Document class (Sphinx HOWTO)]
+\ProvidesClass{sphinxhowto}[2018/12/22 v1.8.3 Document class (Sphinx howto)]
 
 % 'oneside' option overriding the 'twoside' default
 \newif\if@oneside
@@ -30,7 +30,7 @@
 % Change the title page to look a bit better, and fit in with the fncychap
 % ``Bjarne'' style a bit better.
 %
-\renewcommand{\maketitle}{%
+\newcommand{\sphinxmaketitle}{%
   \noindent\rule{\textwidth}{1pt}\par
     \begingroup % for PDF information dictionary
        \def\endgraf{ }\def\and{\& }%

sphinx/texinputs/sphinxmanual.cls

@@ -3,7 +3,7 @@
 %
 
 \NeedsTeXFormat{LaTeX2e}[1995/12/01]
-\ProvidesClass{sphinxmanual}[2018/09/18 v1.8.1 Document class (Sphinx manual)]
+\ProvidesClass{sphinxmanual}[2018/12/22 v1.8.3 Document class (Sphinx manual)]
 
 % chapters starting at odd pages (overridden by 'openany' document option)
 \PassOptionsToClass{openright}{\sphinxdocclass}
@@ -33,7 +33,7 @@
 % Change the title page to look a bit better, and fit in with the fncychap
 % ``Bjarne'' style a bit better.
 %
-\renewcommand{\maketitle}{%
+\newcommand{\sphinxmaketitle}{%
   \let\spx@tempa\relax
   \ifHy@pageanchor\def\spx@tempa{\Hy@pageanchortrue}\fi
   \hypersetup{pageanchor=false}% avoid duplicate destination warnings
@@ -69,6 +69,8 @@
   \setcounter{footnote}{0}%
   \let\thanks\relax\let\maketitle\relax
   %\gdef\@thanks{}\gdef\@author{}\gdef\@title{}
+  \clearpage
+  \ifdefined\sphinxbackoftitlepage\sphinxbackoftitlepage\fi
   \if@openright\cleardoublepage\else\clearpage\fi
   \spx@tempa
 }

sphinx/writers/latex.py

@@ -106,7 +106,7 @@ DEFAULT_SETTINGS = {
     'releasename':     '',
     'makeindex':       '\\makeindex',
     'shorthandoff':    '',
-    'maketitle':       '\\maketitle',
+    'maketitle':       '\\sphinxmaketitle',
     'tableofcontents': '\\sphinxtableofcontents',
     'atendofbody':     '',
     'printindex':      '\\printindex',