Merge pull request #2704 from jfbu/jfbu_verbatim20

latex: customizable literal blocks

CHANGES

@@ -11,6 +11,8 @@ Incompatible changes
   using new name sphinxVerbatim for its custom wrapper
 * LaTeX package newfloat (which was shipped with Sphinx since 1.3.4) is no
   longer a dependency of sphinx.sty (ref #2660)
+* latex, writer does not use OriginalVerbatim for literal blocks in tables but
+  sphinxVerbatimintable (ref #2704)
 
 
 Features added
@@ -33,9 +35,16 @@ Features added
   list at end of ``sphinx.sty`` (ref: #2686)
 * public names for latex environments and parameters used by note, warning,
   and other admonition types, allowing full customizability from the
-  ``'preamble'`` key (ref: feature request #2674, #2685)
+  ``'preamble'`` key or an input file (ref: feature request #2674, #2685)
 * latex better computes column widths of some tables (as a result, there will
   be slight changes as tables now correctly fill the line with; ref: #2708)
+* latex, sphinxVerbatim environment is more easily customizable (ref: #2704).
+  In addition to already existing VerbatimColor and VerbatimBorderColor:
+
+  - two lengths ``\sphinxverbatimsep`` and ``\sphinxverbatimborder``,
+  - booleans ``\ifsphinxverbatimwithframe`` and ``\ifsphinxverbatimwrapslines``.
+* latex, captions for literal blocks inside tables are handled, and long code
+  lines wrapped to fit table cell (ref: #2704)
 
 Bugs fixed
 ----------

sphinx/texinputs/sphinx.sty

@@ -23,6 +23,7 @@
     \fi
 }
 
+\RequirePackage{graphicx}
 \@ifclassloaded{memoir}{}{\RequirePackage{fancyhdr}}
 
 % for \text macro and \iffirstchoice@ conditional even if amsmath not loaded
@@ -33,7 +34,6 @@
 \RequirePackage{makeidx}
 % For framing code-blocks and warning type notices, and shadowing topics
 \RequirePackage{framed}
-\newif\ifspx@inframed % flag set if we are in a framed environment
 % The xcolor package draws better fcolorboxes around verbatim code
 \IfFileExists{xcolor.sty}{
     \RequirePackage{xcolor}
@@ -77,8 +77,6 @@
   \newcount\pdfoutput\pdfoutput=0
 \fi
 
-\RequirePackage{graphicx}
-
 % for PDF output, use colors and maximal compression
 \newif\ifsphinxpdfoutput % used in \maketitle
 \ifx\pdfoutput\undefined\else
@@ -187,6 +185,13 @@
 \let\OriginalVerbatim   \Verbatim
 \let\endOriginalVerbatim\endVerbatim
 
+\newif\ifspx@inframed % flag set if we are already in a framed environment
+\newdimen\sphinxverbatimsep   \sphinxverbatimsep   \fboxsep  % default 3pt
+\newdimen\sphinxverbatimborder\sphinxverbatimborder\fboxrule % default 0.4pt
+\newif\ifsphinxverbatimwithframe      \sphinxverbatimwithframetrue
+\newif\ifsphinxverbatimwrapslines     \sphinxverbatimwrapslinestrue
+% if forced use of minipage encapsulation is needed (e.g. table cells)
+\newif\ifsphinxverbatimwithminipage   \sphinxverbatimwithminipagefalse
 \newcommand\spx@colorbox [2]{%
 % #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).
@@ -200,9 +205,11 @@
 \def\spx@fcolorbox #1#2%
   {\color@b@x {\fboxsep\z@\color{#1}\spx@VerbatimFBox}{\color{#2}}}%
 
-% The title is specified from outside as macro \sphinxVerbatimTitle.
+% The title (caption) is specified from outside as macro \sphinxVerbatimTitle.
 % \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
 % Holder macro for labels of literal blocks. Set-up by LaTeX writer.
 \newcommand*\sphinxLiteralBlockLabel {}
 \newcommand*\sphinxSetupCaptionForVerbatim [1]
@@ -218,27 +225,23 @@
 }
 
 % Inspired and adapted from framed.sty's \CustomFBox with extra handling
-% of a non separable by pagebreak caption, and controlled counter stepping.
-\newif\ifspx@myfirstframedpass
+% of a non separable by pagebreak caption.
 \long\def\spx@VerbatimFBox#1{%
   \leavevmode
   \begingroup
   % framed.sty does some measuring but this macro adds possibly a caption
   % use amsmath conditional to inhibit the caption counter stepping after
   % first pass
-  \ifspx@myfirstframedpass\else\firstchoice@false\fi
   \setbox\@tempboxa\hbox{\kern\fboxsep{#1}\kern\fboxsep}%
    \hbox
    {\lower\dimexpr\fboxrule+\fboxsep+\dp\@tempboxa
     \hbox{%
-      \vbox{\ifx\sphinxVerbatimTitle\empty\else
+      \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\begin{minipage}{\wd\@tempboxa}%
-                                  \sphinxVerbatimTitle
-                                 \end{minipage}\hss}\fi
+                  \hb@xt@\z@{\hss\unhcopy\spx@VerbatimTitleBox\hss}\fi
             % draw frame border _latest_ to avoid pdf viewer issue
             \kern\fboxrule
             \hbox{\kern\fboxrule
@@ -254,7 +257,6 @@
             \hrule\@height\fboxrule}%
    }}%
   \endgroup
-  \global\spx@myfirstframedpassfalse
 }
 
 % For linebreaks inside Verbatim environment from package fancyvrb.
@@ -309,7 +311,11 @@
    \lccode`\~`\~
 }
 
-\newenvironment{sphinxVerbatim}[1][1]{%
+% needed to create wrapper environments of fancyvrb's Verbatim
+\newcommand*{\sphinxVerbatimEnvironment}{\gdef\FV@EnvironName{sphinxVerbatim}}
+% Sphinx <1.5 optional argument was in fact mandatory. It is now really
+% optional and handled by original Verbatim.
+\newenvironment{sphinxVerbatim}{%
   % quit horizontal mode if we are still in a paragraph
   \par
   % list starts new par, but we don't want it to be set apart vertically
@@ -325,16 +331,25 @@
           \needspace{\sphinxliteralblockwithoutcaptionneedspace}%
           \phantomsection\sphinxLiteralBlockLabel
       \fi
-  \fi
+      \setbox\spx@VerbatimTitleBox\box\voidb@x
+  \else
   % non-empty \sphinxVerbatimTitle has label inside it (in case there is one)
+     \setbox\spx@VerbatimTitleBox
+            \hbox{\begin{minipage}{\linewidth}%
+                    \sphinxVerbatimTitle
+                  \end{minipage}}%
+  \fi
+  \fboxsep\sphinxverbatimsep \fboxrule\sphinxverbatimborder
+  % setting borderwidth to zero is simplest for no-frame effect with same pagebreaks
+  \ifsphinxverbatimwithframe\else\fboxrule\z@\fi
   % Customize framed.sty \MakeFramed to glue caption to literal block
-  \global\spx@myfirstframedpasstrue
   % via \spx@fcolorbox, will use \spx@VerbatimFBox which inserts title
   \def\FrameCommand   {\spx@colorbox\spx@fcolorbox }%
   \let\FirstFrameCommand\FrameCommand
   % for mid pages and last page portion of (long) split frame:
   \def\MidFrameCommand{\spx@colorbox\fcolorbox }%
   \let\LastFrameCommand\MidFrameCommand
+  \ifsphinxverbatimwrapslines
   % fancyvrb's Verbatim puts each input line in (unbreakable) horizontal boxes.
   % This customization wraps each line from the input in a \vtop, thus
   % allowing it to wrap and display on two or more lines in the latex output.
@@ -358,12 +373,15 @@
        \discretionary{\copy\sphinxvisiblespacebox}{\sphinxafterbreak}
                      {\kern\fontdimen2\font}%
        }%
-  % go around fancyvrb's check of \@currenvir
-  \renewcommand*{\VerbatimEnvironment}{\gdef\FV@EnvironName{sphinxVerbatim}}%
-  % go around fancyvrb's check of current list depth
-  \def\@toodeep {\advance\@listdepth\@ne}%
   % Allow breaks at special characters using \PYG... macros.
   \sphinxbreaksatspecials
+  % Breaks at punctuation characters . , ; ? ! and / (needs catcode activation)
+  \def\FancyVerbCodes{\sphinxbreaksatpunct}%
+  \fi % end of conditional code for wrapping long code lines
+  % go around fancyvrb's check of \@currenvir
+  \let\VerbatimEnvironment\sphinxVerbatimEnvironment
+  % go around fancyvrb's check of current list depth
+  \def\@toodeep {\advance\@listdepth\@ne}%
   % The list environment is needed to control perfectly the vertical space.
   % Note: \OuterFrameSep used by framed.sty is later set to \topsep hence 0pt.
   % - if caption: vertical space above caption = (\abovecaptionskip + D) with
@@ -377,23 +395,41 @@
   \rightmargin\z@
   \parindent  \z@% becomes \itemindent. Default zero, but perhaps overwritten.
   \trivlist\item\relax
-  % use a minipage if we are already inside a framed environment
+     \ifsphinxverbatimwithminipage\spx@inframedtrue\fi
+     % use a minipage if we are already inside a framed environment
      \ifspx@inframed\noindent\begin{minipage}{\linewidth}\fi
      \MakeFramed {% adapted over from framed.sty's snugshade environment
-     \advance\hsize-\width\@totalleftmargin\z@\linewidth\hsize
-     \@setminipage  }%
+        \advance\hsize-\width\@totalleftmargin\z@\linewidth\hsize\@setminipage
+        }%
      \small
      % For grid placement from \strut's in \FancyVerbFormatLine
      \lineskip\z@skip
-     % Breaks at punctuation characters . , ; ? ! and / need catcode=\active
-     \OriginalVerbatim[#1,codes*=\sphinxbreaksatpunct]%
+     % will fetch its optional arguments if any
+     \OriginalVerbatim
 }
 {%
   \endOriginalVerbatim
-  \par\unskip\@minipagefalse\endMakeFramed
+  \par\unskip\@minipagefalse\endMakeFramed % from framed.sty snugshade
   \ifspx@inframed\end{minipage}\fi
   \endtrivlist
 }
+\newenvironment {sphinxVerbatimNoFrame}
+  {\sphinxverbatimwithframefalse
+   % needed for fancyvrb as literal code will end in \end{sphinxVerbatimNoFrame}
+   \def\sphinxVerbatimEnvironment{\gdef\FV@EnvironName{sphinxVerbatimNoFrame}}%
+   \begin{sphinxVerbatim}}
+  {\end{sphinxVerbatim}}
+\newenvironment {sphinxVerbatimintable}
+  {% don't use a frame if in a table cell
+   \sphinxverbatimwithframefalse
+   \sphinxverbatimwithminipagetrue
+   % counteract longtable/tabulary redefinition of caption
+   \let\caption\sphinxfigcaption
+   % reduce above caption space if in a table cell
+   \abovecaptionskip\smallskipamount
+   \def\sphinxVerbatimEnvironment{\gdef\FV@EnvironName{sphinxVerbatimintable}}%
+   \begin{sphinxVerbatim}}
+  {\end{sphinxVerbatim}}
 
 % define macro to frame contents and add shadow on right and bottom
 % use public names for customizable lengths

sphinx/writers/latex.py

@@ -1908,17 +1908,17 @@ class LaTeXTranslator(nodes.NodeVisitor):
             hlcode = hlcode.replace(u'€', u'@texteuro[]')
             # must use original Verbatim environment and "tabular" environment
             if self.table:
-                hlcode = hlcode.replace('\\begin{Verbatim}',
-                                        '\\begin{OriginalVerbatim}')
                 self.table.has_problematic = True
                 self.table.has_verbatim = True
+                hlcode = hlcode.replace('\\begin{Verbatim}',
+                                        '\\begin{sphinxVerbatimintable}')
             else:
                 hlcode = hlcode.replace('\\begin{Verbatim}',
                                         '\\begin{sphinxVerbatim}')
             # get consistent trailer
             hlcode = hlcode.rstrip()[:-14]  # strip \end{Verbatim}
-            self.body.append('\n' + hlcode + '\\end{%sVerbatim}\n' %
-                             ((not self.table) and 'sphinx' or 'Original'))
+            self.body.append('\n' + hlcode + '\\end{sphinxVerbatim%s}\n' %
+                             (self.table and 'intable' or ''))
             if ids:
                 self.body.append('\\let\\sphinxLiteralBlockLabel\empty\n')
             raise nodes.SkipNode