changeset 100081:a156a334252a

(Document View): Explain dependence on gs at the top. Copyedits.

--- a/doc/emacs/misc.texi	Sun Nov 30 22:57:36 2008 +0000
+++ b/doc/emacs/misc.texi	Sun Nov 30 22:57:43 2008 +0000
@@ -6,13 +6,13 @@
 @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
 
@@ -22,40 +22,52 @@
 
 @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.
@@ -68,55 +80,53 @@
 @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
+@findex doc-view-show-tooltip
+  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; 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.
+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
@@ -127,12 +137,12 @@
 
 @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?
@@ -143,7 +153,7 @@
 @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.
 
@@ -151,26 +161,22 @@
 @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.