=encoding utf8

=head1 NAME

braillegraph - a simple histogram tool that produces text output

=head1 SYNOPSIS

B<braillegraph> E<lt>I<data series>

B<psql> B<-At> B<-c> 'select ...' B<|>B<braillegraph>

=head1 DESCRIPTION

B<braillegraph> takes a single data series and plots them abusing the
Braille range (U+2800..U+28FF).  It is able to display two values per a
horizontal character, thus a plain text mail can hold an X range up to ~150
data points.  The vertical resolution is 4/character, thus a reasonable Y
range is up to 80ish.

By default, no scaling is done at all — one dot is exactly one data point
horizontally, a value of 1 vertically.

Input is given as one non-negative integer per line.

=head1 EXAMPLE

 psql bugs -A -t -c "
 select
     count(case when arch='amd64 (x86_64)' then 1 else null end)
     *80/count(*)
 from (select arch, date_trunc('month', timestamp) as month from si) m
 group by month
 order by month
 "|braillegraph

=head1 OPTIONS

=over

=item B<-h>, B<--horizontal>

Horizontal layout.  The Y axis is left-to-right, X axis is top-to-bottom.

=item B<-m>, B<--max> I<number>

Force the target range of the data.  Normally, the histogram will be
auto-sized based on the largest value in the input; this option sets the max
to a fixed value.  It will result either in empty space on the graph or in
values over the limit being hard-capped.

You typically want this option when comparing multiple histograms, or when
continuously updating the display.

=item B<-y>, B<--y-scale> I<number>

Scale the data so that the graph takes a given size (measured in dots)
instead of varying on the data given.  The size in characters is E<frac14>
the dot size on a vertical graph, E<frac12> on horizontal.

=back

=head1 CAVEATS

Versions of FreeFont older than end of 2016 make any Braille glyphs (both
for legitimate uses and for B<brailleimg>) totally unreadable at pixel sizes
commonly found in computer displays — ie, anything but HiDPI and/or very
large text sizes.  Alas, this font is commonly configured as primary
fallback in default setups shipped by distributions.

=head1 AUTHOR

Adam Borowski <kilobyte@angband.pl>
