From 2f7c71c4bf584859777bdcdea6ce346c4bcfd5ab Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jean-Fran=C3=A7ois=20B?=
 <2589111+jfbu@users.noreply.github.com>
Date: Sun, 21 Jul 2024 12:33:10 +0200
Subject: [PATCH 1/2] Use Latexmk in a more efficient way for `'xelatex'` as
 `latex_engine`

---
 sphinx/texinputs/Makefile.jinja | 21 ++++++++++++++++-----
 1 file changed, 16 insertions(+), 5 deletions(-)

diff --git a/sphinx/texinputs/Makefile.jinja b/sphinx/texinputs/Makefile.jinja
index f7611bb3732..4417987fddc 100644
--- a/sphinx/texinputs/Makefile.jinja
+++ b/sphinx/texinputs/Makefile.jinja
@@ -4,6 +4,8 @@ ALLDOCS = $(basename $(wildcard *.tex))
 ALLPDF = $(addsuffix .pdf,$(ALLDOCS))
 {% if latex_engine == 'xelatex' -%}
 ALLDVI =
+# but we do not know a way to let Latexmk produce the .xdv files
+# as final targets, only as left-overs from a .pdf build
 ALLXDV = $(addsuffix .xdv,$(ALLDOCS))
 {% else -%}
 ALLDVI = $(addsuffix .dvi,$(ALLDOCS))
@@ -16,10 +18,6 @@ ARCHIVEPREFIX =
 # Additional LaTeX options (passed via variables in latexmkrc/latexmkjarc file)
 export LATEXOPTS ?=
 # Additional latexmk options
-{% if latex_engine == 'xelatex' -%}
-# with latexmk version 4.52b or higher set LATEXMKOPTS to -xelatex either here
-# or on command line for faster builds.
-{% endif -%}
 LATEXMKOPTS ?=
 {% if xindy_use -%}
 export XINDYOPTS = {{ xindy_lang_option }} -M sphinx.xdy
@@ -40,9 +38,22 @@ FMT = pdf
 # latexmkrc is read then overridden by latexmkjarc
 LATEX = latexmk -r latexmkjarc -dvi
 PDFLATEX = latexmk -r latexmkjarc -pdfdvi -dvi- -ps-
-{% else -%}
+{% endif -%}
+{% if latex_engine == 'pdflatex' -%}
 LATEX = latexmk -dvi
 PDFLATEX = latexmk -pdf -dvi- -ps-
+{% endif -%}
+{% if latex_engine == 'xelatex' -%}
+# No LATEX as it is used for .dvi targets which xelatex can't produce.
+# The -pdf is not needed with current (2024) Latexmk but may have been
+# in the distant past.  It doesn't hurt.
+PDFLATEX = latexmk -pdf -xelatex
+{% endif -%}
+{% if latex_engine == 'lualatex' -%}
+LATEX = latexmk -dvilua
+# The -pdf is not needed with current (2024) Latexmk but may have been
+# in the distant past.  It doesn't hurt.
+PDFLATEX = latexmk -pdf -lualatex
 {% endif %}
 
 {% if latex_engine != 'xelatex' -%}

From 1c7cba7a1778d35f111818717d3ede39760f0a5e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jean-Fran=C3=A7ois=20B?=
 <2589111+jfbu@users.noreply.github.com>
Date: Sun, 21 Jul 2024 12:53:18 +0200
Subject: [PATCH 2/2] Update CHANGES and docs for PR #12636 (Latexmk)

---
 CHANGES.rst                  | 3 +++
 doc/usage/builders/index.rst | 4 ----
 2 files changed, 3 insertions(+), 4 deletions(-)

diff --git a/CHANGES.rst b/CHANGES.rst
index e5279bcdb58..60376e14ca2 100644
--- a/CHANGES.rst
+++ b/CHANGES.rst
@@ -67,6 +67,9 @@ Deprecated
 Features added
 --------------
 
+* #12636: LaTeX: possibly faster builds with ``'xelatex'`` from modernized
+  invocation of :program:`Latexmk` (backward compatible).
+
 Bugs fixed
 ----------
 
diff --git a/doc/usage/builders/index.rst b/doc/usage/builders/index.rst
index e293399282e..4956fdee856 100644
--- a/doc/usage/builders/index.rst
+++ b/doc/usage/builders/index.rst
@@ -280,10 +280,6 @@ The most common builders are:
 
       reduces console output to a minimum.
 
-      Also, if ``latexmk`` is at version 4.52b or higher (January 2017)
-      ``LATEXMKOPTS="-xelatex"`` speeds up PDF builds via XeLateX in case
-      of numerous graphics inclusions.
-
       To pass options directly to the ``(pdf|xe|lua)latex`` binary, use
       variable ``LATEXOPTS``, for example: