[Emacs-diffs] Changes to emacs/doc/emacs/files.texi,v

[Tassilo Horn]

CVSROOT:        /sources/emacs
Module name:    emacs
Changes by:     Tassilo Horn <tsdh>     08/10/31 09:31:43

Index: files.texi
===================================================================
RCS file: /sources/emacs/emacs/doc/emacs/files.texi,v
retrieving revision 1.42
retrieving revision 1.43
diff -u -b -r1.42 -r1.43
--- files.texi  22 Oct 2008 21:11:42 -0000      1.42
+++ files.texi  31 Oct 2008 09:31:43 -0000      1.43
@@ -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.
 
+
address@hidden Document Files
address@hidden Document Files
address@hidden mode, pdf, ps, dvi
address@hidden DocView mode
address@hidden mode, DocView
address@hidden document files
address@hidden 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.
+
address@hidden 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
address@hidden
+
address@hidden doc-view-minor-mode
address@hidden 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
address@hidden 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.
+
address@hidden doc-view-enlarge
address@hidden 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}.
+
address@hidden
+* Navigation:: Navigation inside DocView buffers.
+* Searching::  Searching inside documents.
+* Slicing::    Specifing which part of pages should be displayed.
+* Conversion:: Influencing and triggering converison.
address@hidden menu
+
address@hidden Navigation
address@hidden 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},
address@hidden and @kbd{C-f}.
+
address@hidden doc-view-next-page
address@hidden doc-view-previous-page
+To go to the next page use @kbd{n}, @address@hidden or @kbd{C-x ]}
+(@code{doc-view-next-page}), to go to the previous page use @kbd{p},
address@hidden@key{prior}} or @kbd{C-x [} (@code{doc-view-previous-page}).
+
address@hidden doc-view-scroll-up-or-next-page
address@hidden 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 @address@hidden
+(@code{doc-view-scroll-up-or-next-page}).  @address@hidden will do the
+same in the other direction
+(@code{doc-view-scroll-down-or-previous-page}).
+
address@hidden doc-view-first-page
address@hidden 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}).
+
address@hidden 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}).
+
address@hidden Searching
address@hidden 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}).
+
address@hidden doc-view-search
address@hidden 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 @address@hidden the number of matches will
+be echoed.  Navigation between the matches is done by pressing @kbd{C-s}
+and @kbd{C-r} again.
+
address@hidden 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
address@hidden (@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.
+
address@hidden Slicing
address@hidden 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.
+
address@hidden doc-view-set-slice
address@hidden 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
address@hidden m} (@code{doc-view-set-slice-using-mouse}), where you use the
+mouse to select the slice.
+
address@hidden doc-view-reset-slice
+To reset the selected slice use @kbd{s r} (@code{doc-view-reset-slice}).
+
address@hidden Conversion
address@hidden 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.
+
address@hidden 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.
+
address@hidden doc-view-kill-proc
address@hidden doc-view-kill-proc-and-buffer
+To force a reconversion of the currently viewed document hit @kbd{r} or
address@hidden (@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.
+
address@hidden doc-view-resolution
+The default resolution for conversion can be customized via the variable
address@hidden
+
+
 @node Remote Files
 @section Remote Files