hovacui.1

.TH hovacui 1 "March 30, 2018"

.
.
.
.SH NAME
hovacui - pdf viewer with autozoom to text for X11 and the Linux framebuffer

.
.
.
.SH SYNOPSIS
\fBhovacui\fP
[\fIoptions\fP]
\fIfile.pdf\fP

.
.
.
.SH DESCRIPTION

Viewer for pdf files in X11 and the Linux framebuffer based on poppler,
with autozooming to the blocks of text in the page.

The other pdf viewers require the user to set the zoom explicitly and then to
move the page on the screen via scrollbars or cursor keys. The only automatic
zoom modes available are those fitting the page width or height (or both) to
the screen's.

The \fBhovacui\fP pdf viewer automatically zooms to the blocks of text in the
page. The user only needs to scroll down to continue reading.

This is handy on small screens, especially for documents with small letters.
White margins are not shown and the text is zoomed enough to fit the width of
the screen. Contrary to normal pdf viewer, it is not the page that fits the
width the screen, only the text in it. This means that the letters are larger
and therefore more readable.

Moving through the text for reading is much improved for two-column documents,
or document with multiple columns. A regular pdf viewer requires the user to
first zoom enough to make the letters readable, and then to move across the
page following the text:

.nf
        +-------+     +-------+
        |    <-----   |       |
        |   |   |   ----->    |
        |   |   |  ^  |   |   |
        |   |   |  |  |   |   |
        |   |   |  |  |   |   |
        |   |   |  |  |   |   |
        |   |   |  |  |   |   |
        |   V   |  |  |   |   |
        |    ----->   |   V   |
        +-------+     +-------+
.fi

This is not necessary in \fBhovacui\fP. The screen automatically starts showing
the top of the first column:

.nf
       +---------+
       |+-------+|    +-------+
       ||       ||    |       |
       ||       ||    |       |
       ||       ||    |       |
       +---------+    |       |
        |       |     |       |
        |       |     |       |
        |       |     |       |
        |       |     |       |
        |       |     |       |
        +-------+     +-------+
.fi

The cursor down key moves the screen down the text:

.nf
        +-------+     +-------+
        |       |     |       |
        |       |     |       |
       +---------+    |       |
       ||       ||    |       |
       ||       ||    |       |
       ||       ||    |       |
       ||       ||    |       |
       +---------+    |       |
        |       |     |       |
        +-------+     +-------+
.fi

This looks like moving down in the page like in a regular pdf viewer, but is
not. The difference shows when reaching the end of the column:

.nf
        +-------+     +-------+
        |       |     |       |
        |       |     |       |
        |       |     |       |
        |       |     |       |
        |       |     |       |
       +---------+    |       |
       ||       ||    |       |
       ||       ||    |       |
       ||       ||    |       |
       |+-------+|    +-------+
       +---------+
.fi

The next cursor down keystroke moves to the \fBnext part of text\fP, wherever
it is. In this case, a single keystroke moves to the top of the second column:

.nf
                     +---------+
        +-------+    |+-------+|
        |       |    ||       ||
        |       |    ||       ||
        |       |    ||       ||
        |       |    +---------+
        |       |     |       |
        |       |     |       |
        |       |     |       |
        |       |     |       |
        |       |     |       |
        +-------+     +-------+
.fi

The user needs not to move around in the page or even remember where the text
goes. A single cursor down keystroke is enough to continue reading, regardless
of whether the next part of the text is below, in the next column or in the
next page.

The cursor up key does the same in the opposite direction.

.
.
.
.SH MODE OF OPERATION

Before displaying a page, \fBhovacui\fP locates its blocks of text. It then
displays its first block with a blue border, zoomed enough to fill the width of
the screen. If the block is taller than the screen at this zoom, the cursor
down key scrolls it up. When the bottom of the block is visible, the next
cursor down keystroke makes the viewer switch to the next block.

This mode of operation is affected by various parameters, which can be
configured by keystrokes, from the menu (key \fI'm'\fP), via command line
options or the configuration file \fI$HOME/.config/hovacui/hovacui.conf\fP
or \fI/etc/hovacui.conf\fP.

.SS View mode

Normally, \fBhovacui\fP splits the page into its blocks of text, and displays
them one at time.

