<?xml version='1.0' encoding='utf-8'?>
<!DOCTYPE refentry PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN' 'http://www.docbook.org/xml/4.5/docbookx.dtd'
[
    <!ENTITY p 'ocrodjvu'>
    <!ENTITY version '0.10'>
]>

<refentry>

<refentryinfo>
    <title>&p; manual</title>
    <productname>&p;</productname>
    <author>
        <firstname>Jakub</firstname> <surname>Wilk</surname>
        <email>jwilk@jwilk.net</email>
    </author>
</refentryinfo>

<refmeta>
    <refentrytitle>&p;</refentrytitle>
    <manvolnum>1</manvolnum>
    <refmiscinfo class='version'>&version;</refmiscinfo>
</refmeta>

<refnamediv>
    <refname>&p;</refname>
    <refpurpose>OCR for DjVu files</refpurpose>
</refnamediv>

<refsynopsisdiv>
    <cmdsynopsis>
        <command>&p;</command>
        <group choice='req'>
            <arg choice='plain'><option>-o</option></arg>
            <arg choice='plain'><option>--save-bundled</option></arg>
        </group>
        <arg choice='plain'><replaceable>output-djvu-file</replaceable></arg>
        <arg choice='opt' rep='repeat'><replaceable>option</replaceable></arg>
        <arg choice='plain'><replaceable>djvu-file</replaceable></arg>
    </cmdsynopsis>
    <cmdsynopsis>
        <command>&p;</command>
        <group choice='req'>
            <arg choice='plain'><option>-i</option></arg>
            <arg choice='plain'><option>--save-indirect</option></arg>
        </group>
        <arg choice='plain'><replaceable>index-djvu-file</replaceable></arg>
        <arg choice='opt' rep='repeat'><replaceable>option</replaceable></arg>
        <arg choice='plain'><replaceable>djvu-file</replaceable></arg>
    </cmdsynopsis>
    <cmdsynopsis>
        <command>&p;</command>
        <arg choice='plain'><option>--save-script</option></arg>
        <arg choice='plain'><replaceable>script-file</replaceable></arg>
        <arg choice='opt' rep='repeat'><replaceable>option</replaceable></arg>
        <arg choice='plain'><replaceable>djvu-file</replaceable></arg>
    </cmdsynopsis>
    <cmdsynopsis>
        <command>&p;</command>
        <arg choice='plain'><option>--in-place</option></arg>
        <arg choice='opt' rep='repeat'><replaceable>option</replaceable></arg>
        <arg choice='plain'><replaceable>djvu-file</replaceable></arg>
    </cmdsynopsis>
    <cmdsynopsis>
        <command>&p;</command>
        <arg choice='plain'><option>--dry-run</option></arg>
        <arg choice='opt' rep='repeat'><replaceable>option</replaceable></arg>
        <arg choice='plain'><replaceable>djvu-file</replaceable></arg>
    </cmdsynopsis>
    <cmdsynopsis>
        <command>&p;</command>
        <group choice='req'>
            <arg choice='plain'><option>--version</option></arg>
            <arg choice='plain'><option>--help</option></arg>
            <arg choice='plain'><option>-h</option></arg>
            <arg choice='plain'><option>--list-engines</option></arg>
            <arg choice='plain'><option>--list-languages</option></arg>
        </group>
    </cmdsynopsis>
</refsynopsisdiv>

<refsection>
    <title>Description</title>
    <para>
        &p; is a wrapper for OCR systems that allows you to perform OCR on DjVu files.
    </para>
    <para>
        The following OCR engines are supported:
        <itemizedlist>
        <listitem>
            <para><ulink url='https://code.google.com/p/ocropus/'><application>OCRopus</application></ulink> (internally,
                &p; calls <command>ocroscript</command>'s <command>recognize</command> (or <command>rec-tess</command>)
                command, so that ultimately <application>Tesseract</application> acts as the OCR backend);
            </para>
        </listitem>
        <listitem>
            <para><ulink url='https://launchpad.net/cuneiform-linux'><application>Cuneiform for Linux</application></ulink>.</para>
        </listitem>
        <listitem>
            <para><ulink url='https://www.gnu.org/software/ocrad/'><application>Ocrad</application></ulink>.</para>
        </listitem>
        <listitem>
            <para><ulink url='http://jocr.sourceforge.net/'><application>GOCR</application></ulink>.</para>
        </listitem>
        <listitem>
            <para>Stand-alone <ulink url='https://code.google.com/p/tesseract-ocr/'><application>Tesseract</application></ulink>.</para>
        </listitem>
        </itemizedlist>
    </para>
