LaTeX: support CSS3 length units

Author: jfbu

sphinx/templates/latex/latex.tex.jinja

@@ -16,6 +16,7 @@
 \ifdefined\pdfimageresolution
     \pdfimageresolution= \numexpr \dimexpr1in\relax/\sphinxpxdimen\relax
 \fi
+\newdimen\sphinxremdimen\sphinxremdimen = <%= pointsize%>
 %% let collapsible pdf bookmarks panel have high depth per default
 \PassOptionsToPackage{bookmarksdepth=5}{hyperref}
 <% if use_xindy -%>

sphinx/texinputs/sphinx.sty

@@ -9,7 +9,7 @@
 % by the Sphinx LaTeX writer.
 
 \NeedsTeXFormat{LaTeX2e}[1995/12/01]
-\ProvidesPackage{sphinx}[2025/04/24 v8.3.0 Sphinx LaTeX package (sphinx-doc)]
+\ProvidesPackage{sphinx}[2025/06/11 v8.3.0 Sphinx LaTeX package (sphinx-doc)]
 
 % provides \ltx@ifundefined
 % (many packages load ltxcmds: graphicx does for pdftex and lualatex but
@@ -1218,5 +1218,25 @@
 % FIXME: this line should be dropped, as "9" is default anyhow.
 \ifdefined\pdfcompresslevel\pdfcompresslevel = 9 \fi
 
-
+%%% SUPPORT FOR CSS3 EXTRA LENGTH UNITS
+% cf rstdim_to_latexdim in latex.py
+%
+\def\sphinxchdimen{\dimexpr\fontcharwd\font`0\relax}
+% TODO: decide if we want rather \textwidth/\textheight.
+\newdimen\sphinxvwdimen
+  \sphinxvwdimen=\dimexpr0.01\paperwidth\relax
+\newdimen\sphinxvhdimen
+  \sphinxvhdimen=\dimexpr0.01\paperheight\relax
+\newdimen\sphinxvmindimen
+  \sphinxvmindimen=\dimexpr
+     \ifdim\paperwidth<\paperheight\sphinxvwdimen\else\sphinxvhdimen\fi
+                   \relax
+\newdimen\sphinxvmaxdimen
+  \sphinxvmaxdimen=\dimexpr
+     \ifdim\paperwidth<\paperheight\sphinxvhdimen\else\sphinxvwdimen\fi
+                   \relax
+\newdimen\sphinxQdimen
+  \sphinxQdimen=0.25mm
+% MEMO: \sphinxremdimen is defined in the template as it needs
+% the config variable pointsize.
 \endinput

sphinx/writers/latex.py

@@ -305,6 +305,11 @@ def escape_abbr(text: str) -> str:
 
 def rstdim_to_latexdim(width_str: str, scale: int = 100) -> str:
     """Convert `width_str` with rst length to LaTeX length."""
+    # MEMO: the percent unit is interpreted here as a percentage
+    # of \linewidth.  Let's keep in mind though that \linewidth
+    # is dynamic in LaTeX (e.g. smaller in lists), and may even
+    # be zero in some contexts (some table cells).  This is a legacy
+    # situation perhaps best not changed (2025/06/11).
     match = re.match(r'^(\d*\.?\d*)\s*(\S*)$', width_str)
     if not match:
         raise ValueError
@@ -318,6 +323,8 @@ def rstdim_to_latexdim(width_str: str, scale: int = 100) -> str:
             res = '%sbp' % amount  # convert to 'bp'
         elif unit == '%':
             res = r'%.3f\linewidth' % (float(amount) / 100.0)
+        elif unit in {'ch', 'rem', 'vw', 'vh', 'vmin', 'vmax', 'Q'}:
+            res = rf'{amount}\sphinx{unit}dimen'
     else:
         amount_float = float(amount) * scale / 100.0
         if unit in {'', 'px'}:
@@ -326,8 +333,16 @@ def rstdim_to_latexdim(width_str: str, scale: int = 100) -> str:
             res = '%.5fbp' % amount_float
         elif unit == '%':
             res = r'%.5f\linewidth' % (amount_float / 100.0)
+        elif unit in {'ch', 'rem', 'vw', 'vh', 'vmin', 'vmax', 'Q'}:
+            res = rf'{amount_float / 100.0:.5f}\sphinx{unit}dimen'
         else:
             res = f'{amount_float:.5f}{unit}'
+    # MEMO: non-recognized units will in all probability end up causing
+    # a low-level TeX error.  The units not among those above which will
+    # be accepted by TeX are sp (all TeX dimensions are integer multiple
+    # of 1sp), em and ex (font dependent), bp, cm, mm, in, and pc.
+    # Non-CSS units are cc, nc, dd, and nd. Also the math only mu, which
+    # is not usable for example for LaTeX length assignments.
     return res