Building PDF documentation from tex files

[wplappert]

BPO	3909
Nosy	@birkenfeld
Files	tutorial.zip: tutorial.log file reference.zip: all reference.* files apart from reference.tex sphinx.sty-issue3909.diff

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = 'https://github.com/birkenfeld'
closed_at = <Date 2008-10-08.16:47:45.969>
created_at = <Date 2008-09-19.16:46:46.313>
labels = ['docs']
title = 'Building PDF documentation from tex files'
updated_at = <Date 2008-10-16.19:05:54.387>
user = 'https://bugs.python.org/wplappert'

bugs.python.org fields:

activity = <Date 2008-10-16.19:05:54.387>
actor = 'georg.brandl'
assignee = 'georg.brandl'
closed = True
closed_date = <Date 2008-10-08.16:47:45.969>
closer = 'georg.brandl'
components = ['Documentation']
creation = <Date 2008-09-19.16:46:46.313>
creator = 'wplappert'
dependencies = []
files = ['11525', '11626', '11805']
hgrepos = []
issue_num = 3909
keywords = ['patch']
message_count = 14.0
messages = ['73430', '73431', '73497', '73559', '73734', '73856', '73874', '73884', '73899', '74227', '74338', '74535', '74809', '74846']
nosy_count = 3.0
nosy_names = ['georg.brandl', 'wplappert', 'sergey']
pr_nums = []
priority = 'normal'
resolution = 'works for me'
stage = None
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue3909'
versions = ['Python 2.6', 'Python 3.0']

[wplappert]

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

[wplappert]

modified version info: 2.6, 3.0

[birkenfeld]

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.

[wplappert]

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 :)

[birkenfeld]

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?

[wplappert]

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.

[wplappert]

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).

[birkenfeld]

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?

[wplappert]

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.

[wplappert]

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?

[wplappert]

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