From 73b88a0a6ffcbbbca6832108172257c39b06247c Mon Sep 17 00:00:00 2001
From: "James R. Barlow" <jim@purplerock.ca>
Date: Fri, 28 Oct 2016 01:22:40 -0700
Subject: [PATCH] More work on documentation

---
 docs/cookbook.rst     |  8 +++++---
 docs/errors.rst       | 33 +++++++++++++++++++++++++++++++++
 docs/index.rst        |  1 +
 docs/introduction.rst | 12 +++++++-----
 ocrmypdf/__main__.py  |  3 +++
 5 files changed, 49 insertions(+), 8 deletions(-)
 create mode 100644 docs/errors.rst

diff --git a/docs/cookbook.rst b/docs/cookbook.rst
index 5c191f0b..bebbc61b 100644
--- a/docs/cookbook.rst
+++ b/docs/cookbook.rst
@@ -69,9 +69,11 @@ You can also use Tesseract 3.04+ directly to convert single page images or multi
 Image processing
 ----------------
 
-OCRmyPDF perform some image processing on each page of a PDF, if desired.  The same processing is applied to each page.
+OCRmyPDF perform some image processing on each page of a PDF, if desired.  The same processing is applied to each page.  It is suggested that the user review files after image processing as these commands might remove desirable content, especially from poor quality scans.
 
-OCRmyPDF has two image processing functions: deskew and clean.  
+* ``--rotate-pages`` attempts to determine the correct orientation for each page and rotates the page if necessary.
+
+* ``--remove-background`` attempts to detect and remove a noisy background from grayscale or color images.  Monochrome images are ignored. This should not be used on documents that contain color photos as it may remove them.
 
 * ``--deskew`` will correct pages were scanned at a skewed angle by rotating them back into place.  Skew determination and correction is performed using `Postl's variance of line sums <http://www.leptonica.com/skew-measurement.html>`_ algorithm as implemented in `Leptonica <http://www.leptonica.com/index.html>`_.
   
@@ -127,7 +129,7 @@ Consider using the excellent `GNU Parallel <https://www.gnu.org/software/paralle
 
 Both ``parallel`` and ``ocrmypdf`` will try to use all available processors. To maximize parallelism without overloading your system with processes, consider using ``parallel -j 2`` to limit parallel to running two jobs at once.
 
-This command will run all ocrmypdf all files named ``\*.pdf`` in the current directory and write them to the previous created ``output/`` folder.
+This command will run all ocrmypdf all files named ``*.pdf`` in the current directory and write them to the previous created ``output/`` folder.
 
 .. code-block:: bash
 
diff --git a/docs/errors.rst b/docs/errors.rst
new file mode 100644
index 00000000..44bc5732
--- /dev/null
+++ b/docs/errors.rst
@@ -0,0 +1,33 @@
+Common error messages
+=====================
+
+Page already has text
+---------------------
+
+.. code::
+
+	ERROR -    1: page already has text! – aborting (use --force-ocr to force OCR)
+
+You ran ocrmypdf on a file that already contains printable text or a hidden OCR text layer (it can't quite tell the difference). You probably don't want to do this, because the file is already searchable.
+
+As the error message suggests, your options are:
+
+- ``ocrmypdf --force-ocr`` to :ref:`rasterize <raster-vector>` all vector content and run OCR on the images. This is useful if a previous OCR program failed, or if the document contains a text watermark.
+
+- ``ocrmypdf --skip-text`` to skip OCR and other processing on any pages that contain text. Text pages will be copied into the output PDF without modification.
+
+
+Input file 'filename' is not a valid PDF
+----------------------------------------
+
+OCRmyPDF passes files through qpdf, a program that fixes errors in PDFs, before it tries to work on them. In most cases this happens because the PDF is corrupt and
+truncated (incomplete file copying) and not much can be done.
+
+You can try rewriting the file with Ghostscript or pdftk:
+
+- ``gs -o output.pdf -dSAFER -sDEVICE=pdfwrite input.pdf``
+
+- ``pdftk input.pdf cat output output.pdf``
+
+Sometimes Acrobat can repair PDFs with its `Preflight tool <https://helpx.adobe.com/acrobat/using/correcting-problem-areas-preflight-tool.html>`_.
+
diff --git a/docs/index.rst b/docs/index.rst
index 5daf250d..e047e555 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -20,6 +20,7 @@ Contents:
    installation
    languages
    cookbook