Instead of the blocks of text, the area of the page that is displayed may be
the whole bounding box of the page (the smallest rectangle enclosing all text
in the page). This viewing mode is obtained by the keystroke \fI'v'\fP, by the
\fI'view mode'\fP entry in the menu, by the command line option \fI-v
boundingbox\fP and by the configuration file line \fImode boundingbox\fP.

It is equivalent to the page being a single block of text that is as large as
the bounding box. When \fBhovacui\fP fails to correctly locate the blocks of
text or their order, switching to this mode allows for a more conventional view
of the page. Still, the white border of the page is suppressed, making the text
larger than the "fit to width" mode.

The default is that \fBhovacui\fP chooses between these two reading modes (by
blocks of text and by the boundingbox) depending on whether the page looks
multiple-column or not. This is the mode \fIauto\fP. Reading by blocks of text
can be forced by the keystroke \fI'v'\fP, the \fI'view mode'\fP entry in the
menu, by the command line option \fI-v textarea\fP and by the configuration
file line \fImode textarea\fP.

Fitting the whole page to the width of the screen is another mode of operation,
obtained by the keystroke \fI'v'\fP, by the menu, by the command line option
\fI-v page\fP and by the configuration file line \fImode page\fP.

.SS Fit direction

Normally, \fBhovacui\fP fits the width of the text to the width of the screen.
This achieves the largest possible zoom not requiring the user to move right or
left for reading a single line of text.

If required, it fits the height instead: by the \fI'f'\fP key, the \fIfit
direction\fP entry in the menu, the \fI-f vertical\fP command line option and
the \fIfit vertical\fP line in the configuration file.

Zooming the text so that it is all in the screen is also possible: pressing
\fI'f'\fP again or using the \fIboth\fP fit direction. This allows for example
to view the whole text in the page at once, or the entire page, by also
selecting the boundingbox or page mode (previous section).

Also possible is the fitting direction "none", which allows arbitrary zooming
and moving in the page. This is mostly a hack to allow zooming more than
normally possible, and some things do not work: moving to the next or previous
search match may skip some matches unless \fInavigatematches\fP is in the
configuration file; only PageUp and PageDown switch page.

.SS Minimal width

Fitting the width of the text to the width of the screen produces the largest
possible zoom while keeping the lines of text wholly in the page. However, when
the block of text is very narrow, the resulting zoom may be too large.

For example, line numbers are usually separated from the text, and therefore
each makes its own block of text. A page number like "12" would be rendered so
large that its width is made the same of the screen, with the result that its
bottom being cut out of the screen.

The minimal width parameter prevents this from happening. It is the width of
the most narrow block of text that is fit to the width of the screen. Blocks of
text that are narrower than this are still zoomed, but only as if they were as
wide as the minimal width.

In short: the minimal width prevents narrow blocks of text to be zoomed too
much.

It can be set by the \fI'w'\fP keystroke, by the menu, by the \fI'-w'\fP
command line option and by the \fIminwidth\fP configuration file line. The
default is half the width of the screen minus the margin. It can be changed on
the fly with keys 'z' and 'Z'. They work like 'zoom in' and 'zoom out' keys,
but the block of text is never zoomed more than the width of the screen.

.SS The text distance

Locating the block of text depends on a parameter: the minimal distance between
blocks of text. If two letters are closer than this, they are considered to be
part of the same block of text. Therefore, two blocks of text are never closer
than this distance.

The default is the average height of characters. This is reasonable for most
documents. On largely-spaced pages the blocks of text may be too many, even one
per paragraph. However, since such pages are usually single-column, if the
block of text are too many, it is usually better to switch to bounding box mode
(see above) rather than increasing the text distance.

Nevertheless, the text distance can be changed by the \fI't'\fP keystroke, from
the menu, by the \fI-t\fP command line option and by the \fIdistance\fP
configuration file line.

.SS Block order

Once the blocks of text are detected, they are sorted so that viewing can be
switched correctly from one to the next. Three methods are available:
\fIquick\fP, \fItwostep\fP and \fIchar\fP.

The first two are based on sorting blocks vertically if they overlap
horizontally, otherwise they are ordered horizontally. This guarantees a
reasonable ordering on both single-column and multiple-column documents. The
\fIquick\fP algorithm is approximated, the \fItwostep\fP is exact but less
efficient.

The \fIchar \fP algorithm is based on the order of the characters of the blocks
in the page. The block that contains the first character is the first; the
block that contains the first character not in the first block is the second,
and so on.

