Debian Codegraph @

src/djview.1

raw
1 .\" t
2 .\"
3 .\" Copyright (c) 2007- Leon Bottou
4 .\"
5 .\" This is free documentation; you can redistribute it and/or
6 .\" modify it under the terms of the GNU General Public License as
7 .\" published by the Free Software Foundation; either version 2 of
8 .\" the License, or (at your option) any later version.
9 .\"
10 .\" The GNU General Public License's references to "object code"
11 .\" and "executables" are to be interpreted as the output of any
12 .\" document formatting or typesetting system, including
13 .\" intermediate and printed output.
14 .\"
15 .\" This manual is distributed in the hope that it will be useful,
16 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
17 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 .\" GNU General Public License for more details.
19 .\"
20 .\" You should have received a copy of the GNU General Public
21 .\" License along with this manual. Otherwise check the web site
22 .\" of the Free Software Foundation at http://www.fsf.org.
23 .TH DJVIEW4 1 "10/11/2001" "DjVuLibre" "DjVuLibre"
24 .de SS
25 .SH \\0\\0\\0\\$*
26 ..
27 .SH NAME
28 djview4 \- Standalone DjVu viewer
29
30 .SH SYNOPSIS
31 .BI "djview4 [" "options" "] [" "argument" "]"
32
33 .SH DESCRIPTION
34 Standalone viewer for DjVu files.
35 Features include navigating documents,
36 zooming and panning page images,
37 producing and displaying thumbnails,
38 displaying document outlines,
39 searching documents for particular words in the hidden text layer,
40 copying hidden text to the clipboard,
41 saving pages and documents
42 as bundled or indirect multi-page files,
43 and printing page and documents.
44 The viewer can simultaneously display several pages
45 using a side-by-side or a continuous layout.
46
47 .SH COMMAND LINE ARGUMENT AND OPTIONS
48 This program
49 can run as a standalone program or
50 as a slave process for the DjVu browser plugin
51 .BR nsdejavu .
52 When running as a standalone program,
53 the command line argument
54 .I argument
55 can be:
56 .IP "*" 3
57 The filename of a valid DjVu document.
58 .IP "*" 3
59 A local DjVu document
60 .SM URL
61 of the form:
62 .IP "" 5
63 .BI "file:///" path "/" name.djvu "[?djvuopts&" keyword = value "&...]"
64 .IP "" 3
65 The square brackets delimit the optional components of the
66 .SM URL.
67 Various options can be specified using a syntax
68 similar to that of
69 .SM CGI
70 arguments.
71 Specifying options in this manner is very useful
72 for a browser plugin because there are no
73 command line arguments.
74 In the case of a standalone viewer,
75 all options can be specified as command line arguments.
76 .IP "*" 3
77 An remote DjVu document
78 .SM URL
79 of the form:
80 .IP "" 5
81 .BI http:// host / path "/" name.djvu "[?djvuopts&" keyword = value "&...]"
82 .IP "" 5
83 .BI https:// host / path "/" name.djvu "[?djvuopts&" keyword = value "&...]"
84 .IP "" 3
85 Browsing remote DjVu documents with the standalone viewer
86 is less efficient than using the browser plugin.
87 The standalone viewer does not benefit from the browser
88 caching strategies and proxy settings.
89 Proxy settings for the standalone viewer can be set
90 independently with the preferences dialog.
91 .PP
92
93 An extensive list of options are recognized.
94 Most options can be specified as command line argument starting
95 with the customary dash character
96 .BR "" "(" "-" ")"
97 or using the syntax of
98 .SM CGI
99 arguments in the document
100 .SM URL.
101 Some options however are only meaningful
102 as command line arguments.
103 Other options are only recognized when
104 running the
105 .SM X11
106 version of the
107 .BR djview4
108 program.
109
110 .SH COMMAND LINE OPTIONS
111 The following options are only meaningful
112 when specified on the command line.
113
114 .TP
115 .B "-help"
116 Display a brief help message.
117
118 .TP
119 .B "-verbose"
120 Prints informational messages on the console.
121 This option is very useful because it displays
122 messages about the unrecognized constructs
123 in the DjVu annotation and hyperlink layers.
124
125 .TP
126 .BI "-fullscreen, -fs "
127 Start
128 .B djview4
129 in full screen mode.
130 Use the key
131 .B ESC
132 to exit the full screen mode.
133
134 .TP
135 .BI "-slideshow[=" arg "]
136 Start
137 .B djview4
138 in slide show mode.
139 The optional numerical argument
140 .I arg
141 specifies the number of seconds
142 before turning each page.
143 Use the key
144 .B ESC
145 to exit the slide show mode.
146
147
148 .TP
149 .BI "-style=" "stylename"
150 Specify the graphical user interface style.
151 The recognized values for
152 .I stylename
153 depend on the installed version of the Qt toolkit.
154 Common style names include
155 .BR cde ,
156 .BR motif ,
157 .BR plastique ,
158 .BR platinum ,
159 and
160 .BR windows .
161
162
163 .SH X11 OPTIONS
164 The following command line options are recognized by the
165 .SM X11
166 version of the
167 .B djview4
168 program.
169 Unlike most
170 .B djview4 options,
171 X11 options that demand an argument
172 do not use the equal character
173 to introduce their argument.
174 .TP
175 .BI "-display " "displayname"
176 Specify that the
177 .B djview4
178 windows should appear on the X11 display
179 .IR displayname .
180
181 .TP
182 .BI "-geometry " W x H + X + Y
183 Specify the initial size and position of the first window
184 using the traditional X11 geometry specification syntax.
185 The numerical arguments
186 .IR W " and " H
187 represent the initial window width and height.
188 The numerical arguments
189 .IR X " and " Y
190 indicate the window position relative to the
191 top left corner of the screen.
192
193 .TP
194 .BI "-name " "name"
195 Set the application name.
196
197 .TP
198 .BI "-title " "title"
199 Set the title of the first window.
200
201 .TP
202 .BI "-fn " "fontname" ", -font " "fontname"
203 Specify the name of the default font
204 used for buttons and menus.
205 The font should be specified using
206 a X logical font description string.
207 .TP
208 .BI "-bg " "color" ", -background " "color"
209 Specify the default background color for
210 graphical user interface elements.
211 The color should be given as a standard X11 color name.
212
213 .TP
214 .BI "-fg " "color" ", -foreground " "color"
215 Specify the default foreground color for
216 graphical user interface elements.
217 The color should be given as a standard X11 color name.
218
219 .TP
220 .BI "-btn " "color"
221 Specify the default button color.
222 The color should be given as a standard X11 color name.
223
224 .TP
225 .BI "-ncols " "count"
226 Limit the number of colors allocated on a 8 bit display.
227 The default color cube contains 216 distinct colors.
228 .TP
229 .B "-cmap"
230 Force the allocation of a private color map on a 8-bit display.
231 This might increase the color quality but cause flashing
232 when the viewer window gets activated.
233
234 .SH GENERAL OPTIONS
235 The following options can be specified as command line options
236 or can be passed by augmenting the document
237 .SM URL
238 using a syntax similar to that of
239 .SM CGI
240 arguments
241 .IP "" 3
242 .BI "http://.../file.djvu?djvuopts&" "key=value" "&" "key=value" "&" "..."
243 .PP
244 In order to separate real
245 .SM CGI
246 arguments from these options,
247 the viewer only recognizes keywords
248 that appear after the word
249 .BR djvuopts .
250 The keywords
251 .I key
252 are derived from the option names
253 by removing the initial dashes.
254
255 .TP
256 .BI "-page=" "pagename"
257 Display a specific document page.
258 The viewer first searches a page
259 whose identifier matches the argument
260 .IR pagename .
261 Otherwise, if
262 .I pagename
263 is a number preceded by character
264 .BR "+" " or " "-" ","
265 the viewer performs a displacement relative to the current page.
266 Otherwise, starting from the current page
267 and wrapping around, it searches for a page
268 whose title matches the argument
269 .IR pagename .
270 Otherwise, if
271 .I pagename
272 is numerical, it is interpreted as
273 an ordinal page number.
274 Otherwise, and finally, the viewer searches a page
275 whose name matches
276 .IR pagename .
277 .TP
278 .BI "-pageno=" "pagenumber"
279 The page searching algorithm for option
280 .B "page"
281 can cause ambiguities when page titles can
282 be interpreted as numbers.
283 The argument of option
284 .B "pageno"
285 is always interpreted as an ordinal page number.
286 This option is less portable than
287 .B "page"
288 because it is not recognized by earlier
289 versions of the djvu plugin.
290 When using this option is necessary,
291 it is advisable to use both the
292 .B "page"
293 and
294 .B "pageno"
295 options.
296 .TP
297 .BI "-zoom=" zoomfactor
298 Specify the initial zoom factor.
299 Unless the toolbar, pop-up menu and keyboard are disabled,
300 the user will be able to change the zoom factor.
301 Legal values for
302 .I zoomfactor
303 are shown in the below:
304 .br
305 .TS
306 center,box;
307 lfI l
308 lfB l
309 lfB l
310 lfB l
311 lfB l
312 .
313 number Magnification factor in range 10% to 999%.
314 one2one Select the "one-to-one" mode.
315 width Select the "fit width" mode.
316 page Select the "fit page" mode.
317 stretch Stretch the image to the plugin window size.
318 .TE
319 .PP
320
321 .TP
322 .BI "-showposition=" px "," py
323 Specify a point in the current page that should be
324 as close as possible to the center of the window.
325 The horizontal and vertical positions
326 .IB px "," py
327 in the current page are given as fractions in range 0 to 1.
328 For instance,
329 .B 0,0
330 designates the upper left corner of the page,
331 .B 0.5,0.5
332 is the center, and
333 .B 1,1
334 is the lower right corner.
335
336 .TP
337 .BI "-mode=" modespec
338 Specify the initial display mode.
339 Unless the toolbar and pop-up menu are disabled,
340 the user will be able to change it.
341 Legal values for
342 .I modespec
343 are shown in the below:
344 .br
345 .TS
346 center,box;
347 lfB l
348 lfB l
349 lfB l
350 lfB l
351 lfB l
352 .
353 color Display the color image.
354 bw Display the foreground mask only.
355 fore Display the foreground only.
356 back Display the background only.
357 text Overlay the hidden text over the color image.
358 .TE
359 .PP
360
361 .TP
362 .BI "-hor_align=" keyword ", -halign=" keyword
363 Specify the horizontal position of the page in the viewer window.
364 (This does not specify what part of the page will be shown, but rather
365 how margins will be laid out around the page in the plugin window.)
366 Argument
367 .I keyword
368 must be
369 .BR left ,
370 .BR center ,
371 or
372 .BR right .
373
374 .TP
375 .BI "-ver_align=" keyword ", -valign=" keyword
376 Specify the vertical position of the page in the viewer window.
377 (This does not specify what part of the page will be shown, but rather
378 how margins will be laid out around the page in the plugin window.)
379 Argument
380 .I keyword
381 must be
382 .BR top ,
383 .BR center ,
384 or
385 .BR bottom .
386
387 .TP
388 .BI "-cache=(yes|no)"
389 Enable or disable the caching of fully decoded pages of the document.
390 Caching is on by default.
391 Caching of documents whose
392 .SM URL
393 does not contain an extension
394 .BR .djvu " or " .djv
395 is off by default.
396
397 .TP
398 .BI "-continuous=(yes|no)"
399 Enable or disable the continuous layout of
400 multipage documents.
401
402 .TP
403 .BI "-sidebyside=(yes|no), -side_by_side=(yes|no)"
404 Enable or disable the side-by-side layout of
405 multipage documents.
406
407 .TP
408 .BI "-coverpage=(yes|no)"
409 Specify whether the cover page must be displayed alone
410 when multipage documents are shown in side-by-side layout.
411
412 .TP
413 .BI "-righttoleft=(yes|no)"
414 Specify whether pages should be arranged right-to-left
415 when multipage documents are shown in side-by-side layout.
416
417 .TP
418 .BI "-layout=" keyword "{," keyword "}"
419 Specify the layout settings using a single list
420 of comma-separated keywords.
421 The following keywords are recognized:
422 .br
423 .TS
424 center,box;
425 lfB l
426 lfB l
427 lfB l
428 lfB l
429 lfB l
430 lfB l
431 .
432 single Disable the side-by-side and continuous modes.
433 double Enable the side-by-side mode.
434 continuous Enable the continuous mode.
435 cover,nocover First page treatment in side-by-side mode.
436 ltor,rtol Layout direction for side-by-side mode.
437 gap,nogap Specify whether there is a gap between pages.
438 .TE
439
440 .TP
441 .BI "-scrollbars=(yes|no)"
442 Enable or disable the presence of scroll bars when the full
443 image size exceeds the plugin window size.
444 The default is yes.
445
446 .TP
447 .BI "-frame=(yes|no)"
448 Enable or disable the display of a thin frame
449 and shadow around the DjVu images.
450 Frames are enabled by default.
451
452 .TP
453 .BI "-background=" color
454 Specify the color of the background border
455 displayed around the document. The color
456 .I color
457 must be given in hexadecimal
458 .SM RRGGBB
459 or
460 .SM #RRGGBB
461 format.
462
463 .TP
464 .BI "-toolbar=" keyword "{(,|+|-)" keyword "}"
465 Controls the appearance and the contents of the toolbar.
466 The argument of option
467 .B toolbar
468 is composed of a number of keywords separated
469 by characters comma, plus or minus.
470 The appearance of the toolbar is controlled by keywords
471 placed before the first occurrence of a character plus
472 or minus. The following keywords are recognized in
473 this context:
474 .br
475 .TS
476 center,box;
477 lfB l
478 lfB l
479 lfB l
480 lfB l
481 lfB l
482 .
483 no Disable toolbar.
484 always Displays the toolbar.
485 auto Enable toolbar "autohide" mode (not implemented).
486 top Place toolbar along the top edge.
487 bottom Place toolbar along the bottom edge.
488 .TE
489 .IP ""
490 The contents of the toolbar is controlled by keywords
491 placed after the first occurrence of a
492 character plus or minus.
493 Each keyword adds (after a plus) or removes (after a minus)
494 a particular toolbar button or group of buttons.
495 The initial content of the toolbar is determined
496 by the first occurrence of a character plus or minus.
497 When this is a plus,
498 the toolbar is initially empty.
499 When this is a minus,
500 the toolbar initially contains
501 the default selection of buttons.
502
503 The following keywords are recognized:
504 .br
505 .TS
506 center,box;
507 lfB l
508 lfB l
509 lfB l
510 lfB l
511 lfB l
512 lfB l
513 lfB l
514 lfB l
515 lfB l
516 lfB l
517 lfB l
518 lfB l
519 lfB l
520 lfB l
521 .
522 modecombo for the display mode selection tool.
523 zoomcombo for the zoom selection tool.
524 zoom for the zoom buttons.
525 select for the selection button.
526 rotate for the image rotation buttons.
527 find for the text search button.
528 new for the new window button.
529 open for the open new document button.
530 save for the save button.
531 print for the print button.
532 layout for the page layout buttons.
533 pagecombo for the page selection tool.
534 firstlast for the first-page and last-page buttons.
535 prevnext for the previous- and next-page buttons.
536 backforw reserved for the back and forward buttons.
537 help for the contextual help button.
538 .TE
539 .PP
540 For the sake of backward compatibility,
541 the keywords
542 .BR fore ,
543 .BR fore_button ,
544 .BR back ,
545 .BR back_button ,
546 .BR bw ,
547 .BR bw_button ,
548 .BR color ,
549 and
550 .BR color_button
551 are interpreted like keyword
552 .BR modecombo ;
553 the keyword
554 .BR rescombo
555 is a synonym of
556 .BR zoomcombo ;
557 the keywords
558 .BR pan ,
559 .BR zoomsel ,
560 and
561 .BR textsel
562 are interpreted like keyword
563 .BR select ;
564 and the keyword
565 .BR doublepage
566 is interpreted like keyword
567 .BR layout .
568 All other keywords are ignored.
569 .PP
570
571 .TP
572 .BI "-menubar=(yes|no)"
573 Enable or disable the presence of the menu bar
574 located on top of the window.
575
576 .TP
577 .BI "-statusbar=(yes|no)"
578 Enable or disable the presence of the status bar
579 located at the bottom of the window.
580
581 .TP
582 .BI "-sidebar=" keyword "{," keyword "}"
583 Control the dockable panels.
584 The argument is a comma separated list of keywords.
585 A first group of keywords selects which panels are affected.
586 Omitting these keywords selects all panels.
587 A second group of keywords then controls the visibility and
588 the position of the selected panels.
589 .br
590 .TS
591 center,box;
592 lfB l
593 lfB l
594 lfB l
595 lfB l
596 lfB l
597 lfB l
598 lfB l
599 lfB l
600 lfB l
601 .
602 thumbnails specify the thumbnail panel.
603 outline,bookmarks specify the outline panel.
604 search,find specify the search panel.
605 =
606 yes,true show the specified panels (default).
607 no,false hide the specified panels.
608 left dock specified panels on the left side.
609 right dock specified panels on the right side.
610 top dock specified panels on the top side.
611 bottom dock specified panels on the bottom side.
612 .TE
613 .PP
614 .TP
615 .BI "-thumbnails=" keyword "{," keyword "}"
616 Compatibility alias for
617 .BI "-sidebar=" keyword "{," keyword "},thumbnails."
618 .TP
619 .BI "-outline=" keyword "{," keyword "}"
620 Compatibility alias for
621 .BI "-sidebar=" keyword "{," keyword "},outline."
622 .TP
623 .BI "-menu=(yes|no)"
624 Enable or disable the pop-up menu.
625
626 .TP
627 .BI "-keyboard=(yes|no)"
628 Enable or disable the DjVu plugin keyboard shortcuts.
629 The default is yes (enabled).
630 Note that disabling the keyboard handling
631 does not disable the shortcuts associated
632 with active menus (see options
633 .BR "-menu" " and " "-menubar" "),"
634 visible toolbars and sidebars (see options
635 .BR "-toolbar" " and " "-sidebar" ")."
636
637 .TP
638 .BI "-mouse=(yes|no)"
639 Enable or disable mouse interaction for panning and selecting.
640 The default is yes (enabled).
641
642 .TP
643 .BI "-links=(yes|no)"
644 Enable or disable hyper-links in the DjVu image.
645 Hyper-links are enabled by default.
646
647 .TP
648 .BI "-highlight=" x "," y "," w "," h "[," color "]"
649 Display a highlighted rectangle at the specified coordinates in
650 the current page and with the specified color. Coordinates
651 .IR x ", " y ", " w ", and " h
652 are measured in document image coordinates (not screen coordinates).
653 The origin is set at the bottom left corner of the image. The color
654 .I color
655 must be given in hexadecimal
656 .SM RRGGBB
657 or
658 .SM #RRGGBB
659 format.
660 Multiple highlighted zone can be specified
661 and can be interspersed with multiple
662 .BI "-page=" "pagename"
663 options.
664 .TP
665 .BI "-find=" text
666 Highlight occurrences of the given string
667 .IR text .
668 This option works when the document contains a hidden
669 text layer. It can be used in conjunction with
670 .BR "-sidebar=find"
671 to display the text searching interface.
672
673 String
674 .I text
675 can be terminated by slash
676 .BR "" "(" "/" ")"
677 followed by letters specifying search options.
678 The following letters are recognized
679 .br
680 .TS
681 center,box;
682 lfB l
683 lfB l
684 lfB l
685 lfB l
686 lfB l
687 lfB l
688 .
689 c Case-sensitive search.
690 C Case-insensitive search (default).
691 w Search hits start on word boundaries (default).
692 W Ignore word boundaries.
693 r Regular expression search.
694 R String search (default).
695 .TE
696 .PP
697
698 .TP
699 .BI "-rotate=(0|90|180|270)"
700 Rotate the djvu image by the specified angle expressed
701 in degrees counter-clockwise.
702
703 .TP
704 .BI "-print=(yes|no)"
705 Enable or disable printing the DjVu document.
706 Printing is enabled by default.
707
708 .TP
709 .BI "-save=(yes|no)"
710 Enable or disable saving the DjVu document.
711 Saving is enabled by default.
712
713 .TP
714 .BI "-passive"
715 Cause the DjVu image to be displayed in a manner similar
716 to an ordinary web image.
717 The default zoom factor is changed to
718 .BR page .
719 The toolbar, the status bar, the scrollbars,
720 the menus, and the keyboard shortcuts are disabled.
721
722 .TP
723 .BI "-passivestretch"
724 Cause the DjVu image to be displayed in a manner similar
725 to an ordinary web image.
726 The default zoom factor is changed to
727 .BR stretch .
728 The toolbar, the status bar, the scrollbars,
729 the menus, and the keyboard shortcuts are disabled.
730
731 .TP
732 .BI "-nomenu, -notoolbar, -noscrollbars"
733 These options were recognized by some versions
734 of the DjVu viewers and are honored for the sake
735 of backward compatibility.
736 A warning message is printed
737 when option
738 .BR -verbose
739 is active.
740
741 .TP
742 .BI "-logo, -textsel, -search"
743 These options were recognized by some versions
744 of the DjVu viewers but are currently
745 not implemented by
746 .BR djview4 .
747 A warning message is printed
748 when option
749 .BR -verbose
750 is active.
751
752
753 .SH USAGE
754
755 Most features can be accessed using the menus,
756 the toolbar, the side bar or the pop-up menu
757 shown when the right mouse button is depressed over a DjVu image.
758 Detailed help can be accessed by clicking the contextual
759 help icon from the toolbar and then clicking on various
760 section of the djview user interface.
761
762 The following table lists some useful key combinations
763 recognized when the djvu document is active:
764 .PP
765 .TS
766 center,box;
767 lfB lfB
768 l l
769 l l
770 l l
771 l l
772 l l
773 l l
774 l l
775 l l
776 l l
777 l l
778 l l
779 l l
780 l l
781 l l
782 l l
783 l l
784 l l
785 .
786 Key Action
787 =
788 SHIFT+F1 Activate the contextual help.
789 1,2, and 3 Change zoom to to 100%, 200% and 300%.
790 Up, Down, Left, Right Scroll the image in the given direction.
791 Home Display top left corner of the image.
792 End Display bottom right corner of the image.
793 Control+Home Go to the beginning of the document.
794 Control+End Go to the end of the document.
795 Space, Return Scroll down or go to next page.
796 Backspace Scroll up or go to previous page.
797 Page Down Go to the next page.
798 Page Up Go to the previous page.
799 +, - Zoom in and out.
800 [, ] Rotate image.
801 W Select the "Fit Width" zooming mode.
802 P Select the "Fit Page" zooming mode.
803 CTRL+F, F3 Search the hidden text layer.
804 CTRL+G Go to a specific page by name or by number.
805 .TE
806 .PP
807 Handy effects can be achieved by holding modifier keys.
808 Although these keys are configurable from the preference dialog,
809 the following table lists the default assignments
810 .PP
811 .TS
812 center,box;
813 lfB lfB
814 l l
815 l l
816 l l
817 .
818 Key Action
819 =
820 CTRL+SHIFT Hold these keys to show the magnification lens.
821 CTRL Hold this key to select an area with the mouse.
822 SHIFT Hold this key to display all hyperlinks.
823 .TE
824 .PP
825
826
827 .SH ENVIRONMENT
828 Setting environment variable
829 .BR DJVIEW_VERBOSE
830 to a nonzero value is equivalent to calling
831 .BR djview
832 with option
833 .BR -verbose .
834 Setting environment variable
835 .BR DJVIEW_OPENGL
836 to values 0 or 1 overrides the preference
837 settings regarding OpenGL rendering.
838
839 When the user clicks on a djvu hyperlink pointing to a web page, the program
840 first tries to execute the web browser programs whose names are listed in the
841 colon separated environment variable
842 .BR BROWSER ,
843 then tries sensible platform dependent defaults.
844
845 The user interface language is determined by first trying
846 to find a complete set of translation files for the
847 language specified in the preference dialog, then
848 for the ISO 639 languages specified in the colon separated
849 environment variable
850 .BR LANGUAGE ,
851 and finally the language specified by the system locale.
852 If all these searches fail, the user interface language
853 reverts to the english default.
854
855 .SH CREDITS
856 This program was written by L\('eon Bottou <[email protected]>
857 and is distributed under the GNU General Public License.
858 This program includes code derived from program
859 .BR tiff2pdf ,
860 written by Ross Finlayson and
861 released under a BSD license.
862
863
864 .SH SEE ALSO
865 .BR djvu (1),
866 .BR ddjvu (1),
867 .BR nsdejavu (1),
868 .BR tiff2pdf (1)