+
+Overview
+
+PDF is evil.
+Because a PDF file is normally big and has a complex structure,
+parsing a PDF as a whole is time-and-memory
+consuming. Furthermore, not every part is needed for most PDF
+processing. Therefore, PDFMiner takes a strategy of lazy parsing,
+which is to parse the stuff only when it's necessary. To parse PDF
+files, you need at least two classes: PDFParser
+and PDFDocument. These objects work together.
+PDFParser fetches (or parses) data from a PDF,
+and PDFDocument stores it. You'll also need
+PDFPageInterpreter to process the page contents
+and PDFDevice to translate it to whatever you need.
+
+
+PDF documents are more like graphics format, rather than text
+format. The contents in PDF are just a bunch of procedures that
+tell how to render the stuff on a display or paper. In most
+cases, it presents no logical structure such as sentences or
+paragraphs. So PDFMiner attempts to reconstruct some of them by
+performing layout analysis. Ugly, I know. Again, PDF is evil.
+
+
+Figure 1 shows the relationship between these classes:
+
+
+
+
Figure 1. Relationships between PDFMiner classes
+
Accessing Layout Objects
-PDF documents are more like graphics, rather than text documents.
-In most cases, it presents no logical structure such as sentences or paragraphs.
-PDFMiner attempts to reconstruct some of them by performing
-basic layout analysis.
-
-Here is a typical way to do it:
+Here is a typical way to use the layout analysis function:
from pdfminer.layout import LAParams
from pdfminer.converter import PDFPageAggregator
@@ -172,11 +192,12 @@ for (level,title,dest,a,se) in outlines:
-In some PDF documents, destinations are referred to as page numbers.
-In other PDF documents, destinations are referred to as page numbers plus
-the location within the page. Since PDF does not provide a way to
-point to graphical objects in a page, normally these in-page destinations
-are specified by physical coordinates.
+Some PDF documents use page numbers as destinations, while others
+use page numbers and the physical location within the page. Since
+PDF does not have a logical strucutre, and it does not provide a
+way to refer to any in-page object from the outside, there's no
+way to tell exactly which part of text these destinations are
+refering to.
Yusuke Shinyama