#   Copyright
#
#      Copyright (C) 2009-2010 Jari Aalto
#
#   License
#
#       This program 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 2 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.
#
#       You should have received a copy of the GNU General Public License
#       along with this program. If not, see <http://www.gnu.org/licenses/>.
#
#   Description
#
#       To learn what TOP LEVEL section to use in manual pages,
#       see POSIX/Susv standard and "tility 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

dbar - ASCII progresbar

=head1 SYNOPSIS

  echo <percentage> | dbar [options] <indicator text>

=head1 DESCRIPTION

dbar lets you define static 0% and 100% marks or you can define these
marks dynamically at runtime.  Static and dynamic marks can be mixed,
in this case the value specified at runtime will have a higher priority.

You can specify ranges of numbers, negative, positive or ranges with a
negative min value and positive max value.

All numbers are treated as double precision floating point, i.e. the
input is NOT limited to integers.

=head1 OPTIONS

=over 4

=item B<-l>

Label to be prepended to the bar (default: "" ).

=item B<-nonl>

no new line, don't put '\n' at the end of the bar (default: do print
"\n")

=item B<-max>

Value to be considered 100% (default: 100).

=item B<-min>

Value to be considered 0% (default: 0).

=item B<-s>

Symbol represeting the percentage value in the meter (default: "=").

=item B<-w>

Number of charcaters to be considered 100% in the meter (default: 25)

=back

=head1 EXAMPLES

Static 100% mark or single value input:

    echo 25 | dbar -max 100 -l text

    Output: text  25% [======                   ]

If your 100% mark changes dynamically or 2-values input:

    echo "50 150" | dbar
          |   |
          |   |__ max value
          |
          |__ value to display

    Output: 33% [========                 ]

If your value range is not between [0, maxval] or 3-values input:

    echo "50 -25 150" | dbar
          |   |  |
          |   |  |__ max value 100% mark
          |   |
          |   |_____ min value 0% mark
          |
          |________ value to display

    Output: 43% [===========              ]

Multiple runs:

    for i in 2 20 50 75 80; do echo $i; sleep 1; done | dbar | dzen2

    Output: Find out yourself.

=head1 ENVIRONMENT

None.

=head1 FILES

None.

=head1 SEE ALSO

dzen2(1)

=head1 AUTHORS

Program was written by Robert Manea <rob.manea@gmail.com>.

This manual page was written by Jari Aalto <jari.aalto@cante.net> for
the Debian GNU system (but may be used by others). Released under
license GNU GPL version 2 or (at your option) any later version. For
more information about license, visit
<http://www.gnu.org/copyleft/gpl.html>.

=cut
