diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 153 |
1 files changed, 153 insertions, 0 deletions
diff --git a/README.md b/README.md new file mode 100644 index 0000000..52f7eea --- /dev/null +++ b/README.md @@ -0,0 +1,153 @@ +![][image] + +## About + +`nov.el` provides a major mode for reading EPUB documents. + +Features: + +- Basic navigation (jump to TOC, previous/next chapter) +- Remembering and restoring the last read position +- Jump to next chapter when scrolling beyond end +- Storing and following Org links to EPUB files +- Renders EPUB2 (.ncx) and EPUB3 (<nav>) TOCs +- Hyperlinks to internal and external targets +- Supports textual and image documents +- Info-style history navigation +- View source of document files +- Metadata display +- Image rescaling + +## Screenshot + +![][screenshot] + +## Installation + +Set up the [MELPA] or [MELPA Stable] repository if you haven't already +and install with `M-x package-install RET nov RET`. + +## Setup + +Make sure you have an `unzip` executable on `PATH`, otherwise the +extraction of EPUB files will fail. If you for some reason have +`unzip` in a non-standard location, customize `nov-unzip-program` to +its path. You'll also need an Emacs compiled with `libxml2` support, +otherwise rendering will fail. + +Put the following in your init file: + + (add-to-list 'auto-mode-alist '("\\.epub\\'" . nov-mode)) + +## Customization + +While the defaults make for an acceptable reading experience, it can +be improved with any of the following changes: + +### Default font + +To change the default font, use `M-x customize-face RET +variable-pitch`, pick a different family, save and apply. If you +dislike globally customizing that face, add the following to your init +file: + + (defun my-nov-font-setup () + (face-remap-add-relative 'variable-pitch :family "Liberation Serif" + :height 1.0)) + (add-hook 'nov-mode-hook 'my-nov-font-setup) + +To completely disable the variable pitch font, customize +`nov-variable-pitch` to `nil`. Text will be displayed with the +default face instead which should be using a monospace font. + +### Text width + +By default text is filled by the window width. You can customize +`nov-text-width` to a number of columns to change that: + + (setq nov-text-width 80) + +It's also possible to set it to `t` to inhibit text filling, this can +be used in combination with `visual-line-mode` and packages such as +`visual-fill-column` to implement more flexible filling: + + (setq nov-text-width t) + (setq visual-fill-column-center-text t) + (add-hook 'nov-mode-hook 'visual-line-mode) + (add-hook 'nov-mode-hook 'visual-fill-column-mode) + +### Rendering + +In case you're not happy with the rendering at all, you can either use +`nov-pre-html-render-hook` and `nov-post-html-render-hook` to adjust +the HTML before and after rendering or use your own rendering function +by customizing `nov-render-html-function` to one that replaces HTML in +a buffer with something nicer than the default output. + +Here's an advanced example of text justification with the [justify-kp] +package: + + (require 'justify-kp) + (setq nov-text-width t) + + (defun my-nov-window-configuration-change-hook () + (my-nov-post-html-render-hook) + (remove-hook 'window-configuration-change-hook + 'my-nov-window-configuration-change-hook + t)) + + (defun my-nov-post-html-render-hook () + (if (get-buffer-window) + (let ((max-width (pj-line-width)) + buffer-read-only) + (save-excursion + (goto-char (point-min)) + (while (not (eobp)) + (when (not (looking-at "^[[:space:]]*$")) + (goto-char (line-end-position)) + (when (> (shr-pixel-column) max-width) + (goto-char (line-beginning-position)) + (pj-justify))) + (forward-line 1)))) + (add-hook 'window-configuration-change-hook + 'my-nov-window-configuration-change-hook + nil t))) + + (add-hook 'nov-post-html-render-hook 'my-nov-post-html-render-hook) + +This customization yields the following look: + +![][screenshot-kp] + +## Usage + +Open the EPUB file with `C-x C-f ~/novels/novel.epub`, scroll with +`SPC` and switch chapters with `n` and `p`. More keybinds can be +looked up with `F1 m`. + +## Bugs + +Invalid EPUB documents are *not* supported. Please use [epubcheck] to +validate yours when running into an error. + +In case the bug is specific to an EPUB document, please send attach it +to your email. I'll try my best to figure out the error, but chances +are you can figure it out as well by using the source view (bound to +``v`` for the current document and ``V`` for the content file) to spot +the problematic XML. + +## Alternatives + +The first one I've heard of is [epubmode.el] which is, well, see for +yourself. You might find [ereader] more useful, especially if you're +after Org integration and annotation support. + +[image]: img/novels.gif +[screenshot]: img/scrot.png +[MELPA]: https://melpa.org/ +[MELPA Stable]: https://stable.melpa.org/ +[justify-kp]: https://github.com/Fuco1/justify-kp +[screenshot-kp]: img/justify-kp.png +[epubcheck]: https://github.com/IDPF/epubcheck +[epubmode.el]: https://www.emacswiki.org/emacs/epubmode.el +[ereader]: https://github.com/bddean/emacs-ereader |