diff --git a/README.md b/README.md new file mode 100644 index 00000000..686ecb09 --- /dev/null +++ b/README.md @@ -0,0 +1,132 @@ +OCRmyPDF +======== + +![image](https://travis-ci.org/jbarlow83/OCRmyPDF.svg?branch=master%0A%20:target:%20https://travis-ci.org/jbarlow83/OCRmyPDF) + +![image](https://img.shields.io/pypi/v/ocrmypdf.svg%0A%20:target:%20https://pypi.org/project/ocrmypdf/) + +![image](https://img.shields.io/homebrew/v/ocrmypdf.svg%0A%20:alt:%20homebrew%0A%20:target:%20http://brewformulas.org/Ocrmypdf) + +OCRmyPDF adds an OCR text layer to scanned PDF files, allowing them to be searched or copy-pasted. + +```bash +ocrmypdf # it's a scriptable command line program + -l eng+fra # it supports multiple languages + --rotate-pages # it can fix pages that are misrotated + --deskew # it can deskew crooked PDFs! + --title "My PDF" # it can change output metadata + --jobs 4 # it uses multiple cores by default + --output-type pdfa # it produces PDF/A by default + input_scanned.pdf # takes PDF input (or images) + output_searchable.pdf # produces validated PDF output +``` + +Main features +------------- + +- Generates a searchable [PDF/A](https://en.wikipedia.org/?title=PDF/A) file from a regular PDF +- Places OCR text accurately below the image to ease copy / paste +- Keeps the exact resolution of the original embedded images +- When possible, inserts OCR information as a "lossless" operation without disrupting any other content +- Optimizes PDF images, often producing files smaller than the input file +- If requested deskews and/or cleans the image before performing OCR +- Validates input and output files +- Distributes work across all available CPU cores +- Uses [Tesseract OCR](https://github.com/tesseract-ocr/tesseract) engine +- Supports more than [100 languages](https://github.com/tesseract-ocr/tessdata) recognized by Tesseract +- Battle-tested on thousands of PDFs, a test suite and continuous integration + +For details: please consult the [documentation](https://ocrmypdf.readthedocs.io/en/latest/). + +Motivation +---------- + +I searched the web for a free command line tool to OCR PDF files on Linux/UNIX: I found many, but none of them were really satisfying. + +- Either they produced PDF files with misplaced text under the image (making copy/paste impossible) +- Or they did not handle accents and multilingual characters +- Or they changed the resolution of the embedded images +- Or they generated ridiculously large PDF files +- Or they crashed when trying to OCR +- Or they did not produce valid PDF files +- On top of that none of them produced PDF/A files (format dedicated for long time storage) + +...so I decided to develop my own tool. + +Installation +------------ + +Linux, UNIX, and macOS are supported. Windows is not directly supported but there is a Docker image available that runs on Windows. + +Users of Debian 9 or later or Ubuntu 16.10 or later may simply + +```bash +apt-get install ocrmypdf +``` + +and macOS users with Homebrew may simply + +```bash +brew install ocrmypdf +``` + +For everyone else, [see our documentation](https://ocrmypdf.readthedocs.io/en/latest/installation.html) for installation steps. + +Languages +--------- + +OCRmyPDF uses Tesseract for OCR, and relies on its language packs. For Linux users, you can often find packages that provide language packs: + +```bash +# Display a list of all Tesseract language packs +apt-cache search tesseract-ocr + +# Debian/Ubuntu users +apt-get install tesseract-ocr-chi-sim # Example: Install Chinese Simplified language back +``` + +You can then pass the `-l LANG` argument to OCRmyPDF to give a hint as to what languages it should search for. Multiple languages can be requested. + +Documentation and support +------------------------- + +Once ocrmypdf is installed, the built-in help which explains the command syntax and options can be accessed via: + +```bash +ocrmypdf --help +``` + +Our [documentation is served on Read the Docs](https://ocrmypdf.readthedocs.io/en/latest/index.html). + +If you detect an issue, please: + +- Check whether your issue is already known +- If no problem report exists on github, please create one here: +- Describe your problem thoroughly +- Append the console output of the script when running the debug mode (`-v 1` option) +- If possible provide your input PDF file as well as the content of the temporary folder (using a file sharing service like Dropbox) + +Requirements +------------ + +Runs on CPython 3.5, 3.6 and 3.7. Requires external program installations of Ghostscript, Tesseract OCR, QPDF, and Leptonica. ocrmypdf is pure Python, but uses CFFI to portably generate library bindings. + +Press & Media +------------- + +- [c't 1-2014, page 59](http://heise.de/-2279695): Detailed presentation of OCRmyPDF v1.0 in the leading German IT magazine c't +- [heise Open Source, 09/2014: Texterkennung mit OCRmyPDF](http://heise.de/-2356670) + +License +------- + +The OCRmyPDF software is licensed under the GNU GPLv3. Certain files are covered by other licenses, as noted in their source files. + +The license for each test file varies, and is noted in tests/resources/README.rst. The documentation is licensed under Creative Commons Attribution-ShareAlike 4.0 (CC-BY-SA 4.0). + +OCRmyPDF versions prior to 6.0 were licensed under the MIT License. + +Disclaimer +---------- + +The software is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. diff --git a/README.rst b/README.rst deleted file mode 100644 index 71dc137f..00000000 --- a/README.rst +++ /dev/null @@ -1,150 +0,0 @@ -OCRmyPDF -======== - -.. image:: https://travis-ci.org/jbarlow83/OCRmyPDF.svg?branch=master - :target: https://travis-ci.org/jbarlow83/OCRmyPDF - -.. image:: https://img.shields.io/pypi/v/ocrmypdf.svg - :target: https://pypi.org/project/ocrmypdf/ - -.. image:: https://img.shields.io/homebrew/v/ocrmypdf.svg - :alt: homebrew - :target: http://brewformulas.org/Ocrmypdf - - -OCRmyPDF adds an OCR text layer to scanned PDF files, allowing them to -be searched or copy-pasted. - -.. code-block:: bash - - ocrmypdf # it's a scriptable command line program - -l eng+fra # it supports multiple languages - --rotate-pages # it can fix pages that are misrotated - --deskew # it can deskew crooked PDFs! - --title "My PDF" # it can change output metadata - --jobs 4 # it uses multiple cores by default - --output-type pdfa # it produces PDF/A by default - input_scanned.pdf # takes PDF input (or images) - output_searchable.pdf # produces validated PDF output - - -Main features -------------- - -- Generates a searchable - `PDF/A `_ file from a regular PDF -- Places OCR text accurately below the image to ease copy / paste -- Keeps the exact resolution of the original embedded images -- When possible, inserts OCR information as a "lossless" operation without disrupting any other content -- Optimizes PDF images, often producing files smaller than the input file -- If requested deskews and/or cleans the image before performing OCR -- Validates input and output files -- Distributes work across all available CPU cores -- Uses `Tesseract OCR `_ engine -- Supports more than `100 languages `_ recognized by Tesseract -- Battle-tested on thousands of PDFs, a test suite and continuous integration - -For details: please consult the `documentation `_. - -Motivation ----------- - -I searched the web for a free command line tool to OCR PDF files on -Linux/UNIX: I found many, but none of them were really satisfying. - -- Either they produced PDF files with misplaced text under the image (making copy/paste impossible) -- Or they did not handle accents and multilingual characters -- Or they changed the resolution of the embedded images -- Or they generated ridiculously large PDF files -- Or they crashed when trying to OCR -- Or they did not produce valid PDF files -- On top of that none of them produced PDF/A files (format dedicated for long time storage) - -...so I decided to develop my own tool. - -Installation ------------- - -Linux, UNIX, and macOS are supported. Windows is not directly supported but there is a Docker image available that runs on Windows. - -Users of Debian 9 or later or Ubuntu 16.10 or later may simply - -.. code-block:: bash - - apt-get install ocrmypdf - -and macOS users with Homebrew may simply - -.. code-block:: bash - - brew install ocrmypdf - -For everyone else, `see our documentation `_ for installation steps. - -Languages ---------- - -OCRmyPDF uses Tesseract for OCR, and relies on its language packs. For Linux users, -you can often find packages that provide language packs: - -.. code-block:: bash - - # Display a list of all Tesseract language packs - apt-cache search tesseract-ocr - - # Debian/Ubuntu users - apt-get install tesseract-ocr-chi-sim # Example: Install Chinese Simplified language back - -You can then pass the ``-l LANG`` argument to OCRmyPDF to give a hint as to what languages it should search for. Multiple -languages can be requested. - -Documentation and support -------------------------- - -Once ocrmypdf is installed, the built-in help which explains the command syntax and options can be accessed via: - -.. code-block:: bash - - ocrmypdf --help - -Our `documentation is served on Read the Docs `_. - -If you detect an issue, please: - -- Check whether your issue is already known -- If no problem report exists on github, please create one here: - https://github.com/jbarlow83/OCRmyPDF/issues -- Describe your problem thoroughly -- Append the console output of the script when running the debug mode - (``-v 1`` option) -- If possible provide your input PDF file as well as the content of the - temporary folder (using a file sharing service like Dropbox) - -Requirements ------------- - -Runs on CPython 3.5, 3.6 and 3.7. Requires external program installations of Ghostscript, Tesseract OCR, QPDF, and Leptonica. ocrmypdf is pure Python, but uses CFFI to portably generate library bindings. - -Press & Media -------------- - -- `c't 1-2014, page 59 `_: - Detailed presentation of OCRmyPDF v1.0 in the leading German IT - magazine c't -- `heise Open Source, 09/2014: Texterkennung mit - OCRmyPDF `_ - -License -------- - -The OCRmyPDF software is licensed under the GNU GPLv3. Certain files are covered by other licenses, as noted in their source files. - -The license for each test file varies, and is noted in tests/resources/README.rst. The documentation is licensed under Creative Commons Attribution-ShareAlike 4.0 (CC-BY-SA 4.0). - -OCRmyPDF versions prior to 6.0 were licensed under the MIT License. - -Disclaimer ----------- - -The software is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR -CONDITIONS OF ANY KIND, either express or implied. diff --git a/docs/release_notes.rst b/docs/release_notes.rst index 46a7dd16..c654156c 100644 --- a/docs/release_notes.rst +++ b/docs/release_notes.rst @@ -26,6 +26,8 @@ v7.1.0 - Improved handling of KeyboardInterrupt error messages. (`#301 `_) +- README.md is now served in GitHub markdown instead of reStructuredText. + v7.0.6 ------ diff --git a/setup.py b/setup.py index 0d8d310b..27122284 100644 --- a/setup.py +++ b/setup.py @@ -205,13 +205,14 @@ tests_require = open('test_requirements.txt').read().splitlines() def readme(): - with open('README.rst') as f: + with open('README.md') as f: return f.read() setup( name='ocrmypdf', description='OCRmyPDF adds an OCR text layer to scanned PDF files, allowing them to be searched', long_description=readme(), + long_description_content_type='text/markdown', url='https://github.com/jbarlow83/OCRmyPDF', author='James R. Barlow', author_email='jim@purplerock.ca', @@ -269,4 +270,10 @@ setup( }, package_data={'ocrmypdf': ['data/sRGB.icc']}, include_package_data=True, - zip_safe=False) + zip_safe=False, + project_urls={ + 'Documentation': 'https://ocrmypdf.readthedocs.io/', + 'Source': 'https://github.com/jbarlow83/ocrmypdf', + 'Tracker': 'https://github.com/jbarlow83/ocrmypdf/issues' + } +)