djview4 (1)

Leading comments

t

Copyright (c) 2007- Leon Bottou

This is free documentation; 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.

The GNU General Public License's references to "object code"
and "executables" are to be interpreted as the output of any
document formatting or typesetting system, including
intermediate and printed output.

This manual is...

(The comments found at the beginning of the groff file "man1/djview4.1".)

NAME

djview4 - Standalone DjVu viewer

SYNOPSIS

djview4 [options] [argument]

DESCRIPTION

Standalone viewer for DjVu files. Features include navigating documents, zooming and panning page images, producing and displaying thumbnails, displaying document outlines, searching documents for particular words in the hidden text layer, copying hidden text to the clipboard, saving pages and documents as bundled or indirect multi-page files, and printing page and documents. The viewer can simultaneously display several pages using a side-by-side or a continuous layout.

COMMAND LINE ARGUMENT AND OPTIONS

This program can run as a standalone program or as a slave process for the DjVu browser plugin nsdejavu. When running as a standalone program, the command line argument argument can be:

*

The filename of a valid DjVu document.

*

A local DjVu document

URL

of the form:

file:///path/name.djvu[?djvuopts&keyword=value&...]

The square brackets delimit the optional components of the

URL.

Various options can be specified using a syntax similar to that of

CGI

arguments. Specifying options in this manner is very useful for a browser plugin because there are no command line arguments. In the case of a standalone viewer, all options can be specified as command line arguments.

*

An remote DjVu document

URL

of the form:

http://host/path/name.djvu[?djvuopts&keyword=value&...]

https://host/path/name.djvu[?djvuopts&keyword=value&...]

Browsing remote DjVu documents with the standalone viewer is less efficient than using the browser plugin. The standalone viewer does not benefit from the browser caching strategies and proxy settings. Proxy settings for the standalone viewer can be set independently with the preferences dialog.

An extensive list of options are recognized. Most options can be specified as command line argument starting with the customary dash character (-) or using the syntax of

arguments in the document Some options however are only meaningful as command line arguments. Other options are only recognized when running the version of the djview4 program.

COMMAND LINE OPTIONS

The following options are only meaningful when specified on the command line.

-help

Display a brief help message.

-verbose

Prints informational messages on the console. This option is very useful because it displays messages about the unrecognized constructs in the DjVu annotation and hyperlink layers.

-fullscreen, -fs

Start djview4 in full screen mode. Use the key ESC to exit the full screen mode.

-slideshow[=arg]

Start djview4 in slide show mode. The optional numerical argument arg specifies the number of seconds before turning each page. Use the key ESC to exit the slide show mode.

-style=stylename

Specify the graphical user interface style. The recognized values for stylename depend on the installed version of the Qt toolkit. Common style names include cde, motif, plastique, platinum, and windows.

X11 OPTIONS

The following command line options are recognized by the version of the djview4 program. Unlike most djview4 options, X11 options that demand an argument do not use the equal character to introduce their argument.

-display displayname

Specify that the djview4 windows should appear on the X11 display displayname.

-geometry WxH+X+Y

Specify the initial size and position of the first window using the traditional X11 geometry specification syntax. The numerical arguments W and H represent the initial window width and height. The numerical arguments X and Y indicate the window position relative to the top left corner of the screen.

-name name

Set the application name.

-title title

Set the title of the first window.

-fn fontname, -font fontname

Specify the name of the default font used for buttons and menus. The font should be specified using a X logical font description string.

-bg color, -background color

Specify the default background color for graphical user interface elements. The color should be given as a standard X11 color name.

-fg color, -foreground color

Specify the default foreground color for graphical user interface elements. The color should be given as a standard X11 color name.

-btn color

Specify the default button color. The color should be given as a standard X11 color name.

-ncols count

Limit the number of colors allocated on a 8 bit display. The default color cube contains 216 distinct colors.

-cmap

Force the allocation of a private color map on a 8-bit display. This might increase the color quality but cause flashing when the viewer window gets activated.

GENERAL OPTIONS

The following options can be specified as command line options or can be passed by augmenting the document using a syntax similar to that of arguments

.../file.djvu?djvuopts&key=value&key=value&...

In order to separate real

arguments from these options, the viewer only recognizes keywords that appear after the word djvuopts. The keywords key are derived from the option names by removing the initial dashes.

-page=pagename

Display a specific document page. The viewer first searches a page whose identifier matches the argument pagename. Otherwise, if pagename is a number preceded by character + or -, the viewer performs a displacement relative to the current page. Otherwise, starting from the current page and wrapping around, it searches for a page whose title matches the argument pagename. Otherwise, if pagename is numerical, it is interpreted as an ordinal page number. Otherwise, and finally, the viewer searches a page whose name matches pagename.

-pageno=pagenumber

