id	summary	reporter	owner	description	type	status	component	version	severity	resolution	keywords	cc	stage	has_patch	needs_docs	needs_tests	needs_better_patch	easy	ui_ux
25738	Docs code listings in PDF format are broken	Graham Wideman	nobody	"Affects PDF docs downloaded today, 2015-11-11, from https://readthedocs.org/projects/django/downloads/pdf/1.8.x/ (and all other version numbers)

1. Broken rendering of certain code blocks

Throughout the Django docs PDF format, in every code listing that has a grey-bar file name header, the code is formatted unreadably, and appears before the code box, instead of within it. 

I will attempt to attach a screenshot. However, examples are easy to find. In the 1.8 PDF this problem can be found starting at page 9, and continuing especially throughout chapter 2 and intermittently elsewhere.

The problem is almost certainly in the apparatus that translates the doc source code into PDF, but is possibly sensitive to the particular combination of nested blocks and formatting of those blocks.

2. Code example text colors print unreadably from the PDF.  The font colors for much of the syntax highlighting is too light to print readably on a monochrome printer, even using maximum Acrobat accessibility tricks. This should be a matter of simply darkening the CSS or whatever is used to define syntax colors for the PDF translation.

Since the PDF is the main way to read large chunks for the Django docs in a coherent way, these obstacles make for a significant impediment to would-be learners.  

The ePub version is not affected by the code formatting problem, but that format is not a serious solution due to lack of page layout suited for printing and lack of page numbers and section numbers by which to navigate in the 1500+ pages equivalent.
"	Bug	closed	Documentation	1.8	Normal	duplicate	PDF formatting		Unreviewed	0	0	0	0	1	0