The default is the \fItwostep\fP method, but can be changed by the \fI'o'\fP
keystroke, from the menu, by the \fI-o\fP command line option and the
\fIorder\fP configuration file line.

.
.
.
.SH KEYS

The cursor up and cursor down keys work as expected: they move up and down the
screen. However, when the bottom of the current block of text (bordered in
blue) is already visible, the cursor down key moves to the next block. The same
for the cursor up key.

The same applies to the cursor left and right keys. This implies that in
horizontal fit mode (the default), since the edges are always visible, the
cursor right key always moves to the next block of text and the cursor left key
to the previous. The converse happens in vertical fit mode.

The page up and page down keys move to the previous and next page. The home key
moves to the upper left corner of the first textbox in the page, the end key to
the lower right corner of the last.

.TP
.B
h
display a summary of the keys
.TP
.B
m
enter the main menu
.TP
.B
v
change view mode: auto (default), textarea, boundingbox, page
(see \fIView mode\fP, above)
.TP
.B
f
change fit direction: none, horizontal, vertical, both
(see \fIFit direction\fP, above)
.TP
.B
g
go to a given page
.TP
.B
G
go to the page before moving by key 'g' or by searching
.TP
.B
/
search forward
(see \fISEARCHING\fP, below)
.TP
.B
?
search backward
(see \fISEARCHING\fP, below)
.TP
.B
n
go to the next match of the last search, if any
(see \fISEARCHING\fP, below)
.TP
.B
p
go to the previous match of the last search, if any
(see \fISEARCHING\fP, below)
.TP
.B
c
save the document or a range of pages to another file
.TP
.B
C
save the visible part of the current textbox to another file;
\fBpdffit\fP(\fI1\fP) enlarges that for printing,
possibly with \fI-w\fP and \fI-l\fP
.TP
.B
w
change the minimal width
(see \fIMinimal width\fP, above)
.TP
.B
z, Z
decrease or increase the minimal width
(see \fIMinimal width\fP, above);
similar to zooming in and out, but the current textbox is made larger than the
screen only in fit direction `none'
.TP
.B
t
change the text distance
(see \fIText distance\fP, above)
.TP
.B
o
change the block order
(see \fIBlock order\fP, above)
.TP
.B
r
reload the document (see also \fIDOCUMENT RELOAD\fP, below)
.TP
.B
a
draw to the rectangle specified by the \fIarea\fP config option;
press again to return to default mode
.TP
.B
b
show the current textbox and append it to the output file, which
by default is \fIhovacui-out.txt\fP but can be changed by \fI-z\fP
.TP
.B
B
same as \fIb\fP, but with the visible part of the current textbox
.TP
.B
s
show or hide the file name, the current view and fit mode and the current page
number
.TP
.B
x
draw a point that can be moved; 'enter' saves the point coordinates to the
output file
.TP
.B
d
draw a box that can be changed size and position; 'enter' saves the box
coordinates to the output file; 's' also saves the box content; 'S' saves the
box content in all pages
.TP
.B
e
execute the external script; see \fIEXTERNAL SCRIPT\fP, below
.TP
.B
q
quit the program

.
.
.
.SH OPTIONS

Not all parameters have their own command line option. Some can only be set in
the configuration file (see below) or by the \fI-c\fP option.

.TP
.BI -m " (auto|textarea|boundingbox|page)
view mode
(see \fIView mode\fP, above)
.TP
.BI -f " (none|horizontal|vertical|both)
fit direction
(see \fIFit direction\fP, above)
.TP
.BI -w " minwidth
minimal width
(see \fIMinimal width\fP, above)
.TP
.BI -t " distance
text distance
(see \fIText distance\fP, above)
.TP
.BI -o " (quick|twostep|char)
block order
(see \fIBlock order\fP, above)
.TP
.BI -p
presentation mode, suitable for an overhead presentation: page mode, fit both,
no margins, no page labels, no boxes, no initial tutorial, no menu and help
.TP
.BI -O " offset
page 1 is normally the first in the document, but not always; prefaces, tables
of contents, lists and other material may move it to a following page; this
makes page numbers misaligned; if for example page 1 is the eleventh in the
document, jumping to page 20 leads to page 9; passing \fI-O 9\fP realigns the
page numbers; pages preceding page 1 are numbered \fI0\fP, \fI-1\fP, \fI-2\fP,
etc.
.TP
.BI -F " first
a document that is a section of a longer texts may have its first page number
larger than 1; this creates a misalignment in the page numbers; for example, if
the first page of the document is page \fI120\fP then jumping to page \fI140\fP
leads to page \fI160\fP; passing \fI-F 120\fP realigns the page numbers
.TP
.BI -d " device
the device to use, by default \fI/dev/fb0\fP for the framebuffer and the
content of the environment variable \fIDISPLAY\fP for X11
.TP
.BI -s " aspect
the screen aspect; it can be specified as \fI16:9\fP or \fI4:3\fP, for example;
only necessary when pixels are non-square
.TP
.BI -e " fifo
receive commands from the given existing fifo;
see \fIEXTERNAL COMMANDS\fP, below
.TP
.BI -z " out
the output file name;
it is a text file that contains the boxes saved by key 'b' and
the logs if enabled by \fI-l\fP;
the default is \fIhovacui-out.txt\fP
.TP
.BI -c " configline
use \fIconfigline\fP as a configuration file line; the first \fI=\fP is
translated into a space; for example, \fI-c mode=page\fP is the same as \fImode
page\fP in the configuration file; this option can occur multiple times to give
multiple configuration lines
.TP
.BI -C " config
use the given configuration file instead of the default
.I $HOME/.config/hovacui/hovacui.conf
.TP
.BI -l " level
logging level:
\fI1\fP is for debugging the main loop to the output file;
\fI2\fP is for pausing each time a page is rendered

the string \fIscript\fP is for debugging the external script;
the script name, parameters, return value and output are saved to the output
file
.TP
.BI -x " suboption
use x11; the argument is either \fIdefault\fP or the x11 options \fIdisplay\fP
or \fIgeometry\fP; for example, the command line to run hovacui in a 400x300
window positioned at 200,100 on display :1 is:
.nf
\fIhovacui -x display=:1 -x geometry=400x300+200+100 file.pdf\fP
.fi
.TP
.BI -r " suboption
use the direct rendering infrastructure; the suboptions are:

.RS
.TP
.I default
show the pdf file on all video outputs at the maximal allowed size

.TP
.I connectors=conn,conn,conn
show the pdf file only on the specified video outputs; each \fIconn\fP may be
the id of a connector or its type, like \fIvga\fP, \fIhdmi\fP, \fIlvds\fP,
\fIsvideo\fP, etc.; the default is all connectors

if the suboption contains \fIlist\fP the selected connectors ids and types are
printed and the program terminates immediately

.TP
.I size=wxh
the width and height of the screen area to be used for showing the pdf file;
this is related to the resolution set for the video outputs but is not the same
because: a. only the default resolutions are used and b. different video output
may support different resolutions

\fIsize=id\fP or \fIsize=type\fP set the size as the best resolution of a
specific video output; the pdf file is displayed at full screen in maximal
resolution on that output; the others may display it with a black frame, or
only its central part or not at all

the form \fIsize=list\fP prints the available resolutions

.TP
.I exact
the width and height in the \fIsize=wxh\fP suboption are the minimal requested
size of a screen area to be used for showing the pdf file; the video modes that
best suit that size on all connectors are selected, and the area used for
showing the pdf file is computed from them maximizing the screen usage; this
may result in an area larger than requested; this option forces the use of the
requested size, possibly leaving a black frame around the pdf file

.TP
.I .
use drm without specifying the video outputs or size
.RE

.TP
.BI -h
show a summary of the command line options and the main keys

.
.
.
.SH CONFIGURATION FILE

All command line options can also be set in the configuration file
\fI$HOME/.config/hovacui/hovacui.conf\fP, but not the other way around.
Command line options take precedence over the configuration file.
The name of the configuration file can be changed by the
.I -C
commandline option.
Many options can be changed at runtime via keys or the menu
(keystroke \fI'm'\fP).

.TP
.BI mode " (auto|textarea|boundingbox|page)
view by the blocks of text in the page, by the bounding box of the page or by
the whole page; see \fIView mode\fP, above
.TP
.BI fit " (none|horizontal|vertical|both)
fit the text to the width of the screen, to its height, or both;
see \fIFit direction\fP, above
.TP
.BI minwidth " w
the minimal width of a block of text that is made as wide as the screen;
see \fIMinimal width\fP, above)
.TP
.BI distance " d
letters closer than this are in the same block of text;
see \fIText distance\fP, above
.TP
.BI order " (quick|twostep|char)
the algorithm used to find the order among the blocks of text:
see \fIBlock order\fP, above
.TP
.BI noui
disable menu and help
.TP
.BI immediate
pressing enter in a menu immediately executes the required change
without exiting the menu first
.TP
.BI nobox
do not draw the textbox and the page box
.TP
.BI nopagelabel
do not show the page number when it changes; they are still shown by key 's'
.TP
.B night
night mode: pdf file is shown in reverse colors
.TP
.BI presentation
set a number of configuration options to show pages in a way suitable for a
overhead presentation: page mode, horizontal fit, no margins, no page labels,
no boxes, no initial tutorial, no menu and help
.TP
.BI aspect " a
the screen aspect, like \fI16:9\fP or \fI4:3\fP; allows for non-square pixels
.TP
.BI scroll " s
how much a keystroke scrolls, in proportion of the screen size; the default is
\fI1/4\fP, meaning that for example the cursor down keys scrolls the text up
one quarter of the screen
.TP
.BI fontsize " f
the size of the font of the user interface (the menus and the text fields);
this has nothing to do with the size of the text in the pdf document
.TP
.BI margin " m
the text does not exactly fit the width of the screen; a small margin is left
around it; the default is \fI10.0\fP
.TP
.BI area " [x,y,width,height]
the rectangle to draw onto when 'a' is pressed; this is intended for overhead
presentations when misconfiguration of the projector or the screen makes part
of the image invisible, hard to read or interfering with other presentation
devices (whiteboards, etc.)
.TP
.BI device " d
the framebuffer device to use; defaults to \fI/dev/fb0\fP
.TP
.BI notutorial
do not show the short tutorial at startup
.TP
.BI totalpages
show page numbers as "page X of Y" instead of "page X"
.TP
.BI clock
show the current time after the current page number
.TP
.BI noinitlabels
do not show the file name, the viewing mode etc. at startup;
this is the default unless \fInotutorial\fP is present
.TP
.B doublebuffering
enable double buffering;
this is the default,
but the \fIDOUBLEBUFFERING\fP environment variable takes precedence over this
option
.TP
.B nodoublebuffering
disable double buffering;
the \fIDOUBLEBUFFERING\fP environment variable takes precedence over this
option
.TP
.B navigatematches
use the traditional method for moving among matches after a successful search:
a match is highlighted, 'n' and 'p' respectively move to the next and previous
match
.TP
.BI fifo " name
receive commands from the given existing fifo;
see \fIEXTERNAL COMMANDS\fP, below
.TP
.BI outfile " name
name of the output file name, used to save the current textbox with key 'b' and
the logs if enabled by \fI-l\fP
.TP
.BI postsave " command
the command is executed after the content of a box is saved;
it must contain two occurrences of \fI%d\fP, which are replaced by the number
of the saved pdf file; the default is to not do anything; \fIpdftoroff -t
selection-%d.pdf > selection-%d.txt\fP converts the current textbox to text
.TP
.BI script " command keys
the external script and the keys and menu entry to execute it;
see \fIEXTERNAL SCRIPT\fP, below
.TP
.B nocachefile
disable reading and writing the cache file; nothing is remembered when a file
is closed and opened again: position, visualition options, last string searched
for
.TP
.BI log " level
verbose logging to output file;
the supported levels are:
\fI1\fP for debugging the main loop to the output file;
\fI2\fP for pausing each time a page is rendered;
\fI"script"\fP for debugging the external script to the output file


.
.
.
.SH DOCUMENT RELOAD

Key 'r', signal
.I SIGHUP
and the external command
.I reload
make
.B hovacui
reload the current document.

The new version of the document may differ from the previous on its number of
pages and blocks of text in the current page. In such cases, \fBhovacui\fP may
need to move to a different page or block of text. For example, if it was
previously on page nine and the new version of the document has only eight
pages, it moves to page eight.

.
.
.
.SH ANNOTATIONS AND ACTIONS

Annotations and actions are not shown. When the current page contains some of
these, \fBhovacui\fP shows a label "contains annotations and actions" along
with the page number. This label is not shown if the only annotations and
actions in the page are internal links. The rationale is that the user is
warned about the presence of content that is now shown, so that it can be
retrieved with other programs, such as \fBpdfannot\fP.

.
.
.
.SH SEARCHING

Searching is started by key '/', '?' or \fIKEY_FIND\fP. The last searched
string can be recalled by the cursor up key. A running search is stopped
by 'Escape', \fIKEY_EXIT\fP, 's' or 'q'. After the first match is located, the
next screenful of matches is shown by 'n', the previous by 'p'.

Unlike other document viewers, moving among matches is by screenfuls, not
individual matches. If the screen contains 120 matches only one 'n' keystroke
is necessary to see the matches following them, not 120. This mechanism is
guaranteed to loop over all matches unless the fitting direction is \fInone\fP.

.
.
.
.SH EXTERNAL COMMANDS

Another program can send commands to \fIhovacui\fP through a \fIfifo(7)\fP, if
the name of such fifo is given by either the \fI-e\fP commandline option or the
\fIfifo\fP configuration option. If neither is given \fIhovacui\fP does not
open any fifo and does not consequently execute any external command.

The following external commands are currently supported:

.TP
.I reload
reload the document
.TP
.I gotopage n
go to page \fIn\fP

pages are numbered from 0 up regardless of options \fI-O\fP or \fI-F\fP
.TP
.I gotodestination name
go to the named destination \fIname\fP
.IP
a destination named "abcd" can be created by running \fIdvipdfm file.dvi\fP or
\fIdvipdfm -C 0x0010 file.dvi\fP on the dvi file resulting from a TeX file that
contains
.nf
\fI\\special{pdf: dest (abcd) [ @thispage /XYZ @xpos @ypos ]}\fP
.fi
.IP
if running \fIhovacui -e fifo file.pdf\fP,
move to that position with
.nf
\fIecho "gotodestination abcd" > fifo\fP
.fi
.TP
.I offset n
set the page offset; this is the same as the commandline option \fI-O n\fP;
also \fI-F m\fP can be realized this way with \fIn=-m+2\fI
.TP
.I quit
the viewer terminates
.TP
.I document
if a menu or window is open close it and show the document
.TP
.I nop
do nothing; lines starting with \fI#\fP have the same effect

.
.
.
.SH EXTERNAL SCRIPT

If the \fIscript\fP configuration line is given, a script is executed by
keystrokes or from a menu. An example string is:

.nf
.I
script pdfhscript 'l[links]_s[save document]'
.fi

The first option \fIpdfhscript\fP is the name of the script. The second option
\fI'l[links]_s[save document]'\fP comprises the keystrokes and the menu
entries:

.IP "  * " 4
pressing 'l'
causes the execution of:

.I
pdfhscript l 3445abf345dc345687ab5ccd45672345 "file.pdf" 9 3 0.0 0.0 20 [10,10,100,200] [0,0,345,245] []

the arguments after the key are: the permanent ID of the document, the file
name, the current page number, the number of the current textbox, the current
horizontal and vertical scroll within the textbox, the total number of pages,
the current textbox, the visible part of the page and the point or rectangle
being drawn by keystrokes `x` or `d', if any

