# xsnap.1.pod -- pod file for xsnap 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 - Take a snapshot of a region of the screen

=head1 SYNOPSIS

B<xsnap> [-display displayname] [-fn name] [-guiwidth size] [-bg bgcolor]
[-fg fgcolor] [-bd bordercolor] [-bw borderwidth] [-geometry geometry]
[-icongeometry icongeometry] [-region geometry] [-iconic] [-name
title] [-grab] [-nograb] [-jpg] [-png] [-pnm] [-ppm] [-xpm] [-xwd]
[-snap] [-gui] [-nogui] [-file name] [-stdout]

=head1 DESCRIPTION

The xsnap program allows one to take a snapshot of a specified region
of the screen. If xsnap is run without a region being specified, the
user is prompted to interactively drag one out with the mouse. In this
case, pressing button 1 will select one corner of the region, and an
opposite corner will be selected upon the release of button 1.
Pressing button 2 selects the whole window, while pressing button 3
cancels the selection. A special case is when a region of zero with
and height is selected with button 1. In that case, the selection is
the last subwin- dow (in the hierarchy of subwindows) which contains
the selected point. Once the region is selected, a window whose
contents are a copy of this region is created, and various actions can
be taken through key bind- ings (upper or lower case is irrelevant).

Pressing C<q> or C<Esc> in the xsnap window will exit the program, and
pressing '!' restarts a new instance. The captured region may also be
stored to a file for later use, by pressing 'j', 'g', 'n', 'p', 'x' or
'w', while key 'z' enables/disables compression.

Here 'j' stands for *.jpg format, 'g' for *.png format, 'n' for
*.pnm.gz (ascii PPM), 'p' for *.ppm.gz (raw PPM), 'x' for XPixmap for-
mat (*.xpm.gz) and 'w' for XWindow Dump format (*.xwd.gz). Except for
PNG which is already compressed, all other formats are automatically
gzip compressed since this saves a lot of disk space. However,
compres- sion is not performed if the image data are dumped to stdout
(-stdout option).

All other keys raise the dialog window if it is not yet open, and have
no effect otherwise.

This program is a strongly enhanced variant of the original xsnap
program by Clauss Strauch.

=head1 OPTIONS

=over 4

=item B<-bd COLOR>

Foreground color of dialog window. Defaults to black.

=item B<-bg COLOR>

background color of dialog window. Defaults to #EEEEE6 (light grey).

=item B<-bd COLOR>

Border color of snapshot window. Defaults to white.

=item B<-bw WIDTH>

Border width of snapshot window. Defaults to 2.

=item B<-display DISPLAY>

Specifies the display to use for both specifying and displaying the
region. See also environment variable DISPLAY.

=item B<-file NAME>

Store the output in the file NAME.<format>, where <format> is the
appropriate suffix derived from the selected format. Only the root
name of the file should thus be given. The file gets overwritten if it
already exists, so take care.

=item B<-fn FONT>

Specifies the font to use in the command GUI window.

=item B<-guiwidth NUMBER>

Specifies the width of the command GUI window.

=item B<-geometry GEOMETRY>

Geometry of snapshot window.

=item B<-grab>

Grab the server during specification of region.

=item B<-gui>

Open directly the GUI command window, without first selecting a
region. This can be done with the appropriate button, marked with an
exclamation sign.

=item B<-icongeometry GEOMETRY>

Geometry of icon.

=item B<-iconic>

If specified, snapshot window will start up in iconic state.

=item B<-jpg>

Store the image in JPG format.

=item B<-name TITLE>

Name of the window to be passed to window manager.

=item B<-nograb>

Do not grab the server during specification of region.

=item B<-nogui>

Without opening the gui window, select a region of screen by dragging
the mouse and dump it to a file (default file is
$HOME/snapXXXX.<format> if no root name has been specified). XXXX is a
number in the range 0000..9999 selected in such a way that the
resulting file does not exist yet (in the very unlikely situation that
all slots 0000..9999 have been exhausted, the last possible file
snap9999.<format> gets overwritten; if several instances of xsnap
are opened and XXXX is less than 9999, the resulting files will NOT
overwrite one another; if $HOME does not exist, $TMPDIR is used instead,
and if $TMPDIR does not exist, /tmp is used as a last resort, but this
should normally happen only in the rare cases where the user environment
is broken.)

=item B<-png>

Store the image in PNG format.

=item B<-pnm>

Store the image in PNM format (=ascii PPM), as a compressed *.pnm.gz
file (compression is not performed when outputting to stdout).

=item B<-ppm>

Store the image in PPM format (raw data), as a compressed *.ppm.gz
file (compression is not performed when outputting to stdout).

=item B<-region GEOMETRY>

The size and location on the screen of the region to be copied.

=item B<-snap>

Set the normal (default) way of operating xsnap, which is to first
select a region of screen by dragging the mouse, and then opening an X
window displayed the region captured. A GUI com- mand window can be
opened from there with a right button click.

=item B<-stdout>

Write the image data to stdout (in the specified format, uncompressed).

=item B<-xpm>

Store the pixmap in X PixMap Format, as a compressed *.xpm.gz file
(compression is not performed when outputting to stdout).

=item B<-xwd>

Store the pixmap in X window dump format, as a compressed *.xwd.gz
file (compression is not performed when outputting to stdout).

=back

=head1 BUGS

In PseudoColor mode, colormaps are supported only in case an entire
window is captured by clicking with the first or second buttons.
Incorrect behavior may result on displays that support windows of dif-
ferent depths, or when the window carries elements which have
different colormaps.

Since it creates a pixmap for each snapshot, it can chew up server
mem- ory very fast. In this perspective, it can be useful to use to
option C<-convert gzip> to compress the files on the fly. The
icongeometry option doesn't know about icon sizes.

=head1 ENVIRONMENT

Files are written under C<$HOME>. If this variable does not exist,
files are written in a temporary directory. The latter is set from
the value of the C<$TMPDIR> environment parameter if it exists, and 
otherwise defaults to the system wide directory P_tmpdir defined 
in stdio.h, usually C</tmp/>.

=head1 FILES

=over 4

=item snap0000.txt, snap0001.txt, ...

Output for the OCR reader program. See location in section ENVIRONMENT.

=item snapXXXX.<format>

See B<-nogui> option. See location in section ENVIRONMENT.

=back

=head1 SEE ALSO

convert(1)
cuneiform(1)
ocrad(1)
xsnap-ocr(1)

=head1 COPYRIGHT

  2000-2013 Jean-Pierre Demailly <jean-pierre.demailly@ujf-grenoble.fr>
  2000-2013 Grenoble University
  2000 Bill Janssen <janssen@parc.xerox.com>
  1990 Arnaud Le Hors <lehors@mirsa.inria.fr>
  1989 Clauss Strauch <cbs@cad.cs.cmu.edu>

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 (colormap support, new image formats PNG, PNM, PPM,
conversion of image formats on the fly, save procedure, GUI dialog;
obsolete atk format removed):

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

3rd version (region option fixed, XPM option added):

    Arnaud Le Hors
    Bull Research France

2nd version (xwd, atk, region options added):

    Bill Janssen
    Xerox Palo Alto Research Center

Original version: Clauss Strauch

    Engineering Design Research Center
    Carnegie Mellon University

Manual page enhancements:

    Jari Aalto <jari.aalto@cante.net>

=cut
