<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [

<!-- Process this file with docbook-to-man to generate an nroff manual
     page: `docbook-to-man manpage.sgml > manpage.1'.  You may view
     the manual page with: `docbook-to-man manpage.sgml | nroff -man |
     less'.  A typical entry in a Makefile or Makefile.am is:

manpage.1: manpage.sgml
	docbook-to-man $< > $@

    
	The docbook-to-man binary is found in the docbook-to-man package.
	Please remember that if you create the nroff version in one of the
	debian/rules file targets (such as build), you will need to include
	docbook-to-man in your Build-Depends control field.

  -->

  <!-- Fill in your name for FIRSTNAME and SURNAME. -->
  <!ENTITY dhfirstname "<firstname>Gopal</firstname>">
  <!ENTITY dhsurname   "<surname>Narayanan</surname>">
  <!-- Please adjust the date whenever revising the manpage. -->
  <!ENTITY dhdate      "<date>Jan 30, 2005</date>">
  <!-- SECTION should be 1-8, maybe w/ subsection other parameters are
       allowed: see man(7), man(1). -->
  <!ENTITY dhsection   "<manvolnum>1</manvolnum>">
  <!ENTITY dhemail     "<email>(gopal@debian.org)</email>">
  <!ENTITY dhusername  "Gopal Narayanan">
  <!ENTITY dhucpackage "<refentrytitle>quickplot</refentrytitle>">
  <!ENTITY dhpackage   "quickplot">

  <!ENTITY debian      "<productname>Debian</productname>">
  <!ENTITY gnu         "<acronym>GNU</acronym>">
  <!ENTITY gpl         "&gnu; <acronym>GPL</acronym>">
]>

<refentry>
  <refentryinfo>
    <address>
      &dhemail;
    </address>
    <author>
      &dhfirstname;
      &dhsurname;
    </author>
    <copyright>
      <year>2003</year>
      <holder>&dhusername;</holder>
    </copyright>
    &dhdate;
  </refentryinfo>
  <refmeta>
    &dhucpackage;

    &dhsection;
  </refmeta>
  <refnamediv>
    <refname>&dhpackage;</refname>

    <refpurpose>fast interactive 2D plotter and data viewer</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <cmdsynopsis>
      <command>&dhpackage;</command>

      <arg><option>OPTIONS</option></arg>
      <arg><option>file1</option></arg>
      <arg><option>OPTIONS</option></arg>
      <arg><option>file2</option></arg>
    </cmdsynopsis>
  </refsynopsisdiv>
  <refsect1>
    <title>DESCRIPTION</title>

    <para><command>&dhpackage;</command> is more like an interactive
      data browser than an interactive picture editor. The difference
      between this 2D plotter and most 2D plotters is that the primary
      purpose of Quickplot is to help you quickly interact with your
      data.  Of secondary importance is to make a pretty static
      picture of your data.  Features that distinguish Quickplot
      include: one click zooming, any number of plots with different
      scales displayed at one time, value picking for any number of
      plots with different scales displayed at one time, and reading
      data from standard input.  These features become indispensable
      when you're looking at data sets with 10,000 to 1,000,000 and
      more data points.  You can't look at a 2D plot with 100,000
      points unless you can quickly zoom.  If you need to look at
      hundreds of files each with 100,000 points, the command line
      options in Quickplot may save your sanity.</para>

    <para>This manual page was written for the &debian; distribution
      because the original program does not have a manual
      page. Instead, it comes with documentation in html format that
      can obtained by running the program and pulling down the Help Menu.
      The html files can be found at /usr/share/doc/quickplot/html/
