python
Incorrect rendering of primary prompt >>> on page 9 of tutorial.pdf
Bug report
Bug description:
On page 9 of the file tutorial.pdf of Python 3.12.2 documentation the primary prompt is rendered incorrectly, like this:
But in the earlier page 6 it is rendered correctly:
I noticed that in the source tree in the file Doc/tutorial/introduction.rst it is entered with the :term: prefix and in single quotes, but in the file Doc/tutorial/interpreter.rst it is entered with double single quotes. Anyway, I don't know the format the source of the documentation is maintained in, so I didn't risk providing a patch. Just reporting it here in order for someone to fix it properly.
CPython versions tested on:
3.12
Operating systems tested on:
Linux
The .rst files are the source. It would have been helpful to give the section for the error. I found it in the first line of chapter 3, where it displays correctly in the online version, with the intended links.
The .rst has :term:`>>>` and :term:`...`, which is correct, so the bug is in the .pdf generator. We likely have nothing to do with that except to use it. @hugovk Any idea?
If I try building the docs from source via make dist the generated .tex source file build/latex/tutorial.tex looks like this:
absence of prompts ({\hyperref[\detokenize{glossary:term-0}]{\sphinxtermref{\DUrole{xref,std,std-term}{>>>}}}} and
and generated .pdf file looks absolutely fine.
So, we need to find out why it builds correctly on my system and wrong on the official build system. I did everything according to the instructions in the README.rst file, i.e. make venv ; make dist.
The build system picks up my full installation of TeX Live 2023 which is confirmed by looking at the first few lines of the file build/latex/tutorial.log:
This is XeTeX, Version 3.141592653-2.6-0.999995 (TeX Live 2023) (preloaded format=xelatex 2023.4.7) 23 MAR 2024 08:57
entering extended mode
restricted \write18 enabled.
...
How do I label the current issue with the doc tag rather than type-bug, so we don't distract attention of the Python core developers unnecessarily?
I've added doc, we can keep type-bug as well.
For reference, links to the two files:
https://github.com/python/cpython/blob/72eea512b88f8fd68b7258242c37da963ad87360/Doc/tutorial/introduction.rst?plain=1#L8
https://github.com/python/cpython/blob/72eea512b88f8fd68b7258242c37da963ad87360/Doc/tutorial/interpreter.rst?plain=1#L93
And the rendered HTML versions:
- https://docs.python.org/3/tutorial/introduction.html#an-informal-introduction-to-python
- https://docs.python.org/3/tutorial/interpreter.html#interactive-mode
The .rst has
:term:`>>>`and:term:`...`, which is correct, so the bug is in the .pdf generator. We likely have nothing to do with that except to use it. @hugovk Any idea?
The PDF is generated somewhere in https://github.com/python/docsbuild-scripts.
@JulienPalard, what tools/versions are used to generate the PDF and any intermediate formats?
Looks like the official version was build with the old (2019) version of LaTeX as opposed to the latest version on my system:
$ pdfinfo tutorial.pdf
Title: Python Tutorial
Author: Guido van Rossum and the Python development team
Creator: LaTeX with hyperref
Producer: xdvipdfmx (20190824)
CreationDate: Sat Mar 16 20:40:07 2024 GMT
Custom Metadata: no
Metadata Stream: no
Tagged: no
UserProperties: no
Suspects: no
Form: none
JavaScript: no
Pages: 163
Encrypted: no
Page size: 595.28 x 841.89 pts (A4)
Page rot: 0
File size: 654208 bytes
Optimized: no
PDF version: 1.5
$ pdfinfo ~/Software/Python/Python-3.12.2/Doc/build/latex/tutorial.pdf
Title: Python Tutorial
Author: Guido van Rossum and the Python development team
Creator: LaTeX with hyperref
Producer: xdvipdfmx (20220710)
CreationDate: Sat Mar 23 08:57:26 2024 GMT
Custom Metadata: no
Metadata Stream: no
Tagged: no
UserProperties: no
Suspects: no
Form: none
JavaScript: no
Pages: 171
Encrypted: no
Page size: 612 x 792 pts (letter)
Page rot: 0
File size: 664120 bytes
Optimized: no
PDF version: 1.5
Docs is on Ubuntu-20.04. Ubuntu-22.04 is available in psf-infra if you're up for a server swap.
Just to let you know that I never (for the past 30 years of typesetting books) used the version of TeX/LaTeX that is bundled with the Linux distribution -- I always install (full) TeX Live from scratch into /usr/local/texlive and upgrade every few years, making sure that all my books and other publications still compile correctly (as I do typesetting in about 20 languages, including right-to-left ones, it is sometimes non-trivial to upgrade, i.e. some things break).
The point of this message is that I suggest you test that every pdf file of the documentation compiles correctly before you commit to an upgrade. If I can be of help, please let me know what to test and against which distribution and I will gladly do that. I recommend the latest TeX Live for pdf generation, of course :)
Can confirm this issue persists in the 3.14 (3.15 is not built yet) documentation.
Should we move this to docsbuild-scripts, since that is where the work is to be done?