The page searching algorithm for option page can cause ambiguities when page titles can be interpreted as numbers. The argument of option pageno is always interpreted as an ordinal page number. This option is less portable than page because it is not recognized by earlier versions of the djvu plugin. When using this option is necessary, it is advisable to use both the page and pageno options.

-zoom=zoomfactor

Specify the initial zoom factor. Unless the toolbar, pop-up menu and keyboard are disabled, the user will be able to change the zoom factor. Legal values for zoomfactor are shown in the below:

number	Magnification factor in range 10% to 999%.
one2one	Select the "one-to-one" mode.
width	Select the "fit width" mode.
page	Select the "fit page" mode.
stretch	Stretch the image to the plugin window size.

-showposition=px,py

Specify a point in the current page that should be as close as possible to the center of the window. The horizontal and vertical positions px,py in the current page are given as fractions in range 0 to 1. For instance, 0,0 designates the upper left corner of the page, 0.5,0.5 is the center, and 1,1 is the lower right corner.

-mode=modespec

Specify the initial display mode. Unless the toolbar and pop-up menu are disabled, the user will be able to change it. Legal values for modespec are shown in the below:

color	Display the color image.
bw	Display the foreground mask only.
fore	Display the foreground only.
back	Display the background only.
text	Overlay the hidden text over the color image.

-hor_align=keyword, -halign=keyword

Specify the horizontal position of the page in the viewer window. (This does not specify what part of the page will be shown, but rather how margins will be laid out around the page in the plugin window.) Argument keyword must be left, center, or right.

-ver_align=keyword, -valign=keyword

Specify the vertical position of the page in the viewer window. (This does not specify what part of the page will be shown, but rather how margins will be laid out around the page in the plugin window.) Argument keyword must be top, center, or bottom.

-cache=(yes|no)

Enable or disable the caching of fully decoded pages of the document. Caching is on by default. Caching of documents whose

URL

does not contain an extension .djvu or .djv is off by default.

-continuous=(yes|no)

Enable or disable the continuous layout of multipage documents.

-sidebyside=(yes|no), -side_by_side=(yes|no)

Enable or disable the side-by-side layout of multipage documents.

-coverpage=(yes|no)

Specify whether the cover page must be displayed alone when multipage documents are shown in side-by-side layout.

-righttoleft=(yes|no)

Specify whether pages should be arranged right-to-left when multipage documents are shown in side-by-side layout.

-layout=keyword{,keyword}

Specify the layout settings using a single list of comma-separated keywords. The following keywords are recognized:

single	Disable the side-by-side and continuous modes.
double	Enable the side-by-side mode.
continuous	Enable the continuous mode.
cover,nocover	First page treatment in side-by-side mode.
ltor,rtol	Layout direction for side-by-side mode.
gap,nogap	Specify whether there is a gap between pages.

-scrollbars=(yes|no)

Enable or disable the presence of scroll bars when the full image size exceeds the plugin window size. The default is yes.

-frame=(yes|no)

Enable or disable the display of a thin frame and shadow around the DjVu images. Frames are enabled by default.

-background=color

Specify the color of the background border displayed around the document. The color color must be given in hexadecimal

RRGGBB

or

#RRGGBB

format.

-toolbar=keyword{(,|+|-)keyword}

Controls the appearance and the contents of the toolbar. The argument of option toolbar is composed of a number of keywords separated by characters comma, plus or minus. The appearance of the toolbar is controlled by keywords placed before the first occurrence of a character plus or minus. The following keywords are recognized in this context:

no	Disable toolbar.
always	Displays the toolbar.
auto	Enable toolbar "autohide" mode (not implemented).
top	Place toolbar along the top edge.
bottom	Place toolbar along the bottom edge.

The contents of the toolbar is controlled by keywords placed after the first occurrence of a character plus or minus. Each keyword adds (after a plus) or removes (after a minus) a particular toolbar button or group of buttons. The initial content of the toolbar is determined by the first occurrence of a character plus or minus. When this is a plus, the toolbar is initially empty. When this is a minus, the toolbar initially contains the default selection of buttons.
The following keywords are recognized:

modecombo	for the display mode selection tool.
zoomcombo	for the zoom selection tool.
zoom	for the zoom buttons.
select	for the selection button.
rotate	for the image rotation buttons.
find	for the text search button.
new	for the new window button.
open	for the open new document button.
save	for the save button.
print	for the print button.
layout	for the page layout buttons.
pagecombo	for the page selection tool.
firstlast	for the first-page and last-page buttons.
prevnext	for the previous- and next-page buttons.
backforw
help

For the sake of backward compatibility, the keywords fore, fore_button, back, back_button, bw, bw_button, color, and color_button are interpreted like keyword modecombo; the keyword rescombo is a synonym of zoomcombo; the keywords pan, zoomsel, and textsel are interpreted like keyword select; and the keyword doublepage is interpreted like keyword layout. All other keywords are ignored.

-menubar=(yes|no)

