Merge branch 'stable'

CHANGES

@@ -73,6 +73,8 @@ Features added
 * #3194: Refer the $MAKE environment variable to determine ``make`` command
 * Emit warning for nested numbered toctrees (refs: #3142)
 * #978: `intersphinx_mapping` also allows a list as a parameter
+* #3340: (LaTeX) long lines in :dudir:`parsed-literal` are wrapped like in
+  :rst:dir:`code-block`, inline math and footnotes are fully functional.
 
 Bugs fixed
 ----------
@@ -97,11 +99,17 @@ Bugs fixed
 * #3335: gettext does not extract field_name of a field in a field_list
 * #2952: C++, fix refs to operator() functions.
 * Fix Unicode super- and subscript digits in :rst:dir:`code-block` and
-  :dudir:`parsed-literal` LaTeX output (ref #3342)
-* LaTeX writer: leave ``"`` character inside :dudir:`parsed-literal` as is
-  (ref #3341)
+  parsed-literal LaTeX output (ref #3342)
+* LaTeX writer: leave ``"`` character inside parsed-literal as is (ref #3341)
 * #3234: intersphinx failed for encoded inventories
 * #3158: too much space after captions in PDF output
+* #3317: An URL in parsed-literal contents gets wrongly rendered in PDF if
+  with hyphen
+* LaTeX crash if the filename of an image inserted in parsed-literal
+  via a substitution contains an hyphen (ref #3340)
+* LaTeX rendering of inserted footnotes in parsed-literal is wrong (ref #3340)
+* Inline math in parsed-literal is not rendered well by LaTeX (ref #3340)
+* #3308: Parsed-literals don't wrap very long lines with pdf builder (ref #3340)
 
 
 Release 1.5.1 (released Dec 13, 2016)

MANIFEST.in

@@ -5,11 +5,9 @@ include CHANGES
 include CHANGES.old
 include CONTRIBUTING.rst
 include EXAMPLES
-include TODO
 
 include babel.cfg
 include Makefile
-include ez_setup.py
 include sphinx-autogen.py
 include sphinx-build.py
 include sphinx-quickstart.py

doc/latex.rst

@@ -132,25 +132,33 @@ Here are the currently available options together with their default values.
    rendering by Sphinx; if in future Sphinx offers various *themes* for LaTeX,
    the interface may change.
 
+.. attention::
+
+   LaTeX requires for keys with Boolean values to use **lowercase** ``true`` or
+   ``false``.
+
 ``verbatimwithframe``
     default ``true``. Boolean to specify if :rst:dir:`code-block`\ s and literal
     includes are framed. Setting it to ``false`` does not deactivate use of
     package "framed", because it is still in use for the optional background
     colour (see below).
 
-    .. attention::
-
-       LaTeX requires ``true`` or ``false`` to be specified in *lowercase*.
-
 ``verbatimwrapslines``
-    default ``true``. Tells whether long lines in :rst:dir:`code-block`\ s
-    should be wrapped.
+    default ``true``. Tells whether long lines in :rst:dir:`code-block`\ 's
+    contents should wrap.
 
     .. (comment) It is theoretically possible to customize this even
        more and decide at which characters a line-break can occur and whether
        before or after, but this is accessible currently only by re-defining some
        macros with complicated LaTeX syntax from :file:`sphinx.sty`.
 
+``parsedliteralwraps``
+    default ``true``. Tells whether long lines in :dudir:`parsed-literal`\ 's
+    contents should wrap.
+
+    .. versionadded:: 1.5.2
+       set this option value to ``false`` to recover former behaviour.
+
 ``inlineliteralwraps``
     default ``true``. Allows linebreaks inside inline literals: but extra
     potential break-points (additionally to those allowed by LaTeX at spaces
@@ -160,7 +168,7 @@ Here are the currently available options together with their default values.
     (or shrinked) in order to accomodate the linebreak.
 
     .. versionadded:: 1.5
-       set this option to ``false`` to recover former behaviour.
+       set this option value to ``false`` to recover former behaviour.
 
 ``verbatimvisiblespace``
     default ``\textcolor{red}{\textvisiblespace}``. When a long code line is
@@ -319,9 +327,10 @@ Here are the currently available options together with their default values.
     (non-breakable) space.
 
     .. versionadded:: 1.5
-       formerly, footnotes from explicit mark-up were
-       preceded by a space (hence a linebreak there was possible), but
-       automatically generated footnotes had no such space.
+       formerly, footnotes from explicit mark-up (but not automatically
+       generated ones) were preceded by a space in the output ``.tex`` file
+       hence a linebreak in PDF was possible. To avoid insertion of this space
+       one could use ``foo\ [#f1]`` mark-up, but this impacts all builders.
 
 ``HeaderFamily``
     default ``\sffamily\bfseries``. Sets the font used by headings.

sphinx/domains/cpp.py

@@ -4957,7 +4957,7 @@ class CPPDomain(Domain):
         # Also, if it's an 'any' ref that resolves to a function, we need to add
         # parens as well.
         addParen = 0
-        if not node['refexplicit'] and declaration.objectType == 'function':
+        if not node.get('refexplicit', False) and declaration.objectType == 'function':
             # this is just the normal haxing for 'any' roles
             if env.config.add_function_parentheses and typ == 'any':
                 addParen += 1

sphinx/texinputs/footnotehyper-sphinx.sty

@@ -1,6 +1,6 @@
 \NeedsTeXFormat{LaTeX2e}
 \ProvidesPackage{footnotehyper-sphinx}%
- [2016/10/27 v0.9f hyperref aware footnote.sty for sphinx (JFB)]
+ [2017/01/16 v1.5.2 hyperref aware footnote.sty for sphinx (JFB)]
 %%
 %% Package: footnotehyper-sphinx
 %% Version: based on footnotehyper.sty v0.9f (2016/10/03)
@@ -15,6 +15,7 @@
 %% 4. \sphinxfootnotemark, and use of \spx@opt@BeforeFootnote from sphinx.sty.
 %% Note: with \footnotemark[N]/\footnotetext[N] syntax, hyperref
 %% does not insert an hyperlink. This is _not_ improved here.
+%% 5. use of \sphinxunactivateextrasandspace for parsed literals
 %%
 \DeclareOption*{\PackageWarning{footnotehyper}{Option `\CurrentOption' is unknown}}%
 \ProcessOptions\relax
@@ -92,7 +93,8 @@
 %% \spx@opt@BeforeFootnote is defined in sphinx.sty
 \def\FNH@fixed@footnote {\spx@opt@BeforeFootnote\ifx\@currenvir\fn@footnote
     \expandafter\FNH@footnoteenv\else\expandafter\fn@latex@@footnote\fi }%
-\def\FNH@footnoteenv {\@ifnextchar[\FNH@xfootnoteenv%]
+\def\FNH@footnoteenv {\catcode13=5\sphinxunactivateextrasandspace
+    \@ifnextchar[\FNH@xfootnoteenv%]
     {\stepcounter\@mpfn
      \protected@xdef\@thefnmark{\thempfn}\@footnotemark
      \def\FNH@endfntext@next{\FNH@endfntext@link}\fn@startfntext}}%

sphinx/texinputs/sphinx.sty

@@ -6,7 +6,7 @@
 %
 
 \NeedsTeXFormat{LaTeX2e}[1995/12/01]
-\ProvidesPackage{sphinx}[2017/01/09 v1.6 LaTeX package (Sphinx markup)]
+\ProvidesPackage{sphinx}[2017/01/16 v1.6 LaTeX package (Sphinx markup)]
 
 % we delay handling of options to after having loaded packages, because
 % of the need to use \definecolor.
@@ -91,6 +91,8 @@
 \DeclareBoolOption[true]{verbatimwithframe}
 \DeclareBoolOption[true]{verbatimwrapslines}
 \DeclareBoolOption[true]{inlineliteralwraps}
+% parsed literal
+\DeclareBoolOption[true]{parsedliteralwraps}
 % \textvisiblespace for compatibility with fontspec+XeTeX/LuaTeX
 \DeclareStringOption[\textcolor{red}{\textvisiblespace}]{verbatimvisiblespace}
 \DeclareStringOption % must use braces to hide the brackets
@@ -397,6 +399,7 @@
 \def\sphinx@verbatim@nolig@list {\do \`}%
 % Some characters . , ; ? ! / are not pygmentized.
 % This macro makes them "active" and they will insert potential linebreaks
+% In math mode, the characters are de-activated.
 \newcommand*\sphinxbreaksbeforeactivelist {}% none
 \newcommand*\sphinxbreaksafteractivelist  {\do\.\do\,\do\;\do\?\do\!\do\/}
 \newcommand*\sphinxbreaksviaactive {%
@@ -411,6 +414,15 @@
    \lccode`\~`\~
 }
 
+% If the linebreak is at a space, the latter will be displayed as visible
+% space at end of first line, and a continuation symbol starts next line.
+% Stretch/shrink are however usually zero for typewriter font.
+\def\spx@verbatim@space {%
+     \nobreak\hskip\z@ plus\fontdimen3\font minus\fontdimen4\font
+     \discretionary{\copy\sphinxvisiblespacebox}{\sphinxafterbreak}
+                   {\kern\fontdimen2\font}%
+}%
+
 % 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
@@ -466,14 +478,7 @@
                 \doublehyphendemerits\z@\finalhyphendemerits\z@
                 \strut ##1\strut}%
           }%
-  % If the linebreak is at a space, the latter will be displayed as visible
-  % space at end of first line, and a continuation symbol starts next line.
-  % Stretch/shrink are however usually zero for typewriter font.
-  \def\FV@Space {%
-       \nobreak\hskip\z@ plus\fontdimen3\font minus\fontdimen4\font
-       \discretionary{\copy\sphinxvisiblespacebox}{\sphinxafterbreak}
-                     {\kern\fontdimen2\font}%
-       }%
+  \let\FV@Space\spx@verbatim@space
   % Allow breaks at special characters using \PYG... macros.
   \sphinxbreaksatspecials
   % Breaks at punctuation characters . , ; ? ! and / (needs catcode activation)
@@ -535,6 +540,68 @@
    \begin{sphinxVerbatim}}
   {\end{sphinxVerbatim}}
 
+% Parsed literal: allow long lines to wrap like they do in code-blocks
+
+% this should be kept in sync with definitions in sphinx.util.texescape
+\newcommand*\sphinxbreaksattexescapedchars{%
+  \def\do##1##2% put potential break point before character
+     {\def##1{\discretionary{}{\sphinxafterbreak\char`##2}{\char`##2}}}%
+  \do\{\{\do\textless\<\do\#\#\do\%\%\do\$\$% {, <, #, %, $
+  \def\do##1##2% put potential break point after character
+     {\def##1{\discretionary{\char`##2}{\sphinxafterbreak}{\char`##2}}}%
+  \do\_\_\do\}\}\do\textasciicircum\^\do\&\&% _, }, ^, &,
+  \do\textgreater\>\do\textasciitilde\~% >, ~
+}
+\newcommand*\sphinxbreaksviaactiveinparsedliteral{%
+  \sphinxbreaksviaactive % by default handles . , ; ? ! /
+  \do\-% we need also the hyphen character
+  \lccode`\~`\~ %
+  % update \dospecials as it is used by \url
+  % but deactivation will already have been done hence commented out
+  %  \expandafter\def\expandafter\dospecials\expandafter{\dospecials
+  %   \sphinxbreaksbeforeactivelist\sphinxbreaksafteractivelist\do\-}%
+}
+\newcommand*\sphinxbreaksatspaceinparsedliteral{%
+  \lccode`~32 \lowercase{\let~}\spx@verbatim@space\lccode`\~`\~
+}
+% now the hack for \url to work (hyperref is required dependency):
+% the aim it to deactivate - . , ; ? ! / in \url's argument
+\def\spx@hack@hyper@normalise {%
+  \expandafter\spx@hack@hyper@normalise@aux\hyper@normalise
+              \spx@hack@hyper@normalise@aux\hyper@n@rmalise\relax\spx@undefined
+}%
+\long\def\spx@hack@hyper@normalise@aux#1\hyper@n@rmalise#2#3\spx@undefined{%
+  \ifx\spx@hack@hyper@normalise@aux#2%
+      \def\hyper@normalise{#1\sphinxunactivateextrasandspace\hyper@n@rmalise}%
+  \else
+      \PackageWarning{sphinx}{Could not patch \string\url\space command.%
+      ^^J    Not using extra active characters in alltt environment}%
+      \sphinxunactivateextras
+  \fi
+}%
+\newcommand*{\sphinxunactivateextras}{\let\do\@makeother
+      \sphinxbreaksbeforeactivelist\sphinxbreaksafteractivelist\do\-}%
+\newcommand*{\sphinxunactivateextrasandspace}{\catcode32=10\relax
+      \sphinxunactivateextras}%
+% now for the modified alltt environment
+\newenvironment{sphinxalltt}
+{% at start of next line to work around Emacs/AUCTeX issue with this file
+\begin{alltt}%
+ \ifspx@opt@parsedliteralwraps
+   \sbox\sphinxcontinuationbox {\spx@opt@verbatimcontinued}%
+   \sbox\sphinxvisiblespacebox {\spx@opt@verbatimvisiblespace}%
+   \sphinxbreaksattexescapedchars
+   \sphinxbreaksviaactiveinparsedliteral
+   \sphinxbreaksatspaceinparsedliteral
+   \spx@hack@hyper@normalise
+% alltt takes care of the ' as derivative ("prime") in math mode
+   \everymath\expandafter{\the\everymath\sphinxunactivateextrasandspace
+             \catcode`\<=12\catcode`\>=12\catcode`\^=7\catcode`\_=8 }%
+   \everydisplay\expandafter{\the\everydisplay\sphinxunactivateextrasandspace
+             \catcode`\<=12\catcode`\>=12\catcode`\^=7\catcode`\_=8 }%
+ \fi }
+{\end{alltt}}
+
 % Topic boxes
 
 % Again based on use of "framed.sty", this allows breakable framed boxes.

sphinx/writers/latex.py

@@ -1126,15 +1126,21 @@ class LaTeXTranslator(nodes.NodeVisitor):
             self.body.append('%%\n\\begin{footnotetext}[%s]'
                              '\\sphinxAtStartFootnote\n' % node['number'])
         else:
-            self.body.append('%%\n\\begin{footnote}[%s]'
-                             '\\sphinxAtStartFootnote\n' % node['number'])
+            if self.in_parsed_literal:
+                self.body.append('\\begin{footnote}[%s]' % node['number'])
+            else:
+                self.body.append('%%\n\\begin{footnote}[%s]' % node['number'])
+            self.body.append('\\sphinxAtStartFootnote\n')
 
     def depart_collected_footnote(self, node):
         # type: (nodes.Node) -> None
         if 'footnotetext' in node:
             self.body.append('%\n\\end{footnotetext}')
         else:
-            self.body.append('%\n\\end{footnote}')
+            if self.in_parsed_literal:
+                self.body.append('\\end{footnote}')
+            else:
+                self.body.append('%\n\\end{footnote}')
         self.in_footnote -= 1
 
     def visit_label(self, node):
@@ -1571,6 +1577,9 @@ class LaTeXTranslator(nodes.NodeVisitor):
         attrs = node.attributes
         pre = []                        # in reverse order
         post = []
+        if self.in_parsed_literal:
+            pre = ['\\begingroup\\sphinxunactivateextrasandspace\\relax ']
+            post = ['\\endgroup ']
         include_graphics_options = []
         is_inline = self.is_inline(node)
         if 'width' in attrs:
@@ -2114,7 +2123,7 @@ class LaTeXTranslator(nodes.NodeVisitor):
         if node.rawsource != node.astext():
             # most probably a parsed-literal block -- don't highlight
             self.in_parsed_literal += 1
-            self.body.append('\\begin{alltt}\n')
+            self.body.append('\\begin{sphinxalltt}\n')
         else:
             ids = ''  # type: unicode
             for id in self.pop_hyperlink_ids('code-block'):
@@ -2174,7 +2183,7 @@ class LaTeXTranslator(nodes.NodeVisitor):
 
     def depart_literal_block(self, node):
         # type: (nodes.Node) -> None
-        self.body.append('\n\\end{alltt}\n')
+        self.body.append('\n\\end{sphinxalltt}\n')
         self.in_parsed_literal -= 1
     visit_doctest_block = visit_literal_block
     depart_doctest_block = depart_literal_block