Opened 9 years ago

Closed 9 years ago

#25738 closed Bug (duplicate)

Docs code listings in PDF format are broken

Reported by: Graham Wideman Owned by: nobody
Component: Documentation Version: 1.8
Severity: Normal Keywords: PDF formatting
Cc: Triage Stage: Unreviewed
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: yes UI/UX: no

Description

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.

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

Attachments (1)

DjangoDocsBrokenCodeFormatting.png (34.8 KB ) - added by Graham Wideman 9 years ago.
Sample of broken code formatting in PDF of docs

Download all attachments as: .zip

Change History (2)

by Graham Wideman, 9 years ago

Sample of broken code formatting in PDF of docs

comment:1 by Tim Graham, 9 years ago

Resolution: duplicate
Status: newclosed

Duplicate of #23751

Note: See TracTickets for help on using tickets.
Back to Top