classification
Title: Building PDF documentation from tex files
Type: Stage:
Components: Documentation Versions: Python 3.0, Python 2.6
process
Status: closed Resolution: works for me
Dependencies: Superseder:
Assigned To: georg.brandl Nosy List: georg.brandl, sergey, wplappert
Priority: normal Keywords: patch

Created on 2008-09-19 16:46 by wplappert, last changed 2008-10-16 19:05 by georg.brandl. This issue is now closed.

Files
File name Uploaded Description Edit
tutorial.zip wplappert, 2008-09-19 16:46 tutorial.log file
reference.zip wplappert, 2008-09-26 22:17 all reference.* files apart from reference.tex
sphinx.sty-issue3909.diff sergey, 2008-10-15 17:41
Messages (14)
msg73430 - (view) Author: Winfried Plappert (wplappert) Date: 2008-09-19 16:46
I try to build PDF documentation from current Python-2.6rc2 and Python-
3.0rc1 versions. I tried the process under Windows XP and also Linux 
(Ubuntu). The results are the same. The documentation is not built 
correctly, mostly the table of contents and always the index is missing. 
pdflatex always stops with the same error:

! Too many }'s.
l.122 }

Line 122 refers to the file sphinx.sty.

After stopping, I rerun pdflatex with the command "R" to completion. 
This run has been created via the 3.0rc1 files, based on WindowsXP.

I will include a log file from the pdflatex build process. The error is 
in line 364 of file tutorial.log. 

The pdflatex (WindowsXP) version is:
MiKTeX-pdfTeX 2.7.3147 (1.40.9) (MiKTeX 2.7)
Copyright (C) 1982 D. E. Knuth, (C) 1996-2006 Han The Thanh
TeX is a trademark of the American Mathematical Society.

In case you need more docu, please let me know.

Winfried
msg73431 - (view) Author: Winfried Plappert (wplappert) Date: 2008-09-19 16:50
modified version info: 2.6, 3.0
msg73497 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2008-09-21 07:38
Which version of Sphinx did you use to build the docs? The Python docs
currently need the unreleased SVN version (that will of course change
for the final release).

If you have a Sphinx release installed as a Python egg, it will cause
problems, even if you used the Makefile to checkout the latest from SVN.
msg73559 - (view) Author: Winfried Plappert (wplappert) Date: 2008-09-22 07:28
Hi Georg,
whatever I am getting when I am doing a make latex in the Docs 
directory. The current version is 66550: "Sphinx v0.5, building latex".

I just redid it again and the error persists. But you say that one has 
to use unreleased SVN versions. So I have to wait another few days for 
a PDF version of the new documents.

Thanks a lot for your time,
Winfried - viele Grüße nach München und viel Glück in der Pyhsik :)
msg73734 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2008-09-24 17:16
Hmm, I can't really tell what may cause the "Too many }" error. Can you
try and play around with sphinx.sty, commenting out stuff, to find where
it comes from?
msg73856 - (view) Author: Winfried Plappert (wplappert) Date: 2008-09-26 16:07
I had a go at commenting stuff in sphinx.sty, but every change produced
another error message. In the end I concluded that the best thing is to
leave sphinx.sty untouched, despite the fact that the index is always
missing. Since I do not understand the magic of tex (or pdflatex), I
better leave it to the expert(s) to figure out how one generates perfect
PDF documentation.  Sorry for that.
msg73874 - (view) Author: Winfried Plappert (wplappert) Date: 2008-09-26 17:58
I found at least one bug:

% Detect if we're using XeLaTeX
\IfFileExists{ifxetex.sty}{%
  \RequirePackage{ifxetex}
}{% not using xelatex
  \newif\ifxetex\xetexfalse         %(line 69)
}
should say:
  \newif\ifxetex\xetexfalse\fi

That makes it possible to run through without any serious errors.

However the index is still defective. Here are the relevant line from
"reference.log" (just as an example):

"""
Writing index file reference.idx
\modindexfile=\write6

...

No file reference.ind.
[99

] (reference.aux) )
"""
Something with your suffixes seems to be incorrect, but I cannot find
it. I guess you are using a built-in macro, but you're not obeying the
filename specifications correctly. Otherwise the index should be included. 

The generated PDF looks far better, but still lacks a proper footer. The
current footer is just "Contents" (at least for reference.pdf,
documenting.pdf, extending.pdf file).
msg73884 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2008-09-26 20:29
If that solves the problem, that is very curious indeed. There must not
be a \fi after \newif; its syntax is

\newif\ifname\default

