@chapter Miscellaneous Commands
This chapter contains several brief topics that do not fit anywhere
-else: reading netnews, running shell commands and shell subprocesses,
-using a single shared Emacs for utilities that expect to run an editor
-as a subprocess, printing hardcopy, sorting text, narrowing display to
-part of the buffer, editing double-column files and binary files,
-saving an Emacs session for later resumption, following hyperlinks,
-browsing images, emulating other editors, and various diversions and
-amusements.
+else: viewing ``document files'', reading netnews, running shell
+commands and shell subprocesses, using a single shared Emacs for
+utilities that expect to run an editor as a subprocess, printing
+hardcopy, sorting text, narrowing display to part of the buffer,
+editing double-column files and binary files, saving an Emacs session
+for later resumption, following hyperlinks, browsing images, emulating
+other editors, and various diversions and amusements.
@end iftex
@node Document View, Gnus, Calendar/Diary, Top
@section Document Viewing
-@cindex DVI file viewing
+@cindex DVI file
@cindex PDF file
@cindex PS file
+@cindex Postscript file
@cindex DocView mode
@cindex mode, DocView
@cindex document viewer (DocView)
@findex doc-view-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.
+DocView mode (@code{doc-view-mode}) is a viewer for DVI, Postscript
+(PS), and PDF documents. It provides features such as slicing,
+zooming, and searching inside documents. It works by converting the
+document to a set of images using the @command{gs} (GhostScript)
+command, and displaying those images.
@findex doc-view-toggle-display
-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.
+@cindex doc-view-minor-mode
+ When you visit a PDF or DVI file, Emacs automatically switches to
+DocView mode. When you visit a Postscript file, Emacs switches to PS
+mode, a major mode for editing Postscript files as text; however, it
+also enables DocView minor mode, so you can type @kbd{C-c C-c} to view
+the document with DocView. (PDF and DVI files, unlike Postscript
+files, are not usually human-editable.) In either case, repeating
+@kbd{C-c C-c} (@code{doc-view-toggle-display}) toggles between DocView
+and the file text.
+
+ You can explicitly toggle DocView mode with the command @code{M-x
+doc-view-mode}, and DocView minor mode with the command @code{M-x
+doc-view-minor-mode}.
+
+ When DocView mode starts, it displays a welcome screen and begins
+formatting the file, page by page. It displays the first page once
+that has been formatted.
@findex doc-view-enlarge
@findex doc-view-shrink
@vindex doc-view-resolution
-When in DocView mode, you can enlarge or shrink the document with
+ 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}.
+ To kill the DocView buffer, type @kbd{k}
+(@code{doc-view-kill-proc-and-buffer}). To bury it, type @kbd{q}
+(@code{quit-window}).
@menu
* Navigation:: Navigation inside DocView buffers.
@subsection Navigation
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}.
+Emacs movement keys: @kbd{C-p}, @kbd{C-n}, @kbd{C-b}, @kbd{C-f}, and
+the arrow keys.
@findex doc-view-next-page
@findex 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}).
+ To display the next page, type @kbd{n}, @key{next} or @kbd{C-x ]}
+(@code{doc-view-next-page}). To display the previous page, type
+@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
-The @key{SPC} (@code{doc-view-scroll-up-or-next-page}) key is a
+ 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}).
+similar way (@code{doc-view-scroll-down-or-previous-page}).
@findex doc-view-first-page
@findex doc-view-last-page
-To go to the first page use @kbd{M-<} (@code{doc-view-first-page}), to
-go to the last one use @kbd{M->} (@code{doc-view-last-page}).
-
@findex doc-view-goto-page
-To jump to a page by its number use @kbd{M-g M-g} or @kbd{M-g g}
-(@code{doc-view-goto-page}).
+ To go to the first page, type @kbd{M-<}
+(@code{doc-view-first-page}); to go to the last one, type @kbd{M->}
+(@code{doc-view-last-page}). To jump to a page by its number, type
+@kbd{M-g M-g} or @kbd{M-g g} (@code{doc-view-goto-page}).
@node Searching
@subsection Searching
-While in DocView mode you can search the file's text for a regular
+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}). 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
-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.
+ To begin a search, type @kbd{C-s} (@code{doc-view-search}) or
+@kbd{C-r} (@code{doc-view-search-backward}). This reads a regular
+expression using a minibuffer, then echoes the number of matches found
+within the document. You can move forward and back among the matches
+by typing @kbd{C-s} and @kbd{C-r}. DocView mode has no way to show
+the match inside the page image; instead, it displays a tooltip (at
+the mouse position) listing all matching lines in the current page.
+To force display of this tooltip, type @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
@findex doc-view-set-slice
@findex doc-view-set-slice-using-mouse
-With DocView you can hide these margins by selecting the @dfn{slice}
+ With DocView you can hide these margins by selecting a @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}
+ 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?
@c ??? How does this work?
@findex doc-view-reset-slice
-To cancel the selected slice, type @kbd{s r}
+ To cancel the selected slice, type @kbd{s r}
(@code{doc-view-reset-slice}). Then DocView shows the entire page
including its entire margins.
@subsection Conversion
@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 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.
+For efficiency, DocView caches the images produced by @command{gs}.
+The name of this directory is given by the variable
+@code{doc-view-cache-directory}. You can clear the cache directory by
+typing @code{M-x doc-view-clear-cache}.
@findex doc-view-kill-proc
@findex 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}
+ 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{-}
+ The zoom commands @kbd{+} (@code{doc-view-enlarge}) and @kbd{-}
(@code{doc-view-shrink}) need to reconvert the document at the new
size. The current page is converted first.
projects / emacs.git / commitdiff