</refsection>

<refsection>
    <title>Options</title>
    <refsection>
        <title>OCR engine options</title>
        <variablelist>
        <varlistentry>
            <term><option>-e</option></term>
            <term><option>--engine=<replaceable>engine-id</replaceable></option></term>
            <listitem>
                <para>
                    Use this OCR engine.
                </para>
                <para>
                    The default is <quote><literal>tesseract</literal></quote>.
                    (The default was <quote><literal>ocropus</literal></quote> prior to &p; 0.8.)
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><option>--list-engines</option></term>
            <listitem>
                <para>
                    Print list of available OCR engines.
                </para>
            </listitem>
        </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Options controlling output</title>
        <variablelist>
        <varlistentry>
            <term><option>-o</option></term>
            <term><option>--save-bundled=<filename><replaceable>output-djvu-file</replaceable></filename></option></term>
            <listitem>
                <para>
                    Save OCR results as a bundled multi-page document into
                    <filename><replaceable>output-djvu-file</replaceable></filename>.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><option>-i</option></term>
            <term><option>--save-indirect=<filename><replaceable>index-djvu-file</replaceable></filename></option></term>
            <listitem>
                <para>
                    Save OCR results as an indirect multi-page document. Use
                    <filename><replaceable>index-djvu-file</replaceable></filename> as the index file name; put the
                    component files into the same directory. The directory must exist and be writable.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><option>--save-script=<filename><replaceable>script-file</replaceable></filename></option></term>
            <listitem>
                <para>
                    Save a <command>djvused</command> script with OCR results into
                    <replaceable>script-file</replaceable>.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><option>--in-place</option></term>
            <listitem>
                <para>
                    Save OCR results in place.
                </para>
                <para>
                    (Use this option to retain compatibility with &p; &lt; 0.2.)
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><option>--dry-run</option></term>
            <listitem>
                <para>
                    Don't change any files, throw OCR results away.
                </para>
            </listitem>
        </varlistentry>
        </variablelist>
        <para>
            It is mandatory to use exactly one of the above options.
        </para>
        <variablelist>
        <varlistentry>
            <term><option>--ocr-only</option></term>
            <listitem>
                <para>
                    If OCR results are to be saved to a separate document
                    (<option>-o</option>/<option>--save-bundled</option> or
                    <option>-i</option>/<option>--save-indirect</option>),
                    save only the pages selected for OCR.
                </para>
                <para>
                    The default is to save all pages, even when the <option>-p</option>/<option>--pages</option> option
                    is in effect.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><option>--clear-text</option></term>
            <listitem>
                <para>
                    Remove existing hidden text if present in the pages not selected for OCR.
                </para>
                <para>
                    (Use this option to retain compatibility with &p; &lt; 0.2.)
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><option>--save-raw-ocr=<filename><replaceable>output-directory</replaceable></filename></option></term>
            <listitem>
                <para>
                    Save raw OCR results (typically in the hOCR format) into
                    <filename><replaceable>output-directory</replaceable></filename>.
                    The directory must exist and be writable.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><option>--raw-ocr-filename-template=<filename><replaceable>template</replaceable></filename></option></term>
            <listitem>
                <para>
                    Specifies the file naming scheme for raw OCR results.
                </para>
                <para>
                    The template language uses the <ulink
                    url='https://docs.python.org/library/string.html#format-string-syntax'>Python
                    string formatting syntax</ulink>. The following fields are available:
                    <variablelist>
                        <varlistentry>
                            <term><varname>page</varname></term>
                            <term><varname>page+<replaceable>N</replaceable></varname></term>
                            <term><varname>page-<replaceable>N</replaceable></varname></term>
                            <listitem>
                                <para>page number, optionally shifted by a number <replaceable>N</replaceable></para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term><varname>id</varname></term>
                            <listitem>
                                <para>page identifier</para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term><varname>id-ext</varname></term>
                            <listitem>
                                <para>page identifier without file extension</para>
                            </listitem>
                        </varlistentry>
                    </variablelist>
                </para>
                <para>
                    The default template is <quote><literal>{id-ext}</literal></quote>.
                </para>
            </listitem>
        </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Text segmentation options</title>
        <variablelist>
        <varlistentry>
            <term><option>-t lines</option></term>
            <term><option>--details lines</option></term>
            <listitem>
                <para>
                    Record location of every line. Don't record locations of particular words or characters.
                </para>
                <para>
                    This is the default for OCRopus 0.2.
                    The option is ineffective with stand-alone Tesseract 2.0.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><option>-t words</option></term>
            <term><option>--details=words</option></term>
            <listitem>
                <para>
                    Record location of every line and every word. Don't record locations of particular characters.
                </para>
                <para>
                    This is the default for most OCR engines.
                </para>
                <para>
                    This option is ineffective with OCRopus 0.2 and stand-alone Tesseract 2.0.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><option>-t chars</option></term>
            <term><option>--details=chars</option></term>
            <listitem>
                <para>
                    Record location of every line, every word and every character.
                </para>
                <para>
                    This option is ineffective with OCRopus 0.2 and stand-alone Tesseract 2.0.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><option>--word-segmentation=simple</option></term>
            <listitem>
                <para>
                    Consider each non-empty sequence of non-whitespace characters a single word.
                </para>
                <para>
                    This is the default, despite being linguistically incorrect.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><option>--word-segmentation=uax29</option></term>
            <listitem>
                <para>
                    Use the <ulink url='http://unicode.org/reports/tr29/'>Unicode Text Segmentation</ulink> algorithm
                    to break lines into words.
                </para>
                <para>
                    This option breaks assumptions of some DjVu tools that words are separated by spaces,
                    and therefore it is not recommended.
                </para>
            </listitem>
        </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Other options</title>
        <variablelist>
        <varlistentry>
            <term><option>-l</option></term>
            <term><option>--language=<replaceable>language-id</replaceable></option></term>
            <listitem>
                <para>
                    Set recognition language. <replaceable>language-id</replaceable> is typically an ISO 639-2/T
                    three-letter code.
                </para>
                <para>
                    Tesseract ≥ 3.02 allows specifying multiple languages separated by
                    <quote><literal>+</literal></quote> characters.
                </para>
                <para>
                    For OCRopus, the default is <quote><literal>eng</literal></quote> (English), unless the
                    <varname>tesslanguage</varname> environment variable is set.
                    For other OCR engines, the default is always <quote><literal>eng</literal></quote>.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><option>--list-languages</option></term>
            <listitem>
                <para>
                    Print list of available languages for the currently selected OCR engine.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><option>--render=mask</option></term>
            <listitem>
                <para>
                    Render only masks of page images.
                </para>
                <para>
                    This is the default.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><option>--render=foreground</option></term>
            <listitem>
                <para>
                    Render only foreground layers of page images.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><option>--render=all</option></term>
            <listitem>
                <para>
                    Render all layers of page images.
                </para>
                <para>
                    This option is necessary to OCR DjVu files with invalid foreground/background separation.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><option>-p</option></term>
            <term><option>--pages=<replaceable>page-range</replaceable></option></term>
            <listitem>
                <para>
                    Specifies pages to process. <replaceable>page-range</replaceable> is a comma-separated list of
                    sub-ranges. Each sub-range is either a single page (e.g. <literal>17</literal>) or a contiguous
                    range of pages (e.g. <literal>37-42</literal>). Pages are numbered from 1.
                </para>
                <para>
                    The default is to process all pages.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><option>-j</option></term>
            <term><option>--jobs=<replaceable>n</replaceable></option></term>
            <listitem>
                <para>
                    Start up to <replaceable>n</replaceable> OCR processes.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><option>--version</option></term>
            <listitem>
                <para>Output version information and exit.</para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><option>-h</option></term>
            <term><option>--help</option></term>
            <listitem>
                <para>Display help and exit.</para>
            </listitem>
        </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Advanced options</title>
        <variablelist>
        <varlistentry>
            <term><option>-D</option></term>
            <term><option>--debug</option></term>
            <listitem>
                <para>To ease debugging, don't delete intermediate files.</para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><option>-X <replaceable>key</replaceable>=<replaceable>value</replaceable></option></term>
            <listitem>
                <para>
                    This option allows controlling some details of how &p; operates.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><option>--on-error=abort</option></term>
            <listitem>
                <para>
                    Stop program execution when an exceptional situation (e.g., malformed output from the OCR engine,
                    internal &p; error, etc.) occurs.
                </para>
                <para>
                    This is the default.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><option>--on-error=resume</option></term>
            <listitem>
                <para>
                    Attempt to recover from exceptional situations.
                </para>
                <para>
                    This option is strongly discouraged.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><option>--html5</option></term>
            <listitem>
                <para>
                    Use a <ulink url='https://html.spec.whatwg.org/multipage/syntax.html#parsing'>HTML5
                    parser</ulink>, which is more robust but slower than the default parser.
                </para>
            </listitem>
        </varlistentry>
        </variablelist>
    </refsection>
</refsection>

<refsection>
    <title>Exit status</title>
    <para>
        One of the following exit values can be returned by &p;:
        <variablelist>
        <varlistentry>
            <term>0</term>
            <listitem><para>The program finished successfully.</para></listitem>
        </varlistentry>
        <varlistentry>
            <term>1</term>
            <listitem><para>A fatal error occurred.</para></listitem>
        </varlistentry>
        <varlistentry>
            <term>2</term>
            <listitem><para>The program recovered from an error (<option>--on-error=resume</option>).</para></listitem>
        </varlistentry>
        </variablelist>
    </para>
</refsection>

<refsection>
    <title>Environment</title>
    <para>
        The following environment variables affects &p;:
        <variablelist>
        <varlistentry>
            <term><varname>tesslanguage</varname></term>
            <listitem>
                <para>
                    Recognition language for Tesseract.
                </para>
                <para>
                    (Use this variable is deprecated in favor of the <option>--language</option> option.)
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><varname>TMPDIR</varname></term>
            <!-- As per IEEE Std 1003.1, 2004 Edition, “8.3 Other Environment Variables”:
            http://www.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap08.html#tag_08_03
            -->
            <listitem>
                <para>
                    &p; makes heavy use of temporary files. It will store them in a directory
                    specified by this variable. The default is <filename>/tmp</filename>.
                </para>
            </listitem>
        </varlistentry>
        </variablelist>
    </para>