Later it can be used as \ifname ... \fi.

What TeX distribution and version of tex/latex are you using?
msg73899 - (view) Author: Winfried Plappert (wplappert) Date: 2008-09-26 22:17
I just tested it under Linux/Ubuntu and it is the same behaviour as
described earlier: fix line 69 in sphinx.sty and it works. My pdflatex
version on Windows (MiKTeX) has been mentioned in my first entry and the
version for Ubuntu is (TeX-live):

pdfTeX 3.1415926-1.40.9-2.2 (Web2C 7.5.7)
kpathsea version 3.5.7
Copyright 2008 Peter Breitenlohner (eTeX)/Han The Thanh (pdfTeX).
Kpathsea is copyright 2008 Karl Berry and Olaf Weber.
There is NO warranty.  Redistribution of this software is
covered by the terms of both the pdfTeX copyright and
the Lesser GNU General Public License.
For more information about these matters, see the file
named COPYING and the pdfTeX source.
Primary author of pdfTeX: Peter Breitenlohner (eTeX)/Han The Thanh (pdfTeX).
Kpathsea written by Karl Berry, Olaf Weber, and others.
Compiled with libpng 1.2.29; using libpng 1.2.29
Compiled with zlib 1.2.3; using zlib 1.2.3
Compiled with xpdf version 3.02pl2

I include all reference.* files (apart from reference.tex) in zipped format.
msg74227 - (view) Author: Winfried Plappert (wplappert) Date: 2008-10-03 07:41
Now that the official PDF documentation is released for download on the
website - including TOC and Index for every major document, the question
arises: what is the difference between the 'official' built and my
'private' built since some of my documents still missing the TOC and the
index? Is it the pdflatex version? The underlying OS or modified control
files? 
I have used the official 2.6 tar ball as a base fpr my experiments,
including the released sphinx version etc... Any ideas?
msg74338 - (view) Author: Winfried Plappert (wplappert) Date: 2008-10-05 09:25
I have rerun the making of the PDFs with the make command. Everything
looks fine now. I did not realize that pdflatex is called multiple times
during the process of PDF creation. 

%.pdf: %.tex
	pdflatex '$<'
	pdflatex '$<'
	pdflatex '$<'
	-makeindex -s python.ist '$(basename $<).idx'
	-makeindex -s python.ist '$(basename mod$<).idx'
	pdflatex '$<'
	pdflatex '$<'

Sorry, my fault and responsibility. Thanks, Winfried
msg74535 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2008-10-08 16:47
OK, no problem. I should have thought about that sooner. Happy TeXing :)
msg74809 - (view) Author: Sergey Lipnevich (sergey) Date: 2008-10-15 17:41
I don't know what the proper procedure is (reopening or filing a new
ticket), but I see this problem with Sphinx 0.5dev-20081015 and Python
2.6 on Windows XP. The change recommended by Winfried in msg73874 seems
to fix it (patch attached). The version of MiKTeX:

MiKTeX-pdfTeX 2.7.3147 (1.40.9) (MiKTeX 2.7)
Copyright (C) 1982 D. E. Knuth, (C) 1996-2006 Han The Thanh
TeX is a trademark of the American Mathematical Society.
msg74846 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2008-10-16 19:05
OK, I've committed a fix that I hope will work for all situations in r66916.
History
Date User Action Args
2008-10-16 19:05:54georg.brandlsetmessages: + msg74846
2008-10-15 17:41:33sergeysetfiles: + sphinx.sty-issue3909.diff
nosy: + sergey
messages: + msg74809
keywords: + patch
2008-10-08 16:47:45georg.brandlsetstatus: open -> closed
resolution: works for me
messages: + msg74535
2008-10-05 09:25:53wplappertsetmessages: + msg74338
2008-10-03 07:41:01wplappertsetmessages: + msg74227
2008-09-26 22:17:58wplappertsetfiles: + reference.zip
messages: + msg73899
2008-09-26 20:29:35georg.brandlsetmessages: + msg73884
2008-09-26 17:58:37wplappertsetmessages: + msg73874
2008-09-26 16:07:57wplappertsetmessages: + msg73856
2008-09-24 17:16:24georg.brandlsetmessages: + msg73734
2008-09-22 07:28:38wplappertsettype: crash ->
messages: + msg73559
2008-09-21 07:38:34georg.brandlsetmessages: + msg73497
2008-09-19 16:50:59wplappertsetmessages: + msg73431
versions: + Python 2.6, - Python 2.5
2008-09-19 16:46:46wplappertcreate