LaTeX: let latexpdf implement '-q' and '-Q' sphinx-build options

[jfbu]

Closes #12717

EDIT: this whole description is obsolete as it was decided in a later stage to actually use latexmk -silent for -q.

obsolete Due to the fact that Latexmk sends to stderr messages of a purely informative nature (such as missing .toc file on first run), I could not handle the -q as I intended to (i.e. simply suppress or capture stdout). I find the -silent option of Latexmk is too drastic as it continues to print out to stdout but makes it more obscure what is happening, so I opted for running the sub-latex in "batchmode", knowing all info is anyhow available at end of LaTeX run in .log file (there are extreme situations, where the log file can remain empty and suppressing stdout loses information, but this is impossible in Sphinx except under special user additions to preamble).

And regarding -Q the stdout/stderr get redirected to some file containing the Latexmk+LaTeX console output which may be checked prior to log file in case of problems. Contrarily to using -silent with Latexmk (and even --silent with make), there is really no output whatsoever in case of successful build.

Examples (for a fresh project each)

$ sphinx-build -M latexpdf . _build/ -Q

i.e. no output whatsoever if no error,

and

$ sphinx-build -M latexpdf . _build/ -Q
Latex error: check _build/latex/__LATEXSTDOUT__

in case of an error. Regarding -q option it behaves like this:

EDIT: final version of this PR simply uses latexmk -silent, so there is less console output than was shown here.

$ sphinx-build -M latexpdf . _build/ -q
latexmk -pdf -dvi- -ps-  'foo.tex'
Rc files read:
  latexmkrc
Latexmk: This is Latexmk, John Collins, 7 Apr. 2024. Version 4.85.
No existing .aux file, so I'll make a simple one, and require run of *latex.
Latexmk: applying rule 'pdflatex'...
Rule 'pdflatex':  Reasons for rerun
Category 'other':
  Rerun of 'pdflatex' forced or previously required:
    Reason or flag: 'Initial setup'

------------
Run number 1 of rule 'pdflatex'
------------
------------
Running 'pdflatex -halt-on-error -interaction=batchmode  -recorder  "foo.tex"'
------------
This is pdfTeX, Version 3.141592653-2.6-1.40.26 (TeX Live 2024) (preloaded format=pdflatex)
 restricted \write18 enabled.
entering extended mode
Latexmk: Getting log file 'foo.log'
Latexmk: Examining 'foo.fls'
Latexmk: Examining 'foo.log'
Latexmk: Index file 'foo.idx' was written
Latexmk: Missing input file 'foo.toc' (or dependence on it) from following:
  No file foo.toc.
Latexmk: Missing input file 'foo.ind' (or dependence on it) from following:
  No file foo.ind.
Latexmk: References changed.
Latexmk: References changed.
Latexmk: Log file says output to 'foo.pdf'
Have index file 'foo.idx', foo.ind foo
Latexmk: applying rule 'makeindex foo.idx'...
Rule 'makeindex foo.idx':  Reasons for rerun
Category 'other':
  Rerun of 'makeindex foo.idx' forced or previously required:
    Reason or flag: 'Initial set up of rule'

------------
Run number 1 of rule 'makeindex foo.idx'
------------
------------
Running 'makeindex -s python.ist  -o "foo.ind" "foo.idx"'
------------
This is makeindex, version 2.17 [TeX Live 2024] (kpathsea + Thai support).
Scanning style file ./python.ist.......done (7 attributes redefined, 0 ignored).
Scanning input file foo.idx...done (0 entries accepted, 0 rejected).
Nothing written in foo.ind.
Transcript written in foo.ilg.
Latexmk: applying rule 'pdflatex'...
Rule 'pdflatex':  Reasons for rerun
Changed files or newly in use/created:
  foo.aux
  foo.ind
  foo.out
  foo.toc

