changeset 99272:e8b894273bf9

(Files): Add a section about document files (doc-view-mode).

--- a/doc/emacs/ChangeLog	Fri Oct 31 06:24:56 2008 +0000
+++ b/doc/emacs/ChangeLog	Fri Oct 31 09:31:43 2008 +0000
@@ -1,3 +1,8 @@
[phone]  Tassilo Horn  <[e-mail]>
+
+	* files.texi (Files): Add a section about document
+	files (doc-view-mode).
+
 2008-10-31  Chong Yidong  <[e-mail]>
 
 	* building.texi (Compilation Mode): Document

--- a/doc/emacs/files.texi	Fri Oct 31 06:24:56 2008 +0000
+++ b/doc/emacs/files.texi	Fri Oct 31 09:31:43 2008 +0000
@@ -37,6 +37,7 @@
 * Misc File Ops::       Other things you can do on files.
 * Compressed Files::    Accessing compressed files.
 * File Archives::       Operating on tar, zip, jar etc. archive files.
+* Document Files::      Viewing PDF, PS and DVI files.
 * Remote Files::        Accessing files on other sites.
 * Quoted File Names::   Quoting special characters in file names.
 * File Name Cache::     Completion against a list of files you often use.
@@ -2988,6 +2989,160 @@
 need these programs to look at the archive table of contents, only to
 extract or manipulate the subfiles in the archive.
 
+
+@node Document Files
+@section Document Files
+@cindex mode, pdf, ps, dvi
+@cindex DocView mode
+@cindex mode, DocView
+@cindex document files
+@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
+@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.
+
+@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}.
+
+@menu
+* Navigation::	Navigation inside DocView buffers.
+* Searching::	Searching inside documents.
+* Slicing::	Specifing which part of pages should be displayed.
+* Conversion::	Influencing and triggering converison.
+@end menu
+
+@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},
+@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}).
+
+@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}).
+
+@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}).
+
+@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}).
+
+@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.
+
+@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.
+
+@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.
+
+@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.
+
+@findex doc-view-reset-slice
+To reset the selected slice use @kbd{s r} (@code{doc-view-reset-slice}).
+
+@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.
+
+@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.
+
+@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}).
+
+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}.
+
+
 @node Remote Files
 @section Remote Files