branch: externals/doc-view-follow
commit e2f24261be0b0fbb5cd735aae731dc25e36a0f86
Author: Paul Nelson <ultr...@gmail.com>
Commit: Paul Nelson <ultr...@gmail.com>
Update doc-follow.el documentation and improve clarity
* README.org (Overview): Rewrite for clarity and provide more detailed
instructions on installation and usage.
(Installation): Add installation instructions with code example.
(Usage): Add explicit activation instructions and example workflow.
(Extensibility): Add new section about extending to other modes.
* doc-follow.el: Expand commentary section with clearer explanation of
functionality and usage instructions.
---
README.org | 38 +++++++++++++++++++++++++++++---------
doc-follow.el | 32 +++++++++++++++++++++++---------
2 files changed, 52 insertions(+), 18 deletions(-)
diff --git a/README.org b/README.org
index e1f149a713..20c098739e 100644
--- a/README.org
+++ b/README.org
@@ -1,21 +1,41 @@
-#+title: doc-follow.el: Synchronized dual window document viewing
+#+title: doc-follow.el: synchronize windows showing the same document
#+author: Paul Nelson
* Overview
-=doc-follow= is an Emacs package that synchronizes multiple windows showing
the same document in =doc-view-mode= or =pdf-view-mode= (with the list of
available modes customizable via =doc-follow-modes=). When you navigate to a
page in one window, the other windows automatically display neighboring pages.
A common setup is to have two pages side by side, in which case this mode gives
a book-like view.
+doc-follow.el provides a minor mode, =doc-follow-mode=, that automatically
synchronizes page navigation between multiple windows displaying the same
PS/PDF/DVI/DjVu document. In particular, this allows for a convenient "book
view," with two windows showing consecutive pages side-by-side.
* Installation
-Install =doc-follow= by, e.g., downloading the source and using =M-x
package-install-file=.
+You can install =doc-follow.el= by downloading the source file and running:
+
+#+begin_src emacs-lisp
+M-x package-install-file RET /path/to/doc-follow.el RET
+#+end_src
* Usage
-After installing the package, you can toggle it globally via =M-x
global-dual-doc-view-mode=, locally via =M-x doc-follow-mode=. To have it
activate by default, add =(global-dual-doc-view-mode)= to your config.
+After installation, you can activate the mode:
+
+- Globally: =M-x global-doc-follow-mode=
+- Locally: =M-x doc-follow-mode=
+
+To enable synchronization by default, add to your Emacs configuration:
+
+#+begin_src emacs-lisp
+(global-doc-follow-mode 1)
+#+end_src
+
+** Example workflow:
+
+1. Open a supported document in =doc-view-mode= or =pdf-view-mode=.
+ (=doc-view-mode= is built-in; =pdf-view-mode= requires
[[https://github.com/vedang/pdf-tools][pdf-tools]].)
+2. Split the frame vertically (with default bindings, via =C-x 3=).
+3. Activate =doc-follow-mode= if not already enabled.
+4. Navigate pages in either window with standard commands (e.g., =n=, =p=).
+
+Both windows will automatically stay synchronized.
-1. Open a document in =doc-view-mode= or =pdf-view-mode= (the latter being
part of the [[https://github.com/vedang/pdf-tools][pdf-tools]] package)
-2. Split the window (e.g., =C-x 3= for vertical split)
-3. Activate =doc-follow-mode= in either window (if not already activated)
-4. Navigate through the document in either window (e.g. =n= or =p= to navigate
by page)
+* Extensibility
-The package will automatically keep the two views in sync, with the second
always one page ahead of the first. It works similarly with more than two
windows.
+One could add support for additional document viewing modes via the
=doc-follow-modes= variable.
diff --git a/doc-follow.el b/doc-follow.el
index b14600a31b..9058ba7e10 100644
--- a/doc-follow.el
+++ b/doc-follow.el
@@ -1,4 +1,4 @@
-;;; doc-follow.el --- Sync two windows showing the same document -*-
lexical-binding: t; -*-
+;;; doc-follow.el --- synchronize windows showing the same document -*-
lexical-binding: t; -*-
;; Copyright (C) 2024 Paul D. Nelson
@@ -23,14 +23,28 @@
;;; Commentary:
-;; This package provides a minor mode, `doc-follow-mode', that
-;; synchronizes page navigation between windows displaying the same
-;; document, making it so that when you navigate to a page in one
-;; window, the other windows will navigate to neighboring pages.
-
-;; Supports `doc-view-mode' and `pdf-view-mode'. You can customize
-;; the `doc-follow-modes' variable to add support for additional
-;; document viewing modes or modify the behavior for existing modes.
+;; doc-follow.el provides a convenient way to synchronize page
+;; navigation between multiple windows displaying the same document
+;; (PS/PDF/DVI/DjVu, etc.).
+;;
+;; With `doc-follow-mode' enabled, navigating pages in one window
+;; automatically adjusts the other windows to show adjacent pages. In
+;; particular, this allows a "book view" where the document is shown
+;; in two side-by-side windows on consecutive pages.
+;;
+;; `doc-view-mode' (built-in to Emacs) and `pdf-view-mode' (from
+;; pdf-tools) are supported by default. Additional viewing modes can
+;; be added via the `doc-follow-modes' variable.
+;;
+;; Usage:
+;; - Enable globally: M-x global-doc-follow-mode
+;; - Enable locally: M-x doc-follow-mode
+;;
+;; Once activated, split your Emacs frame (e.g., vertically with
+;; \\[split-window-right]) and open your document in both windows.
+;; Navigating with standard commands (like 'n' for next page and 'p'
+;; for previous page) in one window automatically synchronizes the
+;; view in the other.
;;; Code:
