# xsnap-ocr.1.pod -- pod file for xsnap-ocr man page
#
#   Copyright information
#
#	Copyright (C) 2013 Jean-Pierre Demailly <jean-pierre.demailly@ujf-grenoble.fr>
#	Copyright (C) 2008-2013 Jari Aalto
#
#   License
#
#       This file is free software; you can redistribute it and/or modify
#       it under the terms of the GNU General Public License as published by
#       the Free Software Foundation; either version 3 of the License, or
#       (at your option) any later version.
#
#       This program is distributed in the hope that it will be useful,
#       but WITHOUT ANY WARRANTY; without even the implied warranty of
#       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
#       GNU General Public License for more details at
#       <http://www.gnu.org/licenses/>.
#
#   Description
#
#       To learn what TOP LEVEL sections to use in manual pages,
#       see POSIX/Susv standard and "Utility Description Defaults" at
#       http://www.opengroup.org/onlinepubs/009695399/utilities/xcu_chap01.html#tag_01_11
#
#       This is manual page in Perl POD format. Read more at
#       http://perldoc.perl.org/perlpod.html or run command:
#
#           perldoc perlpod | less
#
#       To check the syntax:
#
#           podchecker *.pod
#
#       Create manual page with command:
#
#           pod2man PAGE.N.pod > PAGE.N

=pod

=head1 NAME

xsnap-ocr - Bash script used to manage the OCR capabilities of xsnap

=head1 SYNOPSIS

B<xsnap-ocr> <filename> <0/1>

=head1 DESCRIPTION

B<xsnap-ocr> is a Bash script used to manage the OCR capabilities of
xsnap. The xsnap main program can optionally start an OCR process on
captured screenshots or image portions by pressing the <t/T> shortcut
commands or respective button.

Once the OCR has been initiated, the image is processed by the
B<xsnap-ocr> script which takes two arguments. The first one is the
name of the image file which is always expected to be sent as a PPM
file by xsnap. The second parameter is a boolean value 0 or 1
controlling whether the resulting text file will be compressed
(*.txt.gz) or left as is (*.txt).

B<xsnap-ocr> needs an external OCR engine whose parameters are in
their default form: e.g. selection of the language dictionary if the
OCR engine provides such dictionaries. By default, follofing OCR
engines are searched in this order:

    tesseract
    ocrad
    cuneiform

Both the B<tesseract> and B<cuneiform> can use language dictionaries.
The selectedt language is set by B<xsnap-ocr> according to the value
of the B<LANG> environment variable.

After the OCR process, the text file is opened for viewing. By
default, the viewers searched in order are:

    xless
    sensible-editor
    emacs
    nano
    vi

It is possible to customize B<xsnap-ocr> to use other OCR engines for
other language settings and for other editors. The only requirement in
the the main B<xsnap> program is that the first argument sent to
B<xsnap-ocr> is the name of the PPM file to process and the second
argument is a boolean value to control the compression. Some OCR
engines may require the PPM file to be plain black and white (no gray
levels). In those cases the PPM file then has to be preprocessed with
an image filter such as B<convert> from the I<imagemagick> or
I<graphicsmagick> packages.

=head1 ENVIRONMENT

See the OCR engines' manual pages for environment variables for
controlling the use e.g. for the choice of languages. For example
B<cuneiform> uses I<$ENVLANG>.

=head1 FILES

=over 4

=item $HOME/snap0000.txt, $HOME/snap0001.txt ...

Output for the OCR reader program.

=back

=head1 SEE ALSO

convert(1)
cuneiform(1)
ocrad(1)
xsnap(1)

=head1 COPYRIGHT

Program is released under license GNU GPL version 3 or (at your
option) any later version. For more information about license, visit
<http://www.gnu.org/copyleft/gpl.html>.

=head1 AUTHORS

Millenium version:

    Jean-Pierre Demailly <jean-pierre.demailly@ujf-grenoble.fr>
    Grenoble University

Manual page enhancements:

    Jari Aalto <jari.aalto@cante.net>

=cut