+   errors
 
 
 
diff --git a/docs/introduction.rst b/docs/introduction.rst
index 32511c78..376107d7 100644
--- a/docs/introduction.rst
+++ b/docs/introduction.rst
@@ -9,15 +9,16 @@ About OCR
 
 `Optical character recognition <https://en.wikipedia.org/wiki/Optical_character_recognition>`_ is technology that converts images of typed or handwritten text, such as in a scanned document, to computer text that can be searched and copied.
 
-OCRmyPDF uses `Tesseract <https://github.com/tesseract-ocr/tesseract>`_, the best available open source OCR engine, to do perform OCR.
+OCRmyPDF uses `Tesseract <https://github.com/tesseract-ocr/tesseract>`_, the best available open source OCR engine, to perform OCR.
 
+.. _raster-vector:
 
 About PDFs
 ----------
 
-PDFs are `vector graphic files <http://vector-conversions.com/vectorizing/raster_vs_vector.html>`_ that can contain raster objects such as scanned images. Because PDFs can contain multiple pages (unlike many image formats) and can contain fonts and text, it is a good formats for exchanging scanned documents.
+PDFs are page description files that attempts to preserve a layout exactly. They can contain `vector graphic files <http://vector-conversions.com/vectorizing/raster_vs_vector.html>`_ that can contain raster objects such as scanned images. Because PDFs can contain multiple pages (unlike many image formats) and can contain fonts and text, it is a good formats for exchanging scanned documents.
 
-.. image:: _static/bitmap_vs_svg.svg
+.. image:: bitmap_vs_svg.svg
 
 A PDF page might contain multiple images, even if it only appears to have one image.  Some scanners or scanning software will segment pages into monochromatic text and color regions for example, to improve the compression ratio and appearance of the page.
 
@@ -27,11 +28,12 @@ Rasterizing a PDF is the process of generating an image suitable for display or
 About PDF/A
 -----------
 
-`PDF/A <https://en.wikipedia.org/wiki/PDF/A>`_ is a standardized subset of the full PDF specification that is designed for archiving.  PDF/A differs from PDF primarily by omitting features that would make it difficult to read the file in the future.  All fonts and resources needed to interpret the PDF must be contained within it.  Generally speaking, scanned documents should be converted to PDF/A.
+`PDF/A <https://en.wikipedia.org/wiki/PDF/A>`_ is a standardized subset of the full PDF specification that is designed for archiving.  PDF/A differs from PDF primarily by omitting features that would make it difficult to read the file in the future, such as embedded Javascript or references to external fonts.  All fonts and resources needed to interpret the PDF must be contained within it.  Generally speaking, scanned documents should be converted to PDF/A. There are various conformance levels and versions, such as "PDF/A-2b".
+
+Since most people who scan documents are interested in reading them in the future, OCRmyPDF generates PDF/A-2b by default.
 
 PDF/A has a few drawbacks.  Some PDF viewers include an alert that the file is a PDF/A, which may confuse some users.  It also tends to produce larger files than PDF, because it embeds certain resources even if they are commonly available. 
 
-
 What OCRmyPDF does
 ------------------
 
diff --git a/ocrmypdf/__main__.py b/ocrmypdf/__main__.py
index 6c43a4c2..79a1e148 100755
--- a/ocrmypdf/__main__.py
+++ b/ocrmypdf/__main__.py
@@ -152,6 +152,9 @@ ocrmypdf so it is already installed.
 
     img2pdf --pagesize A4 page*.png | ocrmypdf - myfile.pdf
 
+Online documentation is located at:
+    https://ocrmypdf.readthedocs.io/en/latest/introduction.html
+
 """)
 
 parser.add_argument(