</para>

  </refsect1>
  <refsect1>
    <title>OPTIONS</title>

    <para>These programs follow the usual &gnu; command line syntax,
      with long options starting with two dashes (`-').  A summary of
      options is included below.  </para>

    <variablelist>
      <varlistentry>
        <term><option>-a</option>
          <option>--about</option>
        </term>
        <listitem>
          <para>Display some information about Quickplot</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-c RGB</option>
          <option>--canvas-color RGB</option>
        </term>
        <listitem>
          <para>start quickplot with the graph background (canvas) color RGB. Examples: --canvas-color #FF0000 or --canvas-color "red" would make it red</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-d</option>
          <option>--different-scales</option>
        </term>
        <listitem>
          <para> load plots on the same graph with different
          scales. By default Quickplot will load plots on the same
          graph with the same scale if the span of x,y values in all
          the plots are within an order of magnitude of each other </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-geometry GEOMETRY</option>
          <option>--geometry GEOMETRY</option>
        </term>
        <listitem>
          <para> create the initial window with the given geometry
          GEOMETRY, see man page X(1) for the GEOMETRY
          format. Example: quickplot --geometry=1000x300-0+30 </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-C RGB</option>
          <option>--grid-color RGB</option>
        </term>
        <listitem>
          <para>     RGB may be in one of these formats: 
	    <itemizedlist>
	      <listitem>
		<para> #RGB (each of R, G and B is a single hex digit) </para>
	      </listitem>
	      <listitem> 
		<para> #RRGGBB </para>
	      </listitem>
	      <listitem> 
		<para> #RRRGGGBBB </para>
	      </listitem>
	      <listitem> 
		<para> #RRRRGGGGBBBB </para>
	      </listitem>
	      <listitem>
		<para> A name from the X color database, which may be
		in /usr/X11R6/lib/X11/rgb.txt. Example colors are
		"steelblue" and "gainsboro". </para>
	      </listitem>
	  </itemizedlist>
	    </para>
	  </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-g SIZE</option>
          <option>--grid-line-width SIZE</option>
        </term>
        <listitem>      
	  <para> start quickplot using plot grid width SIZE in
	  pixels</para>
	</listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-h</option>
          <option>--help</option>
        </term>
        <listitem>
          <para>Show summary of options.</para>
        </listitem>
      </varlistentry>

      <varlistentry> 
	<term><option>-b CHAR</option>
	  <option>--label-separator CHAR</option>
	</term>
	<listitem>
	  <para> when reading labels from the last file in the argument
      list before this option flag use CHAR as the label (single
      character) separator. The default label separator is ' '
      (space). If this file is not an ASCII text file this will be
      ignored. See option: --labels or -L.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>-L</option>
	  <option>--labels</option>
	  </term>
	<listitem>
	  <para> read labels from the first line not skipped of the
	  last file in the augment list before this option flag. If
	  this file is not an ASCII text file this will be
	  ignored.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>-I SIZE</option>
	  <option>--line-width SIZE</option>
	  </term>
	<listitem>
	  <para> start quickplot using plot line width SIZE in
	  pixels</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>-l [L_OPTIONS]</option>
	  <option>--linear-field [L_OPTIONS]</option>
	</term>
	<listitem>
	  <para>make a field that is a uniformly changing linear
sequence of values, like for example time.  The number of values will
be gotten from the previous file's values loaded.  The field generated
will be added as the first field of the previous file. For sound files
this option is ignored.  </para>
<para><command>L_OPTIONS</command></para>
<para>The L_OPTIONS only have an effect after the --linear-field (or -l) option and they act on the field made from that argument.  The L_OPTIONS are:</para>
	  <itemizedlist>
	    <listitem>
	      <para>--start VALUE or -r VALUE   set the first value in
	      the sequence to VALUE.  The default first value will
	      be zero.</para>
	    </listitem>
	      <listitem>
	      <para>--step SIZE or -t SIZE   set the sequence step
	      size to SIZE.  The default is 1. </para>
	    </listitem>
	  </itemizedlist>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>-B</option>
	  <option>--no-buttons</option>
	  </term>
	<listitem>
	  <para>start quickplot with no button bar</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>--no-default-plots</option>
	  </term>
	<listitem>
	  <para>by default when no --plot or -p options are given
	  Quickplot will make some plots with the files loaded at
	  start up. This option will cause Quickplot not to make these
	  default plots.  When files are loaded using the GUI defaults
	  plot will not be made if this is set.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>-G</option>
	  <option>--no-grid</option>
	  </term>
	<listitem>
	  <para>start quickplot with out drawing graph grid lines,
	  by default, in the graphs</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>--no-gui</option>
	  </term>
	<listitem>
	  <para>start quickplot with out showing any of the standard
	  GUI's (graphical user interfaces). This is the same as uses
	  the options --no-buttons --no-menubar --no-statusbar and
	  --no-tabs.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>-i</option>
	  <option>--no-lines</option>
	  </term>
	<listitem>
	  <para>start quickplot to plot without drawing lines in the
	  graphs by default</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>-M</option>
	  <option>--no-menubar</option>
	</term>
	<listitem>
	  <para>start quickplot with no menubar</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>-N</option>
	  <option>--no-pipe</option>
	</term>
	<listitem>
	  <para>don't read data in from standard input</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>-o</option>
	  <option>--no-points</option>
	</term>
	<listitem>
	  <para>start quickplot to plot without drawing points in the
	    graphs by default</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>--no-statusbar</option>
	  </term>
	<listitem>
	  <para>start Quickplot with no status bar displayed. The
Quickplot status bar is a thin widget at the bottom of the main
Quickplot window which displays pointer x, y graph values and mode
information.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>--no-tabs</option>
	  </term>
	<listitem>
	  <para>start Quickplot with no graph tabs displayed. Quickplot uses a notebook like widget to let you select and
view multiple graphs.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>-n NUM</option>
	  <option>--number-of-plots NUM</option>
	</term>
	  <listitem>
	  <para>set the possible initial number of plots to NUM.  The
default possible initial number of plots is 12.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>-P</option>
	  <option>--pipe</option>
	  </term>
	<listitem>
	  <para>read in data from standard input.  By default
Quickplot looks for data from standard input and stops looking if no
data is found in some short amount of time.  This option will cause
Quickplot to wait for standard input indefinitely.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>-p LIST</option>
	  <option>--plot LIST</option>
	</term>
	<listitem>
	  <para>plot the following list of fields, LIST, at startup.
	    example: --plot "0 1 3 4" will plot field 1 VS field 0 and
	    field 4 VS field 3.  DataFields are numbered, starting at
	    0, in the order that they are read in from a file or
	    created, as in the case of option --linear-field.  A
	    separate Graph Tab will be created for each --plot (or -p)
	    option given.</para>
	</listitem>
      </varlistentry>
      
      <varlistentry>
	<term><option>-O SIZE</option> <option>--point-size
	  SIZE</option></term>
	<listitem> 
	  <para>start quickplot using plot point size SIZE in pixels</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>--print-about</option></term>
	<listitem><para>prints the About HTML document to standard output and then exits</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>--print-help</option></term>
	<listitem>
	  <para>prints the Help HTML document to standard output and then exits</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>-s</option>
	  <option>--same-scale</option></term>
	<listitem>
	  <para>plot all start-up plots on the same scale</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>--silent</option>
	</term>
	<listitem>
	  <para>don't spew even on error. The --silent option will
	  override the effect of the --verbose option.</para>
	</listitem>
      </varlistentry>
      
      <varlistentry>
	<term><option>-S NUM</option>
	  <option>--skip-lines NUM</option>
	  </term>
	<listitem>
	  <para>skip the first NUM lines in the previous file
	  read. The previous file in the argument list should be an
	  ASCII text file.</para>
	</listitem>
      </varlistentry>
      
      <varlistentry>
        <term><option>-v</option>
          <option>--verbose</option>
        </term>
        <listitem>
          <para>spew more to standard output</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-V</option>
          <option>--version</option>
        </term>
        <listitem>
          <para>Show version of program.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
	<term><option>--with-libsndfile</option>
	</term>
	<listitem>
	  <para>if quickplot is linked with the libsndfile --library,
print the version of the libsndfile library that quickplot is
linked with, and exit returning status 0 if quickplot is linked
with the libsndfile library and 1 if quickplot is not linked with
the libsndfile library</para>
	</listitem>
      </varlistentry>

    </variablelist>
  </refsect1>
  <refsect1>
    <title>KEYBINDINGS</title>

    <para>Quickplot has GUIs for all of the following immutable keyboard short-cuts:</para>
    <para>
    <itemizedlist>
      <listitem>
        <para><command>a</command>   show information about Quickplot
        using a web browser</para>
      </listitem>
      <listitem>
	<para><command>b</command>   toggles the visibility of the button bar</para>
      </listitem>
      <listitem>
	<para><command>c</command>   copies the current focused main window frame</para>
      </listitem>
      <listitem>
	<para><command>d</command>   delete the main window. This will not close the last main window.</para>
      </listitem>
      <listitem>
	<para><command>f</command>   makes a new main window frame</para>
      </listitem>
      <listitem>
	<para><command>g</command>   show/hide the graph configuration widget</para>
      </listitem>
      <listitem>
	<para><command>h</command>   show help using a web
	browser</para>
      </listitem>
      <listitem>
	<para><command>i</command>   save a PNG image of the graph</para>
      </listitem>
      <listitem>
	<para><command>m</command>   show/hide the menu bar</para>
      </listitem>
      <listitem>
	<para><command>n</command>   make a new graph</para>
      </listitem>
      <listitem>
	<para><command>o</command>   open a data file</para>
      </listitem>
      <listitem>
	<para><command>p</command>   show/hide the plot lister widget</para>
      </listitem>
      <listitem>
	<para><command>q</command>   quit</para>
      </listitem>
      <listitem>
	<para><command>s</command>   toggles the visibility of the
	status bar</para>
      </listitem>
      <listitem>
	<para><command>t</command>   toggles the visibility of the
	graph tabs</para>
      </listitem>
      <listitem>
	<para><command>esc</command>   close the current focused window. This will not close the last main window.</para>
      </listitem>
    </itemizedlist>
    </para>

  </refsect1>
  <refsect1>
    <title>AUTHOR</title>

    <para><command>Quickplot</command> is written by Lance
    Arsenault. </para>

    <para>This manual page was written by &dhusername; &dhemail; for
      the &debian; system (but may be used by others).  Permission is
      granted to copy, distribute and/or modify this document under
      the terms of the &gnu; General Public License, Version 2 any 
	  later version published by the Free Software Foundation.
    </para>
	<para>
	  On Debian systems, the complete text of the GNU General Public
	  License can be found in /usr/share/common-licenses/GPL.
	</para>

  </refsect1>
</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:2
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:nil
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->