classification
Title: wrong page index number in reference book of python documentation
Type: behavior Stage:
Components: Documentation tools (Sphinx) Versions: Python 3.0, Python 2.6
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: georg.brandl Nosy List: georg.brandl, ray, terry.reedy, wplappert
Priority: normal Keywords:

Created on 2008-10-03 09:41 by ray, last changed 2008-10-19 08:19 by wplappert. This issue is now closed.

Files
File name Uploaded Description Edit
ref.png ray, 2008-10-03 09:41 reference document
distutils.png wplappert, 2008-10-04 09:19 TOC for distutils.pdf (Python 2.6)
typescript wplappert, 2008-10-17 13:52 make [pdf] \tableofcontents error
Messages (19)
msg74233 - (view) Author: Ray Wang (ray) Date: 2008-10-03 09:41
the Glossary's index number is 3, which should be 75,
so people could not navigate "Glossary" by clicking the title showed in
Table of Content, or index link which is beside the content in Evince.
msg74293 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2008-10-04 00:56
Which version of the Ref Manual is this supposed to be?
By Evince do you mean the Gnome document viewer?
http://www.gnome.org/projects/evince/
If so, are you trying to view a .pdf downloaded from python.org?
If so, did you try viewing it with acrobat or some other .pdf viewer?
This would indicate whether the fault is with the Evince or Python's
.pdf generation or index support.

The screenshot shows two other major problems with the TOC.
Data model should not be indented; it is not part of lexical analysis.
Three chapters between Data Model and Compound Statements are missing.
msg74302 - (view) Author: Ray Wang (ray) Date: 2008-10-04 07:58
hi, sorry for didn't present very clear.

> Which version of the Ref Manual is this supposed to be?

the newest python documentations, Release 2.6, October 2, 2008

> By Evince do you mean the Gnome document viewer?
> http://www.gnome.org/projects/evince/

Yes

> If so, are you trying to view a .pdf downloaded from python.org?

Yes, from the official site. download the docs from
http://docs.python.org/ftp/python/doc/2.6/python-docs-pdf-a4.tar.bz2

> If so, did you try viewing it with acrobat or some other .pdf viewer?

Yes, the same. I tested in acrobat. both has this problem. 

> This would indicate whether the fault is with the Evince or Python's
> .pdf generation or index support.

I guess the problem is index support.

> The screenshot shows two other major problems with the TOC.
> Data model should not be indented; it is not part of lexical analysis.
> Three chapters between Data Model and Compound Statements are missing.

exactly, the index may be messed up.
msg74307 - (view) Author: Winfried Plappert (wplappert) Date: 2008-10-04 08:39
In addition to the same issue: library.pdf, downloaded from
http://docs.python.org/ftp/python/doc/2.6/python-docs-pdf-a4.tar.bz2:

Glossary                points to chapter 1, 
"About these documents"           chapter 2,
History and License               chapter 3,
Copyright                         chapter 4.

The Index points correctly to the "Symbol Index", but misplaces the
"Module Index": the "Module Index" is a subchapter of the "Copyright".
msg74308 - (view) Author: Winfried Plappert (wplappert) Date: 2008-10-04 09:19
distutils.pdf shows the wrong behaviour quite nicely. See attached png file
msg74797 - (view) Author: Ray Wang (ray) Date: 2008-10-15 09:07
any feedback here?
msg74808 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2008-10-15 17:37
We are all volunteers here, and I see three replies.
This may or may not be trivial to fix, and may take some time.

Python docs are written in rst format and translated by Sphinx to
various formats.  The main translation is to html, as viewed on the
site. Translation to .pdf is indirect via translation to latex and then
from latex to .pdf.  Since the .html index appears flawless, and since a
different .pdf has problems, I suspect that the .pdf index problem is in
one of the two translation steps.  Hence the change of component.

In the meanwhile, either ignore the index or use the html version.
msg74826 - (view) Author: Ray Wang (ray) Date: 2008-10-16 02:54
> We are all volunteers here, and I see three replies.
> This may or may not be trivial to fix, and may take some time.