.IP "  * "
the script can also be executed from a menu reachable from the main menu or by
keystroke 'e'; it contains two entries: \fIlinks\fP and \fIsave document\fP;
the first is equivalent to keystroke 'l'; the second fires the execution of:

.I
pdfhscript s 3445abf345dc345687ab5ccd45672345 "file.pdf" 9 3 0.0 0.0 20 [10,10,100,200] [0,0,345,245] []

.P

The underscore in \fI_s\fP means that the second entry has no key shortcut:
pressing 's' does not execute the script. The same happens for the predefined
keys.

If no \fIscript\fP is in the configuration file, the menu is not shown.

The script is executed in foreground; \fIhovacui\fP blocks until it ends.

The return value tells \fIhovacui\fP what to do when the script returns:

.IP "  0 " 4
show the script output on screen
.IP "  1 "
move to the position given in the script output
as \fIpage box scrollx scrolly\fP,
if a second output line is present,
it is the name of the file to load instead of the current one
.IP "  2 "
print that the script failed
.IP "  3 "
similar to 1, but the document content and position is essentially the same;
use when switching to a different version of the same document
.P

Only one script can be specified. It is supposed to perform different actions
depending on its first argument. The included \fIhovacui.conf\fP example
configuration file calls the included script \fIpdfhscript\fP on the following
keystrokes:

