[Docutils-checkins] SF.net SVN: docutils:[9401] trunk/docutils

SourceForge Headquarters 1320 Columbia Street Suite 310 San Diego, CA 92101 +1 (858) 422-6466

Revision: 9401
          http://sourceforge.net/p/docutils/code/9401
Author:   milde
Date:     2023-06-22 16:37:27 +0000 (Thu, 22 Jun 2023)
Log Message:
-----------
LaTeX writer: fix placement of hyperlink target (label) for tables.

Fixes [bugs:#440].

Modified Paths:
--------------
    trunk/docutils/HISTORY.txt
    trunk/docutils/RELEASE-NOTES.txt
    trunk/docutils/docs/user/config.txt
    trunk/docutils/docutils/writers/latex2e/__init__.py
    trunk/docutils/test/functional/expected/latex_cornercases.tex
    trunk/docutils/test/functional/expected/latex_memoir.tex
    trunk/docutils/test/functional/expected/standalone_rst_latex.tex
    trunk/docutils/test/functional/expected/standalone_rst_xetex.tex
    trunk/docutils/test/functional/input/data/hyperlinking.txt
    trunk/docutils/test/functional/input/data/tables_latex.txt

Modified: trunk/docutils/HISTORY.txt
===================================================================

--- trunk/docutils/HISTORY.txt	2023-06-22 16:19:59 UTC (rev 9400)
+++ trunk/docutils/HISTORY.txt	2023-06-22 16:37:27 UTC (rev 9401)
@@ -22,7 +22,11 @@
   Update to version `1.4 <https://pypi.org/project/roman/4.1/>`__.
   Fixes feature-requests:#95 (license is now ZPL 2.1).
 
+* docutils/writers/latex2e/__init__.py
 
+  - Fix placement of hyperlink target (label) for tables (bug #440).
+
+
 Release 0.20.1 (2023-05-17)
 ===========================
 

Modified: trunk/docutils/RELEASE-NOTES.txt
===================================================================
--- trunk/docutils/RELEASE-NOTES.txt	2023-06-22 16:19:59 UTC (rev 9400)
+++ trunk/docutils/RELEASE-NOTES.txt	2023-06-22 16:37:27 UTC (rev 9401)
@@ -145,6 +145,7 @@
 
   - Don't wrap references with custom reference-label_ in
     a ``\hyperref`` command in Docutils 0.22.
+    Specify, e.g., "ref" instead of "ref*" to keep generating hyperlinks.
 
     .. _reference-label: docs/user/config.html#reference-label
 

Modified: trunk/docutils/docs/user/config.txt
===================================================================
--- trunk/docutils/docs/user/config.txt	2023-06-22 16:19:59 UTC (rev 9400)
+++ trunk/docutils/docs/user/config.txt	2023-06-22 16:37:27 UTC (rev 9401)
@@ -1736,10 +1736,10 @@
 reference_label
 ~~~~~~~~~~~~~~~
 
-The LaTeX command name for `hyperlink references`_ to internal__ or
-implicit__ targets. Per default the LaTeX writer uses ``\hyperref``.
-Specify an alternative reference command, e.g., "ref" or "pageref" to get
-the section number or the page number as reference text.
+Per default the LaTeX writer uses ``\hyperref`` for `hyperlink
+references`_ to internal__ or implicit__ targets.
+Specify an alternative reference command, e.g., "ref" or "pageref"
+to get the section number or the page number as reference text.
 
 .. Caution::
    * Drops the original reference text.
@@ -1747,16 +1747,16 @@
    * Fails, e.g., with section numbering by Docutils (cf. sectnum_xform_)
      or tables without caption.
    * Provisional: to be replaced by a dedicated
-     `interpreted text role`_ for references.
+     `interpreted text role`_ for references (cf. TODO__).
 
 Default: "" (use "hyperref").  Option: ``--reference-label``.
 
-.. _hyperlink references: ../ref/rst/restructuredtext.html#hyperlink-references
 __ ../ref/rst/restructuredtext.html#internal-hyperlink-targets
 __ ../ref/rst/restructuredtext.html#implicit-hyperlink-targets
+__ ../dev/todo.html#object-numbering-and-object-references
+.. _hyperlink references: ../ref/rst/restructuredtext.html#hyperlink-references
 .. _interpreted text role: ../ref/rst/restructuredtext.html#interpreted-text
 
-
 section_enumerator_separator
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

Modified: trunk/docutils/docutils/writers/latex2e/__init__.py
===================================================================
--- trunk/docutils/docutils/writers/latex2e/__init__.py	2023-06-22 16:19:59 UTC (rev 9400)
+++ trunk/docutils/docutils/writers/latex2e/__init__.py	2023-06-22 16:37:27 UTC (rev 9401)
@@ -904,7 +904,6 @@
             return '|'
         return ''
 
-    # horizontal lines are drawn below a row,
     def get_opening(self, width=r'\linewidth'):
         align_map = {'left': '[l]',
                      'center': '[c]',
@@ -1009,6 +1008,11 @@
             return 'l'
 
     def get_caption(self):
+        """Deprecated. Will be removed in Docutils 0.22."""
+        warnings.warn('`writers.latex2e.Table.get_caption()` is obsolete'
+                      ' and will be removed in Docutils 0.22.',
+                      DeprecationWarning, stacklevel=2)
+
         if not self.caption:
             return ''
         caption = ''.join(self.caption)
@@ -3007,6 +3011,13 @@
             width = self.to_latex_length(node['width'])
         except KeyError:
             width = r'\linewidth'
+        # Insert hyperlabel and anchor before the table
+        # if it has no caption/title.
+        # See visit_thead() for tables with caption.
+        if not self.active_table.caption:
+            self.out.extend(self.ids_to_labels(
+                node, set_anchor=len(self.table_stack) != 1,
+                newline=True))
         # TODO: Don't use a longtable or add \noindent before
         #       the next paragraph, when in a "compound paragraph".
         #       Start a new line or a new paragraph?
@@ -3018,9 +3029,6 @@
         self.active_table.close()
         if len(self.table_stack) > 0:
             self.active_table = self.table_stack.pop()
-        # Insert hyperlabel after (long)table, as
-        # other places (beginning, caption) result in LaTeX errors.
-        self.out += self.ids_to_labels(node, set_anchor=False, newline=True)
         self.duclass_close(node)
 
     def visit_target(self, node):
@@ -3079,7 +3087,14 @@
         if 1 == self.thead_depth():
             self.out.append('{%s}\n' % self.active_table.get_colspecs(node))
             self.active_table.set('preamble written', 1)
-        self.out.append(self.active_table.get_caption())
+        if self.active_table.caption:
+            if self._thead_depth == 1:
+                pre = [r'\caption{']
+                post = self.ids_to_labels(node.parent.parent, False) + [r'}\\']
+            else:
+                pre = [r'\caption[]{']
+                post = [r' (... continued)}\\']
+            self.out.extend(pre + self.active_table.caption + post + ['\n'])
         self.out.extend(self.active_table.visit_thead())
 
     def depart_thead(self, node):

Modified: trunk/docutils/test/functional/expected/latex_cornercases.tex
===================================================================
--- trunk/docutils/test/functional/expected/latex_cornercases.tex	2023-06-22 16:19:59 UTC (rev 9400)
+++ trunk/docutils/test/functional/expected/latex_cornercases.tex	2023-06-22 16:37:27 UTC (rev 9401)
@@ -617,6 +617,7 @@
  \\
 \hline
 
+\label{nested-table}
 \noindent\makebox[\linewidth][r]{%
 \setlength{\DUtablewidth}{\dimexpr\linewidth-3\arrayrulewidth\relax}%
 \begin{tabular}{|p{\DUcolumnwidth{0.150}}|p{\DUcolumnwidth{0.150}}|}
@@ -869,13 +870,13 @@
 
 In LaTeX, we must set an explicit anchor (\texttt{\textbackslash{}phantomsection}) for a
 %
-\phantomsection\label{hypertarget-in-plain-text}hypertarget in plain text or in a figure but not in a longtable or
-caption:
+\phantomsection\label{hypertarget-in-plain-text}hypertarget in plain text or in a figure but not in a table title
+or figure caption:
 
 \setlength{\DUtablewidth}{\dimexpr\linewidth-4\arrayrulewidth\relax}%
 \begin{longtable}{|p{\DUcolumnwidth{0.150}}|p{\DUcolumnwidth{0.150}}|p{\DUcolumnwidth{0.150}}|}
 \caption{Table with %
-\label{hypertarget-in-table-title}hypertarget in table title.}\\
+\label{hypertarget-in-table-title}hypertarget in table title.\label{table-label}}\\
 \hline
 
 False
@@ -886,7 +887,6 @@
  \\
 \hline
 \end{longtable}
-\label{table-label}
 
 \begin{figure}
 \phantomsection\label{figure-label}
@@ -904,6 +904,7 @@
 
 See \hyperref[hypertarget-in-plain-text]{hypertarget in plain text},
 \hyperref[table-label]{table label}, \hyperref[hypertarget-in-table-title]{hypertarget in table title},
+\hyperref[nested-table]{nested table},
 \hyperref[figure-label]{figure label}, \hyperref[hypertarget-in-figure-caption]{hypertarget in figure caption},
 \hyperref[hypertarget-in-figure-legend]{hypertarget in figure legend}, and
 \hyperref[image-label]{image label}.

Modified: trunk/docutils/test/functional/expected/latex_memoir.tex
===================================================================
--- trunk/docutils/test/functional/expected/latex_memoir.tex	2023-06-22 16:19:59 UTC (rev 9400)
+++ trunk/docutils/test/functional/expected/latex_memoir.tex	2023-06-22 16:37:27 UTC (rev 9401)
@@ -1081,6 +1081,7 @@
 column widths are determined by the backend (if supported by the
 writer/backend).
 
+\phantomsection\label{target2}\label{target1}
 \begin{longtable*}{|l|l|l|}
 \hline
 \textbf{A} & \textbf{B} & \textbf{A or B} \\
@@ -1101,7 +1102,6 @@
 True & True & True \\
 \hline
 \end{longtable*}
-\label{target2}\label{target1}
 
 
 \subsection{2.14.4   Admonitions%

Modified: trunk/docutils/test/functional/expected/standalone_rst_latex.tex
===================================================================
--- trunk/docutils/test/functional/expected/standalone_rst_latex.tex	2023-06-22 16:19:59 UTC (rev 9400)
+++ trunk/docutils/test/functional/expected/standalone_rst_latex.tex	2023-06-22 16:37:27 UTC (rev 9401)
@@ -1082,6 +1082,7 @@
 column widths are determined by the backend (if supported by the
 writer/backend).
 
+\phantomsection\label{target2}\label{target1}
 \begin{longtable*}{|l|l|l|}
 \hline
 \textbf{A} & \textbf{B} & \textbf{A or B} \\
@@ -1102,7 +1103,6 @@
 True & True & True \\
 \hline
 \end{longtable*}
-\label{target2}\label{target1}
 
 
 \subsubsection{2.14.4   Admonitions%

Modified: trunk/docutils/test/functional/expected/standalone_rst_xetex.tex
===================================================================
--- trunk/docutils/test/functional/expected/standalone_rst_xetex.tex	2023-06-22 16:19:59 UTC (rev 9400)
+++ trunk/docutils/test/functional/expected/standalone_rst_xetex.tex	2023-06-22 16:37:27 UTC (rev 9401)
@@ -1117,6 +1117,7 @@
 column widths are determined by the backend (if supported by the
 writer/backend).
 
+\phantomsection\label{target2}\label{target1}
 \begin{longtable*}{|l|l|l|}
 \hline
 \textbf{A} & \textbf{B} & \textbf{A or B} \\
@@ -1137,7 +1138,6 @@
 True & True & True \\
 \hline
 \end{longtable*}
-\label{target2}\label{target1}
 
 
 \subsubsection{2.14.4   Admonitions%

Modified: trunk/docutils/test/functional/input/data/hyperlinking.txt
===================================================================
--- trunk/docutils/test/functional/input/data/hyperlinking.txt	2023-06-22 16:19:59 UTC (rev 9400)
+++ trunk/docutils/test/functional/input/data/hyperlinking.txt	2023-06-22 16:37:27 UTC (rev 9401)
@@ -2,8 +2,8 @@
 =======================
 
 In LaTeX, we must set an explicit anchor (``\phantomsection``) for a
-_`hypertarget in plain text` or in a figure but not in a longtable or
-caption:
+_`hypertarget in plain text` or in a figure but not in a table title
+or figure caption:
 
 .. _`table label`:
 
@@ -27,6 +27,7 @@
 
 See `hypertarget in plain text`_,
 `table label`_, `hypertarget in table title`_,
+`nested table`_,
 `figure label`_, `hypertarget in figure caption`_,
 `hypertarget in figure legend`_, and
 `image label`_.

Modified: trunk/docutils/test/functional/input/data/tables_latex.txt
===================================================================
--- trunk/docutils/test/functional/input/data/tables_latex.txt	2023-06-22 16:19:59 UTC (rev 9400)
+++ trunk/docutils/test/functional/input/data/tables_latex.txt	2023-06-22 16:37:27 UTC (rev 9401)
@@ -114,6 +114,7 @@
 +-----------------------------------------+-----------------+
 | .. table::                              | cell 1, 2       |
 |     :align: right                       |                 |
+|     :name: nested table                 |                 |
 |                                         |                 |
 |     +-----+-----+                       |                 |
 |     |  1  |  2  |                       |                 |

This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.



