latex: hint that code-blocks continue on next page (closes #3764)

CHANGES

@@ -13,6 +13,8 @@ Deprecated
 Features added
 --------------
 
+* latex: hint that code-block continues on next page (refs: #3764, #3792)
+
 Bugs fixed
 ----------
 

doc/latex.rst

@@ -189,6 +189,15 @@ The available styling options
     default ``true``. Tells whether long lines in :rst:dir:`code-block`\ 's
     contents should wrap.
 
+``verbatimhintsturnover``
+    default ``false``. If ``true``, code-blocks display "continued on next
+    page", "continued from previous page" hints in case of pagebreaks.
+
+    .. versionadded:: 1.6.3
+       the default will change to ``true`` at 1.7 and horizontal positioning
+       of continuation hints (currently right aligned only) will be
+       customizable.
+
 ``parsedliteralwraps``
     default ``true``. Tells whether long lines in :dudir:`parsed-literal`\ 's
     contents should wrap.
@@ -359,7 +368,8 @@ Macros
   ``indexentry``, ``indexextra``, ``indexpageref``, ``topictitle``,
   ``sidebartitle``, ``othertitle``, ``sidebarsubtitle``, ``thead``,
   ``theadfamily``, ``emphasis``, ``literalemphasis``, ``strong``,
-  ``literalstrong``, ``abbreviation``, ``literalintitle``.
+  ``literalstrong``, ``abbreviation``, ``literalintitle``, ``codecontinued``,
+  ``codecontinues``.
 
   .. versionadded:: 1.5
      these macros were formerly hard-coded as non customizable ``\texttt``,
@@ -369,6 +379,8 @@ Macros
      multiple paragraphs in header cells of tables.
   .. deprecated:: 1.6
      macro ``\sphinxstylethead`` is deprecated at 1.6 and will be removed at 1.7.
+  .. versionadded:: 1.6.3
+     ``\sphinxstylecodecontinued`` and ``\sphinxstylecodecontinues``.
 - by default the Sphinx style file ``sphinx.sty`` executes the command
   ``\fvset{fontsize=\small}`` as part of its configuration of
   ``fancyvrb.sty``. This may be overriden for example via

sphinx/templates/latex/latex.tex_t

@@ -29,6 +29,7 @@
 <%= hyperref %>
 <%= contentsname %>
 <%= numfig_format %>
+<%= literalblockpto %>
 <%= pageautorefname %>
 <%= tocdepth %>
 <%= secnumdepth %>

sphinx/texinputs/sphinx.sty

@@ -257,6 +257,7 @@
 % verbatim
 \DeclareBoolOption[true]{verbatimwithframe}
 \DeclareBoolOption[true]{verbatimwrapslines}
+\DeclareBoolOption[false]{verbatimhintsturnover}
 \DeclareBoolOption[true]{inlineliteralwraps}
 % parsed literal
 \DeclareBoolOption[true]{parsedliteralwraps}
@@ -683,7 +684,7 @@
 % \sphinxVerbatimTitle is reset to empty after each use of Verbatim.
 \newcommand*\sphinxVerbatimTitle {}
 % This box to typeset the caption before framed.sty multiple passes for framing.
-\newbox\spx@VerbatimTitleBox
+\newbox\spx@Verbatim@TitleBox
 % Holder macro for labels of literal blocks. Set-up by LaTeX writer.
 \newcommand*\sphinxLiteralBlockLabel {}
 \newcommand*\sphinxSetupCaptionForVerbatim [1]
@@ -707,56 +708,79 @@
 \newif\ifspx@inframed % flag set if we are already in a framed environment
 % if forced use of minipage encapsulation is needed (e.g. table cells)
 \newif\ifsphinxverbatimwithminipage   \sphinxverbatimwithminipagefalse
-\newcommand\spx@colorbox [2]{%
+\long\def\spx@colorbox #1#2#3{%
-% #1 will be \fcolorbox or, for first part of frame: \spx@fcolorbox
 % let the framing obey the current indentation (adapted from framed.sty's code).
   \hskip\@totalleftmargin
   \hskip-\fboxsep\hskip-\fboxrule
-  #1{VerbatimBorderColor}{VerbatimColor}{#2}%
+  \spx@fcolorbox{VerbatimBorderColor}{VerbatimColor}{#1}{#2}{#3}%
   \hskip-\fboxsep\hskip-\fboxrule
   \hskip-\linewidth \hskip-\@totalleftmargin \hskip\columnwidth
 }
 % use of \color@b@x here is compatible with both xcolor.sty and color.sty
-\def\spx@fcolorbox #1#2%
+\long\def\spx@fcolorbox #1#2#3#4%
-  {\color@b@x {\fboxsep\z@\color{#1}\spx@VerbatimFBox}{\color{#2}}}%
+  {\color@b@x {\color{#1}\spx@VerbatimFBox{#3}{#4}}{\color{#2}}}%
-
+% Frame drawing macro
-% Inspired and adapted from framed.sty's \CustomFBox with extra handling
+% #1 = used by default for title above frame, may contain "continued" hint
-% of a non separable by pagebreak caption.
+% #2 = for material underneath frame, used for "continues on next page" hint
-% The sole purpose of this macro is to add the framing and the title. The #1
+% #3 = actual contents with background color
-% already has the typeset contents with background color, and took into
+\long\def\spx@VerbatimFBox#1#2#3{%
-% account the \sphinxverbatimsep. The \fboxsep parameter is here zero
-% (see \spx@fcolorbox definition) in order for the frame borders to exactly
-% fit the colored contents.
-\long\def\spx@VerbatimFBox#1{%
   \leavevmode
   \begingroup
-  \setbox\@tempboxa\hbox{\kern\fboxsep{#1}\kern\fboxsep}%
+  \setbox\@tempboxa\hbox{{#3}}% inner braces to avoid color leaks
   \hbox
-   {\lower\dimexpr\fboxrule+\fboxsep+\dp\@tempboxa
+   {\lower\dimexpr\fboxrule+\dp\@tempboxa\hbox{%
-    \hbox{%
+      \vbox{#1% above frame
-      \vbox{\ifvoid\spx@VerbatimTitleBox\else
-            % add the caption in a centered way above possibly indented frame
-            % hide its width from framed.sty's measuring step
-            % note that the caption brings \abovecaptionskip top vertical space
-            \moveright\dimexpr\fboxrule+.5\wd\@tempboxa
-                  \hb@xt@\z@{\hss\unhcopy\spx@VerbatimTitleBox\hss}\fi
             % draw frame border _latest_ to avoid pdf viewer issue
             \kern\fboxrule
             \hbox{\kern\fboxrule
-                  \vbox{\vskip\fboxsep\copy\@tempboxa\vskip\fboxsep}%
+                  \copy\@tempboxa
                   \kern-\wd\@tempboxa\kern-\fboxrule
                   \vrule\@width\fboxrule
                   \kern\wd\@tempboxa
                   \vrule\@width\fboxrule}%
-            \kern-\dimexpr\fboxsep+\ht\@tempboxa+\dp\@tempboxa
+            \kern-\dimexpr\ht\@tempboxa+\dp\@tempboxa+\fboxrule\relax
-                                  +\fboxsep+\fboxrule\relax
             \hrule\@height\fboxrule
-            \kern\dimexpr\fboxsep+\ht\@tempboxa+\dp\@tempboxa+\fboxsep\relax
+            \kern\dimexpr\ht\@tempboxa+\dp\@tempboxa\relax
-            \hrule\@height\fboxrule}%
+            \hrule\@height\fboxrule
-   }}%
+            #2% below frame
+          }%
+    }%
+   }%
   \endgroup
 }
 
+% Customize framed.sty \MakeFramed to glue caption to literal block
+% and add optional hint "continued on next page"
+\def\spx@Verbatim@FrameCommand
+   {\spx@colorbox\spx@Verbatim@Title{}}%
+% Macros for a frame with page breaks:
+\def\spx@Verbatim@FirstFrameCommand
+   {\spx@colorbox\spx@Verbatim@Title\spx@Verbatim@Continues}%
+\def\spx@Verbatim@MidFrameCommand
+   {\spx@colorbox\spx@Verbatim@Continued\spx@Verbatim@Continues}%
+\def\spx@Verbatim@LastFrameCommand
+   {\spx@colorbox\spx@Verbatim@Continued{}}%
+
+\def\spx@Verbatim@Title{% hide width from framed.sty measuring
+  \moveright\dimexpr\fboxrule+.5\wd\@tempboxa
+  \hb@xt@\z@{\hss\unhcopy\spx@Verbatim@TitleBox\hss}%
+}%
+\def\spx@Verbatim@Continued{%
+  \moveright\dimexpr\fboxrule+\wd\@tempboxa-\fboxsep
+  \hb@xt@\z@{\hss
+             {\normalcolor\sphinxstylecodecontinued\literalblockcontinuedname}}%
+}%
+\def\spx@Verbatim@Continues{%
+  \moveright\dimexpr\fboxrule+\wd\@tempboxa-\fboxsep
+  \hb@xt@\z@{\hss
+             {\normalcolor\sphinxstylecodecontinues\literalblockcontinuesname}}%
+}%
+\newcommand*\sphinxstylecodecontinued[1]{\footnotesize(#1)}%
+\newcommand*\sphinxstylecodecontinues[1]{\footnotesize(#1)}%
+% Defaults are redefined in document preamble according to language
+\newcommand*\literalblockcontinuedname{continued from previous page}%
+\newcommand*\literalblockcontinuesname{continues on next page}%
+
 % For linebreaks inside Verbatim environment from package fancyvrb.
 \newbox\sphinxcontinuationbox
 \newbox\sphinxvisiblespacebox
@@ -833,10 +857,10 @@
           \needspace{\sphinxliteralblockwithoutcaptionneedspace}%
           \phantomsection\sphinxLiteralBlockLabel
       \fi
-      \setbox\spx@VerbatimTitleBox\box\voidb@x
+      \let\spx@Verbatim@Title\@empty
   \else
   % non-empty \sphinxVerbatimTitle has label inside it (in case there is one)
-     \setbox\spx@VerbatimTitleBox
+     \setbox\spx@Verbatim@TitleBox
             \hbox{\begin{minipage}{\linewidth}%
                     \sphinxVerbatimTitle
                   \end{minipage}}%
@@ -844,13 +868,14 @@
   \fboxsep\sphinxverbatimsep \fboxrule\sphinxverbatimborder
   % setting borderwidth to zero is simplest for no-frame effect with same pagebreaks
   \ifspx@opt@verbatimwithframe\else\fboxrule\z@\fi
-  % Customize framed.sty \MakeFramed to glue caption to literal block
+  \let\FrameCommand     \spx@Verbatim@FrameCommand
-  % via \spx@fcolorbox, will use \spx@VerbatimFBox which inserts title
+  \let\FirstFrameCommand\spx@Verbatim@FirstFrameCommand
-  \def\FrameCommand   {\spx@colorbox\spx@fcolorbox }%
+  \let\MidFrameCommand  \spx@Verbatim@MidFrameCommand
-  \let\FirstFrameCommand\FrameCommand
+  \let\LastFrameCommand \spx@Verbatim@LastFrameCommand
-  % for mid pages and last page portion of (long) split frame:
+  \ifspx@opt@verbatimhintsturnover\else
-  \def\MidFrameCommand{\spx@colorbox\fcolorbox }%
+      \let\spx@Verbatim@Continued\@empty
-  \let\LastFrameCommand\MidFrameCommand
+      \let\spx@Verbatim@Continues\@empty
+  \fi
   \ifspx@opt@verbatimwrapslines
   % fancyvrb's Verbatim puts each input line in (unbreakable) horizontal boxes.
   % This customization wraps each line from the input in a \vtop, thus

sphinx/writers/latex.py

@@ -98,6 +98,7 @@ DEFAULT_SETTINGS = {
     'tocdepth':        '',
     'secnumdepth':     '',
     'pageautorefname': '',
+    'literalblockpto': '',
 }  # type: Dict[unicode, unicode]
 
 ADDITIONAL_SETTINGS = {
@@ -650,6 +651,14 @@ class LaTeXTranslator(nodes.NodeVisitor):
         if self.elements['extraclassoptions']:
             self.elements['classoptions'] += ',' + \
                                              self.elements['extraclassoptions']
+        self.elements['literalblockpto'] = (
+            self.babel_renewcommand(
+                '\\literalblockcontinuedname', self.encode(_('continued from previous page'))
+            ) +
+            self.babel_renewcommand(
+                '\\literalblockcontinuesname', self.encode(_('continues on next page'))
+            )
+        )
         self.elements['pageautorefname'] = \
             self.babel_defmacro('\\pageautorefname', self.encode(_('page')))
         self.elements['numfig_format'] = self.generate_numfig_format(builder)