------------
Run number 2 of rule 'pdflatex'
------------
------------
Running 'pdflatex -halt-on-error -interaction=batchmode  -recorder  "foo.tex"'
------------
This is pdfTeX, Version 3.141592653-2.6-1.40.26 (TeX Live 2024) (preloaded format=pdflatex)
 restricted \write18 enabled.
entering extended mode
Latexmk: Getting log file 'foo.log'
Latexmk: Examining 'foo.fls'
Latexmk: Examining 'foo.log'
Latexmk: Index file 'foo.idx' was written
Latexmk: Log file says output to 'foo.pdf'
Have index file 'foo.idx', foo.ind foo
Latexmk: All targets (foo.pdf) are up-to-date

In case of error it will end in

...
Have index file 'foo.idx', foo.ind foo
Latexmk: Errors, so I did not complete making targets
Collected error summary (may duplicate other messages):
  pdflatex: Command for 'pdflatex' gave return code 1
      Refer to 'foo.log' and/or above output for details

Latexmk: Sometimes, the -f option can be used to get latexmk
  to try to force complete processing.
  But normally, you will need to correct the file(s) that caused the
  error, and then rerun latexmk.
  In some cases, it is best to clean out generated files before rerunning
  latexmk after you've corrected the files.
make: *** [Makefile:29: foo.pdf] Error 12
Latex error: check .log file in _build/latex

(obsolete) This is admittedly a bit verbose but as explained above, the -silent option of Latexmk suppresses too much, and allowing only stderr gives strange console output with innocuous messages making it to stderr.

EDIT: it was decided to use -silent option of Latexmk despite initial reservations.

Alternative syntax are make latexpdf O="-Q" and respectively make latexpdf O="-q".

For example, in case of LaTeX error:

$ make latexpdf O="-Q"
Latex error: check _build/latex/__LATEXSTDOUT__
make: *** [Makefile:20: latexpdf] Error 2

and

$ make latexpdf O="-Q"

i.e. no output whatsoever if no error.

[jfbu]

I am open to using Latexmk -silent in case of -q, despite what I said. But I have had experiences with it where it made diagostics of a problem complex. Admittedly this was in a special context where the main tex file externalized sub-Latexmk commands. So maybe my bad feelings with Latexmk's -silent are not justified.

[jfbu]

I made a change to use in case of -q the -silent option of Latexmk, for reasons explained above. However I don't know how to not override environment or command line (in case of make) LATEXOPTS and LATEXMKOPTS, and I am not even sure this syntax is make.bat compatible at all (help wanted for Windows). I thought about setting the variables at start of command line, but feared it would be even worse for Windows, not sure.

[jfbu]

Help is needed for Windows.

[jfbu]

It is paradoxical that -q runs Latexmk with -silent and -Q does not but captures all its output instead to save it into some file. The reason for not having -q simply capture stdout in a file, is that Latexmk outputs benign information to stderr sometimes, not stdout.

Also: currently make latexpdf O=-q LATEMKOPTS=-xelatex will ignore the LATEXMKOPTS setting (for a project using xelatex). One will have to do make latex O=-q (or equivalent with sphinx-build) and in second step do make -C <builddir> all-pdf LATEXMKOPTS="-xelatex -silent" to achieve similar effect. I don't know how to use subprocess.call to merge env or cmd line LATEXMKOPTS with addition of -silent.

[AA-Turner]

Please could you add a CHANGES entry?

A

[jfbu]

@AA-Turner ok, will do for CHANGES. I had some mail exchanges with the maintainer of Latexmk, and proposed that perhaps in future Latexmk's options -quiet and -silent acquire distinct meanings. I don't know if that proposal will be implemented, but perhaps in future we may have to check if its is interesting to replace the LATEXMKOPTS=-silent by LATEXMKOPTS=-quiet for the -q support. For current and afaik past versions they are aliases.

The defect of my implementation is that it overrides user LATEXMKOPTS from command line or environment. But the stronger -Q does not (as it simply redirects both stdout and stderr to some file and does not use our latex Makefile LATEXMKOPTS mechanism).