Enable or disable the presence of the menu bar located on top of the window.

-statusbar=(yes|no)

Enable or disable the presence of the status bar located at the bottom of the window.

-sidebar=keyword{,keyword}

Control the dockable panels. The argument is a comma separated list of keywords. A first group of keywords selects which panels are affected. Omitting these keywords selects all panels. A second group of keywords then controls the visibility and the position of the selected panels.

thumbnails	specify the thumbnail panel.
outline,bookmarks	specify the outline panel.
search,find	specify the search panel.
yes,true	show the specified panels (default).
no,false	hide the specified panels.
left	dock specified panels on the left side.
right	dock specified panels on the right side.
top	dock specified panels on the top side.
bottom	dock specified panels on the bottom side.

-thumbnails=keyword{,keyword}

Compatibility alias for -sidebar=keyword{,keyword},thumbnails.

-outline=keyword{,keyword}

Compatibility alias for -sidebar=keyword{,keyword},outline.

-menu=(yes|no)

Enable or disable the pop-up menu.

-keyboard=(yes|no)

Enable or disable the DjVu plugin keyboard shortcuts. The default is yes (enabled). Note that disabling the keyboard handling does not disable the shortcuts associated with active menus (see options -menu and -menubar), visible toolbars and sidebars (see options -toolbar and -sidebar).

-mouse=(yes|no)

Enable or disable mouse interaction for panning and selecting. The default is yes (enabled).

-links=(yes|no)

Enable or disable hyper-links in the DjVu image. Hyper-links are enabled by default.

-highlight=x,y,w,h[,color]

Display a highlighted rectangle at the specified coordinates in the current page and with the specified color. Coordinates x, y, w, and h are measured in document image coordinates (not screen coordinates). The origin is set at the bottom left corner of the image. The color color must be given in hexadecimal

RRGGBB

or

#RRGGBB

format. Multiple highlighted zone can be specified and can be interspersed with multiple -page=pagename options.

-find=text

Highlight occurrences of the given string text. This option works when the document contains a hidden text layer. It can be used in conjunction with -sidebar=find to display the text searching interface.
String text can be terminated by slash (/) followed by letters specifying search options. The following letters are recognized

c	Case-sensitive search.
C	Case-insensitive search (default).
w	Search hits start on word boundaries (default).
W	Ignore word boundaries.
r	Regular expression search.
R	String search (default).

-rotate=(0|90|180|270)

Rotate the djvu image by the specified angle expressed in degrees counter-clockwise.

-print=(yes|no)

Enable or disable printing the DjVu document. Printing is enabled by default.

-save=(yes|no)

Enable or disable saving the DjVu document. Saving is enabled by default.

-passive

Cause the DjVu image to be displayed in a manner similar to an ordinary web image. The default zoom factor is changed to page. The toolbar, the status bar, the scrollbars, the menus, and the keyboard shortcuts are disabled.

-passivestretch

Cause the DjVu image to be displayed in a manner similar to an ordinary web image. The default zoom factor is changed to stretch. The toolbar, the status bar, the scrollbars, the menus, and the keyboard shortcuts are disabled.

-nomenu, -notoolbar, -noscrollbars

These options were recognized by some versions of the DjVu viewers and are honored for the sake of backward compatibility. A warning message is printed when option -verbose is active.

-logo, -textsel, -search

These options were recognized by some versions of the DjVu viewers but are currently not implemented by djview4. A warning message is printed when option -verbose is active.

USAGE

Most features can be accessed using the menus, the toolbar, the side bar or the pop-up menu shown when the right mouse button is depressed over a DjVu image. Detailled help can be accessed by clicking the contextual help icon from the toolbar and then clicking on various section of the djview user interface.
The following table lists some useful key combinations recognized when the djvu document is active:

Handy effects can be achieved by holding modifier keys. Although these keys are configurable from the preference dialog, the following table lists the default assignments

ENVIRONMENT

Setting environment variable DJVIEW_VERBOSE to a nonzero value is equivalent to calling djview with option -verbose. Setting environment variable DJVIEW_OPENGL to values 0 or 1 overrides the preference settings regarding OpenGL rendering.
When the user clicks on a djvu hyperlink pointing to a web page, the program first tries to execute the web browser programs whose names are listed in the colon separated environment variable BROWSER, then tries sensible platform dependent defaults.
The user interface language is determined by first trying to find a complete set of translation files for the language specified in the preference dialog, then for the ISO 639 languages specified in the colon separated environment variable LANGUAGE, and finally the language specified by the system locale. If all these searches fail, the user interface language reverts to the english default.

CREDITS

This program was written by L'eon Bottou <leonb@users.sf.net> and is distributed under the GNU General Public License. This program includes code derived from program tiff2pdf, written by Ross Finlayson and released under a BSD license.

SEE ALSO

djvu(1), ddjvu(1), nsdejavu(1), tiff2pdf(1)