</refsection>

<refsection>
    <title>Bugs</title>
    <refsection>
        <title>Known bugs</title>
        <para>
            Tesseract 3.00 is affected by a bug <footnote><para><ulink
            url='https://code.google.com/p/tesseract-ocr/issues/detail?id=376'/></para></footnote> making it produce invalid
            hOCR output in certain circumstances. &p; does not try recover form this fault (which couldn't be done reliably
            anyway) unless you pass the <option>-X fix-html=1</option> option.
        </para>
        <para>
            When using Tesseract ≥ 3.00, extracting bounding boxes of particular characters (which happens when either
            <option>--details=chars</option> or <option>--word-segmentation=uax29</option>) is inefficient.
            This is due to limitations of the Tesseract command-line interface.
        </para>
    </refsection>
    <refsection>
        <title>Reporting new bugs</title>
        <para>
            Please report bugs at:
            <ulink url='https://bitbucket.org/jwilk/ocrodjvu/issues'/>
        </para>
    </refsection>
</refsection>

<refsection>
    <title>See also</title>
    <para>
        <citerefentry>
            <refentrytitle>djvu</refentrytitle>
            <manvolnum>1</manvolnum>
        </citerefentry>,
        <citerefentry>
            <refentrytitle>djvu2hocr</refentrytitle>
            <manvolnum>1</manvolnum>
        </citerefentry>,
        <citerefentry>
            <refentrytitle>hocr2djvused</refentrytitle>
            <manvolnum>1</manvolnum>
        </citerefentry>,
    </para>
    <para>
        <citerefentry>
            <refentrytitle>ocroscript</refentrytitle>
            <manvolnum>1</manvolnum>
        </citerefentry>,
        <citerefentry>
            <refentrytitle>tesseract</refentrytitle>
            <manvolnum>1</manvolnum>
        </citerefentry>,
        <citerefentry>
            <refentrytitle>cuneiform</refentrytitle>
            <manvolnum>1</manvolnum>
        </citerefentry>,
        <citerefentry>
            <refentrytitle>ocrad</refentrytitle>
            <manvolnum>1</manvolnum>
        </citerefentry>,
        <citerefentry>
            <refentrytitle>gocr</refentrytitle>
            <manvolnum>1</manvolnum>
        </citerefentry>
    </para>
</refsection>

</refentry>

<!-- vim:set ts=4 sts=4 sw=4 tw=120 et: -->
