branch: externals/preview-tailor
commit 5edd89fe650d40992a7af3b8f49902a06b9cbdb1
Author: Paul Nelson <ultr...@gmail.com>
Commit: Paul Nelson <ultr...@gmail.com>
update docs
---
README.org | 35 ++++++++++++++++-------------------
preview-tailor.el | 2 ++
2 files changed, 18 insertions(+), 19 deletions(-)
diff --git a/README.org b/README.org
index 52066a0ff1..284ea5b273 100644
--- a/README.org
+++ b/README.org
@@ -2,36 +2,33 @@
#+author: Paul Nelson
* Overview
-The
[[https://www.gnu.org/software/auctex/manual/preview-latex/preview-latex.html][preview]]
feature of [[https://www.gnu.org/software/auctex/][AUCTeX]] provides live
rendering of TeX code. The rendering occurs at a user-specified preview scale.
The appropriate scale to use depends upon your monitor and your text scale.
This package makes the preview scale vary in a natural way with the text scale
and the monitor. In particular, it provides the command =M-x
preview-tailor-set-multipl [...]
+The
[[https://www.gnu.org/software/auctex/manual/preview-latex/preview-latex.html][preview]]
feature of [[https://www.gnu.org/software/auctex/][AUCTeX]] provides live
rendering of TeX code at a user-specified preview scale. The appropriate scale
depends on your monitor and text scale. This package makes the preview scale
vary in a natural way with the text scale and the monitor. It provides the
command =M-x preview-tailor-set-multiplier= that allows you to adjust the
preview scale for [...]
* Configuration
Download this repository, install using =M-x package-install-file= (or
package-vc-install, straight, elpaca, ...), and add something like the
following to your [[https://www.emacswiki.org/emacs/InitFile][init file]]:
#+begin_src elisp
(use-package preview-tailor
- :after latex
+ :after preview
+ :demand
:config
- (preview-tailor-init))
+ (preview-tailor-init)
+ :hook
+ (kill-emacs . preview-tailor-save))
#+end_src
The function =preview-tailor-init= sets the customization variable
=preview-scale-function= to a function internal to this package that provides
the calculation, so make sure you don't modify that variable elsewhere in your
init file.
* Usage
-This package calculates the preview scale by multiplying together four factors:
+To adjust the multiplier for the current monitor, use =M-x
preview-tailor-set-multiplier=.
-1. The result of =preview-scale-from-face=.
-2. The current text scale factor (as tweaked via the =text-scale-adjust=
commands bound by default to =C-x C-+= and =C-x C--=)
-3. A multiplier determined by the current frame's monitor attributes, with
default value 1.
-4. An additional factor provided by the user customization
=preview-tailor-additional-factor-function= (which defaults to nil, which means
to omit this factor).
-5. The buffer-local variable =preview-tailor-local-multiplier= (which defaults
to 1).
-
-To adjust the multiplier for a given monitor, use =M-x
preview-tailor-set-multiplier=. This adjusts the customization variable
=preview-tailor-multipliers=, which is an association list mapping lists of
monitor attributes to numbers. The multiplier is calculated by finding the
first entry in the list all of whose attributes match the current ones.
-
-* Saving your settings
-The package stores your monitor-specific settings in the dotfile
".preview-tailor" inside your user-emacs-directory. This allows you to keep
your settings separate from your init file, making it easier to sync your Emacs
configuration across different computers.
+* Implementation details and refinements
+The monitor-specific multipliers are stored in the variable
=preview-tailor-multipliers=, an association list mapping lists of monitor
attributes to numbers. The multiplier is calculated by finding the first entry
in the list that matches the current monitor's attributes. These multipliers
are saved for future sessions in the dotfile =.preview-tailor= inside your
=user-emacs-directory=. This separation keeps monitor settings, which may be
specific to a given computer, independent of y [...]
-To save your multipliers for future sessions, use =M-x preview-tailor-save=.
The package will automatically load the settings from the dotfile when
initialized. To make saving automatic, you can add the following to your init
file:
+The preview scale is determined by multiplying five factors:
-#+begin_src elisp
-(add-hook 'kill-emacs-hook #'preview-tailor-save)
-#+end_src
+1. The result of =preview-scale-from-face=.
+2. The current text scale factor (adjusted via the =text-scale-adjust=
commands, default bindings =C-x C-+= and =C-x C--=).
+3. A multiplier based on the current frame's monitor attributes, set via =M-x
preview-tailor-set-multiplier=, defaulting to 1.
+4. An additional factor provided by the user customization
=preview-tailor-additional-factor-function= (default is =nil=, meaning this
factor is omitted).
+5. The buffer-local variable =preview-tailor-local-multiplier=, which defaults
to 1.
-If you prefer to edit the dotfile directly, the function =preview-tailor-load=
might be come in handy -- it loads the settings from the dotfile into the
variable =preview-tailor-multipliers=.
+The last two factors add convenience for varying the preview scale in
different settings. For example, I use preview in both =LaTeX-mode= and
=lean4-mode=, with different preview scales. This is because I use
=buffer-face-mode= in =LaTeX-mode=, but not in =lean4-mode=. To achieve this, I
add a function to =lean4-mode-hook= that sets =preview-tailor-local-multiplier=
to 0.7.
diff --git a/preview-tailor.el b/preview-tailor.el
index 311e7756f3..acf6eb2b02 100644
--- a/preview-tailor.el
+++ b/preview-tailor.el
@@ -35,6 +35,8 @@
;; future sessions, use
;;
;; M-x preview-tailor-save
+;;
+;; See README.org for further details.
;;; Code:
