# HG changeset patch # User Richard M. Stallman # Date 1225510074 0 # Node ID 2f4e59d3928501e4f552d2f9481bd22f525db694 # Parent ef372a9c419738cc34c520af2a202f361414a3c6 (Document View): Major rewrite. diff -r ef372a9c4197 -r 2f4e59d39285 doc/emacs/misc.texi --- a/doc/emacs/misc.texi Sat Nov 01 02:21:24 2008 +0000 +++ b/doc/emacs/misc.texi Sat Nov 01 03:27:54 2008 +0000 @@ -21,42 +21,41 @@ @end ifnottex @node Document View, Gnus, Calendar/Diary, Top - @section Document Viewing -@cindex mode, pdf, ps, dvi +@cindex DVI file viewing +@cindex PDF file +@cindex PS file @cindex DocView mode @cindex mode, DocView -@cindex document files +@cindex document viewer (DocView) @findex doc-view-mode -DocView mode is a document viewer for Emacs (@code{doc-view-mode}). -It's capable of displaying PDF, PS and DVI files inside an Emacs buffer -and provides some convenience features like slicing, zooming and -searching inside the document. - -@vindex doc-view-cache-directory -This is done by using @command{gs} (GhostScript) to convert the document -to a set of PNG images which are then displayed. In order to omit -double conversions of documents those images are cached in -@code{doc-view-cache-directory}. - -@findex doc-view-minor-mode +DocView mode (@code{doc-view-mode}) is a document viewer that operates +within Emacs. It provides convenience features such as slicing, +zooming, and searching inside the document. + @findex doc-view-toggle-display -By default Emacs opens all pdf and dvi files using DocView mode. You'll -be greeted with a welcome screen and as soon as the first page's -conversion finished, it'll be displayed. PostScript files are opened -with @code{ps-mode} by default, but additionally -@code{doc-view-minor-mode} is enabled, which adds the binding @kbd{C-c -C-c} (@code{doc-view-toggle-display}) and toggles between the editing -mode (@code{ps-mode} in case of PS files, @code{fundamental-mode} in -case of PDF or DVI files) and DocView mode. +When you visit a PDF or DVI file, Emacs begins in DocView mode: it +displays a welcome screen and begins formatting the file, page by +page. It displays the first page once that has been formatted. You +can use @kbd{C-c C-c} (@code{doc-view-toggle-display}) to switch to +editing the text of the PDF or DVI file. + +@findex doc-view-toggle-display +For Postscript files, Emacs normally visits them in PS mode, but you +can use @kbd{C-c C-c} to switch to viewing the formatted text with +DocView. For all these files, repeating @kbd{C-c C-c} toggles between +DocView and the file text. @findex doc-view-enlarge @findex doc-view-shrink -You can enlarge or shrink the document with @kbd{+} -(@code{doc-view-enlarge}) and @kbd{-} (@code{doc-view-shrink}). - -The DocView buffer can be buried with @kbd{q} and killed with @kbd{k}. +@vindex doc-view-resolution +When in DocView mode, you can enlarge or shrink the document with +@kbd{+} (@code{doc-view-enlarge}) and @kbd{-} +(@code{doc-view-shrink}). To specify the default size for DocView, +set or customize the variable @code{doc-view-resolution}. + +You can kill the DocView buffer with @kbd{k} and bury it with @kbd{q}. @menu * Navigation:: Navigation inside DocView buffers. @@ -68,24 +67,22 @@ @node Navigation @subsection Navigation -Inside DocView mode you can scroll the current page using the usual -Emacs movement keys, that is the arrow keys or @kbd{C-p}, @kbd{C-n}, +When in DocView mode, you can scroll the current page using the usual +Emacs movement keys; that is, the arrow keys or @kbd{C-p}, @kbd{C-n}, @kbd{C-b} and @kbd{C-f}. @findex doc-view-next-page @findex doc-view-previous-page -To go to the next page use @kbd{n}, @kbd{@key{next}} or @kbd{C-x ]} -(@code{doc-view-next-page}), to go to the previous page use @kbd{p}, -@kbd{@key{prior}} or @kbd{C-x [} (@code{doc-view-previous-page}). +To go to the next page, use @kbd{n}, @key{next} or @kbd{C-x ]} +(@code{doc-view-next-page}). To go to the previous page, use @kbd{p}, +@key{prior} or @kbd{C-x [} (@code{doc-view-previous-page}). @findex doc-view-scroll-up-or-next-page @findex doc-view-scroll-down-or-previous-page -While reading a document it's convenient to scroll the current page and -switch to the next one if it's already scrolled to the bottom. This -functionality is bound to @kbd{@key{SPC}} -(@code{doc-view-scroll-up-or-next-page}). @kbd{@key{DEL}} will do the -same in the other direction -(@code{doc-view-scroll-down-or-previous-page}). +The @key{SPC} (@code{doc-view-scroll-up-or-next-page}) key is a +convenient way to advance through the document. It scrolls within the +current page or advances to the next. @key{DEL} moves backwards in a +similar way direction (@code{doc-view-scroll-down-or-previous-page}). @findex doc-view-first-page @findex doc-view-last-page @@ -99,79 +96,83 @@ @node Searching @subsection Searching -It's possible to search for a regular expression (@pxref{Regexps}) -inside documents. In order to do that, the document file will be -converted to text and the search will be performed in the text file. -The interface to searching is inspired by @code{isearch} -(@pxref{Incremental Search}). +While in DocView mode you can search the file's text for a regular +expression (@pxref{Regexps}). The interface for searching is inspired +by @code{isearch} (@pxref{Incremental Search}). @findex doc-view-search @findex doc-view-search-backward -To initiate a search use @kbd{C-s} (@code{doc-view-search}) or @kbd{C-r} -(@code{doc-view-search-backward}). You'll be queried for a regular -expression and after hitting @kbd{@key{RET}} the number of matches will -be echoed. Navigation between the matches is done by pressing @kbd{C-s} -and @kbd{C-r} again. +To initiate a search use @kbd{C-s} (@code{doc-view-search}) or +@kbd{C-r} (@code{doc-view-search-backward}). This reads a regular +expression; after you finish it with @key{RET}, it echoes the number +of matches found. You can move forward and back among these matches +by typing @kbd{C-s} and @kbd{C-r}. @findex doc-view-show-tooltip -Since there's no possibility to show the match inside the image itself, -a tooltip will be shown at the mouse position which lists all matching -lines of the current page. You can force the tooltip to be shown with -@kbd{C-t} (@code{doc-view-show-tooltip}). - -To initiate a new search call @code{doc-view-search} with a prefix -argument, i.e. @kbd{C-u C-s} or @kbd{C-u C-r} for a backward search. +DocView mode has no way to show the match inside the page image, so +instead it displays a tooltip (at the mouse position) which lists all +matching lines in the current page. You can force display of this +tooltip with @kbd{C-t} (@code{doc-view-show-tooltip}). + +To start a new search, use the search command with a prefix argument; +i.e., @kbd{C-u C-s} for a forward search or @kbd{C-u C-r} for a +backward search. @node Slicing @subsection Slicing -Quite often documents have huge margins for printing. These are -annoying when reading the document on a computer, because they use up -screen space and thus can force inconvenient scrolling. +Documents often have wide margins for printing. They are annoying +when reading the document on the screen, because they use up screen +space and can cause inconvenient scrolling. @findex doc-view-set-slice @findex doc-view-set-slice-using-mouse -To prevent you from that DocView lets you select the slice of the pages -you're interested in. To do that hit @kbd{s s} -(@code{doc-view-set-slice}) to enter the top left pixel position and the -slice's width and height. A more convenient method is provided by -@kbd{s m} (@code{doc-view-set-slice-using-mouse}), where you use the -mouse to select the slice. +With DocView you can hide these margins by selecting the @dfn{slice} +of pages to display. A slice is a rectangle within the page area; +once you specify a slice in DocView, it applies to whichever page you +look at. + +To specify the slice numerically, type @kbd{s s} +(@code{doc-view-set-slice}); then enter the top left pixel position +and the slice's width and height. +@c ??? how does this work? + + A more convenient graphical way to specify the slice is with @kbd{s +m} (@code{doc-view-set-slice-using-mouse}), where you use the mouse to +select the slice. +@c ??? How does this work? @findex doc-view-reset-slice -To reset the selected slice use @kbd{s r} (@code{doc-view-reset-slice}). +To cancel the selected slice, type @kbd{s r} +(@code{doc-view-reset-slice}). Then DocView shows the entire page +including its entire margins. @node Conversion @subsection Conversion -As said before DocView mode will automatically convert the document -files when visiting them unless @code{doc-view-cache-directory} already -contains the converted PNG images. In that case it'll use the cached -files. +@vindex doc-view-cache-directory +DocView works by using @command{gs} (GhostScript) to convert the +document to a set of PNG images which are then displayed. For +efficiency it caches those images in @code{doc-view-cache-directory}. @findex doc-view-clear-cache -You can clean up the cache directory with @code{M-x -doc-view-clear-cache}. - -If a document has changed, it'll be converted anew when visiting it. -DocView recognizes documents by the md5 sum of their contents. +You can clear the cache directory with @code{M-x +doc-view-clear-cache}. But this should never be necessary, because +DocView detects changed files based on the md5 checksum of the file +contents. @findex doc-view-kill-proc @findex doc-view-kill-proc-and-buffer -To force a reconversion of the currently viewed document hit @kbd{r} or -@kbd{g} (@code{revert-buffer}). Killing the converter process -associated with the current buffer can be done with @kbd{K} -(@code{doc-view-kill-proc}). The key @kbd{k} will do the same and -additionally kill the DocView buffer -(@code{doc-view-kill-proc-and-buffer}). +To force a reconversion of the currently viewed document, type @kbd{r} +or @kbd{g} (@code{revert-buffer}). To kill the converter process +associated with the current buffer, type @kbd{K} +(@code{doc-view-kill-proc}). The command @kbd{k} +(@code{doc-view-kill-proc-and-buffer}) kills the converter process and +the DocView buffer. The zoom commands @kbd{+} (@code{doc-view-enlarge}) and @kbd{-} -(@code{doc-view-shrink}) will also reconvert the current document using -another resolution. The current page will be converted first. - -@vindex doc-view-resolution -The default resolution for conversion can be customized via the variable -@code{doc-view-resolution}. +(@code{doc-view-shrink}) need to reconvert the document at the new +size. The current page is converted first. @node Gnus, Shell, Document View, Top @section Gnus