.IP "  l " 4
show the links in page 9 of the document in a browser
.IP "  s "
save the document;
this is an identical copy of the file, not a new rendering of it like done by
the 'save document' entry in the 'page range' menu
.IP "  y "
select the visible part of the current textbox or the content of the rectangle
being drawn on keystroke 'd';
requires the environment variable \fICOPIER\fP to be the name of a program that
selects its input
.IP "  N "
edit filename-notes.txt, if a note for the current page exists (edit notes)
.IP "  A "
edit filename-notes.txt (add notes)
.IP "  E "
operate on the point or rectangle being drawn by kestrokes `x` or `d`,
if the script \fIpdfinteractive\fP is available;
the included script allows to clip all pages to the rectangle, to erase or
cover it and to write at the point;
it requires \fIpdfdrawover(1)\fP

.
.
.
.SH THE CACHE FILES

When closing, \fBhovacui\fP saves internal data to
\fI$HOME/.cache/hovacui/permanent_id\fP. The last part is the permanent ID of
the pdf file. This data is read back when the pdf file is opened again. The
content of the cache file is:

.nf
.I
page box x y
.I
update_id
.I
filename
.I
viewmode fit order distance minwidth
.I
timestamp
.I
rectangle
.fi

In details: page number, index of the textbox within the page, position within
the textbox, update ID of the pdf file, filename, visualization parameters,
timestamp at the moment of closing, rectangle currently being drawn (in
response to keystroke `d`) or \fI[]\fP if none.