> Python docs are written in rst format and translated by Sphinx to
> various formats.  The main translation is to html, as viewed on the
> site. Translation to .pdf is indirect via translation to latex and then
> from latex to .pdf.  Since the .html index appears flawless, and since a
> different .pdf has problems, I suspect that the .pdf index problem is in
> one of the two translation steps.  Hence the change of component.

> In the meanwhile, either ignore the index or use the html version.

Thanks a lot for you reply. I just intend to raise somebody's attention
to this 
problem in order to improve reader's experience.

It might or might not be a trivial to fix though.
msg74828 - (view) Author: Winfried Plappert (wplappert) Date: 2008-10-16 06:43
This  problem also applies to Python 3.0rc1. 

Georg, could you please comment on ray's and tjreedy's question. Thanks
msg74830 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2008-10-16 07:47
I'm not ignoring this issue; I think it's a trivial fix once I find out
where :)
msg74831 - (view) Author: Ray Wang (ray) Date: 2008-10-16 10:55
ah, thanks goodness, what a fortune that you are not ignoring this problem.
I expect the fix could be happen in the near future. :)
msg74858 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2008-10-16 21:04
OK, I have the problem. The hyperref package must not be included before
fncychap, in fact, it should be included last.

I'll fix this as soon as I've found the most adaptable way to do it. :)
msg74897 - (view) Author: Ray Wang (ray) Date: 2008-10-17 05:50
Woohoo, you are awesome, thanks a lot!
msg74901 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2008-10-17 11:25
Should be fixed now in r66955. Thanks for your patience!
msg74908 - (view) Author: Winfried Plappert (wplappert) Date: 2008-10-17 13:52
Hi Georg,
I tried to rebuilt the documentation from scratch (2.6 as well as
3.0rc1) and make fails with the command " \tableofcontents", which is
part of the generated *.tex file. I will include the typescript output
of the make command. The error message in 'typescript' is line 77. The
checked ot revision of sphinx is: 'Checked out revision 66957.'
msg74911 - (view) Author: Winfried Plappert (wplappert) Date: 2008-10-17 14:19
Interesting: I reran the build of PDFs under Windows (XP) and it works
like a charm! Everything is there, the TOC, the Index and the Contents.
I have no idea why Ubuntus pdflatex decided to go on strike. Thanks a
lot for all your work!
msg74950 - (view) Author: Ray Wang (ray) Date: 2008-10-18 04:35
Thanks for your big efforts!
msg74955 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2008-10-18 18:07
Winfried, can you try again with the newest trunk?
msg74967 - (view) Author: Winfried Plappert (wplappert) Date: 2008-10-19 08:19
Georg, 
sphinx r66972 works perfectly. Thanks again!
History
Date User Action Args
2008-10-19 08:19:37wplappertsetmessages: + msg74967
2008-10-18 18:07:47georg.brandlsetmessages: + msg74955
2008-10-18 04:35:30raysetmessages: + msg74950
2008-10-17 14:19:03wplappertsetmessages: + msg74911
2008-10-17 13:52:23wplappertsetfiles: + typescript
messages: + msg74908
2008-10-17 11:25:23georg.brandlsetstatus: open -> closed
resolution: fixed
messages: + msg74901
2008-10-17 05:50:25raysetmessages: + msg74897
2008-10-16 21:04:01georg.brandlsetmessages: + msg74858
2008-10-16 10:55:42raysetmessages: + msg74831
2008-10-16 07:47:54georg.brandlsetmessages: + msg74830
2008-10-16 06:43:31wplappertsetmessages: + msg74828
versions: + Python 3.0
2008-10-16 02:54:55raysetmessages: + msg74826
2008-10-15 17:37:58terry.reedysetmessages: + msg74808
components: + Documentation tools (Sphinx), - Documentation
2008-10-15 09:07:05raysetmessages: + msg74797
2008-10-04 09:19:20wplappertsetfiles: + distutils.png
messages: + msg74308
2008-10-04 08:39:10wplappertsetnosy: + wplappert
messages: + msg74307
2008-10-04 07:58:50raysetmessages: + msg74302
2008-10-04 00:56:15terry.reedysetnosy: + terry.reedy
messages: + msg74293
2008-10-03 09:41:15raycreate