2019-03-30 13:46:53

by Mauro Carvalho Chehab

Subject: [PATCH 1/2] docs: Makefile: use latexmk if available

In the past, Sphinx was generating a LaTex Makefile that would
run xelatex 3 times. Running it multiple times is needed in order
to make the indexes right.

However, newer versions of it runs it just once, as it expects
the machine to use the "latexmk" build, with automatically
detects the need for rebuilds.

So, add a logic at the Makefile in order to detect if latexmk
is installed. If so, it will call it.

As an additional bonus, the output of latexmk is a little bit
better, making easier to identify build problems.

Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
Documentation/Makefile | 9 +++++++--
1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 9786957c6a35..e889e7cb8511 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -28,8 +28,13 @@ ifeq ($(HAVE_SPHINX),0)

else # HAVE_SPHINX

-# User-friendly check for pdflatex
+# User-friendly check for pdflatex and latexmk
HAVE_PDFLATEX := $(shell if which $(PDFLATEX) >/dev/null 2>&1; then echo 1; else echo 0; fi)
+HAVE_LATEXMK := $(shell if which latexmk >/dev/null 2>&1; then echo 1; else echo 0; fi)
+
+ifeq ($(HAVE_LATEXMK),1)
+ PDFLATEX := latexmk -$(PDFLATEX)
+endif #HAVE_LATEXMK

# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
@@ -82,7 +87,7 @@ pdfdocs:
else # HAVE_PDFLATEX

pdfdocs: latexdocs
- $(foreach var,$(SPHINXDIRS), $(MAKE) PDFLATEX=$(PDFLATEX) LATEXOPTS="$(LATEXOPTS)" -C $(BUILDDIR)/$(var)/latex || exit;)
+ $(foreach var,$(SPHINXDIRS), $(MAKE) PDFLATEX="$(PDFLATEX)" LATEXOPTS="$(LATEXOPTS)" -C $(BUILDDIR)/$(var)/latex || exit;)

endif # HAVE_PDFLATEX

--
2.20.1

2019-03-30 13:46:54

by Mauro Carvalho Chehab

Subject: [PATCH 2/2] docs: scripts/sphinx-pre-install: suggest latexmk for building pdf

The usage of latexmk improves the PDF output, as it re-run
xelatex when it detects the need, in order to properly generate
indexes and cross-references.

As this is not a mandatory requirement, only suggest its
addition.

Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
scripts/sphinx-pre-install | 1 +
1 file changed, 1 insertion(+)

diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install
index 067459760a7b..f6a5c0bae31e 100755
--- a/scripts/sphinx-pre-install
+++ b/scripts/sphinx-pre-install
@@ -532,6 +532,7 @@ sub check_needs()
check_program("dot", 1);
check_program("convert", 1);
check_program("rsvg-convert", 1) if ($pdf);
+ check_program("latexmk", 1) if ($pdf);

check_distros();

--
2.20.1

2019-04-01 20:44:18

by Jonathan Corbet

Subject: Re: [PATCH 1/2] docs: Makefile: use latexmk if available

On Sat, 30 Mar 2019 10:45:58 -0300
Mauro Carvalho Chehab <[email protected]> wrote:

> In the past, Sphinx was generating a LaTex Makefile that would
> run xelatex 3 times. Running it multiple times is needed in order
> to make the indexes right.
>
> However, newer versions of it runs it just once, as it expects
> the machine to use the "latexmk" build, with automatically
> detects the need for rebuilds.
>
> So, add a logic at the Makefile in order to detect if latexmk
> is installed. If so, it will call it.
>
> As an additional bonus, the output of latexmk is a little bit
> better, making easier to identify build problems.

Seems to work. I've applied both, thanks.

jon