The file is also written and read back across a call to the external script,
which can change it.

.
.
.
.SH ENVIRONMENT VARIABLES

\fBhovacui\fP is affected by the following enviroment variables:

.TP
.I DOUBLEBUFFERING
unless set to \fI"no"\fP, double buffering is used to display pages: rendering
is done on a buffer, which is shown on screen only when done; disabling double
buffering allows seeing the pages during drawing; this may be useful in some
special cases such as pages with lot of content, for example high-resolution
raster images; this variable takes precedence over the config file options
\fIdoublebuffering\fP and \fInodoublebuffering\fP
.TP
.I ESCDELAY
the milliseconds of delay that make an escape input character to be taken as an
actual escape keystroke; default is \fI200\fP; for a complete explanation, see
\fIncurses(3)\fP
.TP
.I DISPLAY
the X11 server to connect to
.TP
.I HOME
the starting path for the configuration file
\fI$HOME/.config/hovacui/hovacui.conf\fP



.
.
.
.SH COMPARISON WITH GREEN(1)

\fBgreen\fP (http://github.com/schandinat/green) is a fine pdf viewer for the
Linux framebuffer and X11. It has some features more and some less than
\fBhovacui\fP:

.IP "  * " 4
green only allows fitting the whole page to the screen (horizontally,
vertically and both ways); hovacui also allows fitting a single block of text
at time or the bounding box of the page
.IP "  * "
green allows for arbitrary zooming and moving in the page;
by default, hovacui has automatic zooming and only allows vertical movements
(but horizontal movements are never necessary); it allows for arbitrary zooming
and moving in the page with viewmode=page and fit=none
.IP "  * "
green allows rotating the document; hovacui does not
.IP "  * "
green can display multiple documents (using tabs to switch to the next);
hovacui only shows a single document
.IP "  * "
green allows searching and moving to a given page, but does not have a user
interface; this means that the user has for example to type a page number
without seeing it; hovacui has a crude but functional user interface
.IP "  * "
hovacui has an inline help and allows for non-square pixels; green does not
(but a fork with these features exist: https://github/sgerwk/green)
.IP "  * "
hovacui briefly shows the page number when switching page; green does not
.IP "  * "
the configuration file of green allows for schemes (profiles); hovacui has a
configuration file but no schemes

.SH SEE ALSO

\fBgreen\fP(\fI1\fP),
\fBjfbview\fP(\fI1\fP),
\fBfbpdf\fP(\fI1\fP)

.SH NOTES

If something goes wrong, press 'v' to change view mode.

The horizontal fit mode is intended for horizontal scripts, but \fBhovacui\fP
also allows for vertical fit mode. It however has no support for sorting blocks
of text for vertical scripts yet, nor for detecting multiple columns.

The cursor left and cursor right keys may not work as expected. Yet, they are
coherent with the general rule: when moving in a direction and the edge of the
current block of text in that direction is already shown, switch to the next
block of text. This means that in horizontal fit mode (the default) the left
and right cursor keys work as "move to the previous/next" block of text.