Binder
Binder is global minor mode to facilitate working on a writing project in multiple files. It is heavily inspired by the binder feature in the macOS writing app Scrivener.
The rationale behind working this way is to split a large writing project into smaller pieces.
Features
Primarily, Binder provides a global minor mode binder-mode. This
allows working with files in the current binder-project-directory.
Data concerning these files is saved in a .binder.el file in the
project directory.
A project can be thought of an ordered list of files with associated notes and tags.
Navigation
At the most basic level, you can navigate back and forth through the files in a project:
binder-next (C-c ])visits the next file in the projectbinder-previous (C-c [)visits the previous
Calling these commands activates a transient map so that each command can be repeated without the prefix key.
Sidebar
You'll mostly interact with the project structure via the sidebar.
binder-toggle-sidebar (C-c ')toggles the visibility of the binder sidebarbinder-reveal-in-sidebar (C-c ;)finds the current file in the sidebar
Each project item is a file reference relative to the project directory.
Project items are displayed in a linear ordered list. Calling
binder-sidebar-find-file (RET) or binder-sidebar-find-file-other-window (o)
will visit the corresponding file.
Each item in the sidebar displays the following information:
*denotes that this item has some notes (see Notes below), or...?denotes that the item's corresponding file cannot be found- either the file relative to the project directory, or an arbitrary display name
#tag1 #tag2 ...arbitrary item tags (see Tags below)
An item's display name can be changed with binder-sidebar-rename (r).
If a file cannot be found, relocate with binder-sidebar-relocate (R).
Calling binder-sidebar-find-file (RET) will visit the corresponding
file.
To add an existing file, call binder-sidebar-add-file (a) or add all
files in directory with binder-sidebar-add-all-files (A).
Add a new file with binder-sidebar-new-file (M-RET). This prompts for a
file-name and adds this (possibly non-existent) file to the project
after the current file's index. If no file-name extension is provided,
use binder-default-file-extension.
Hint: you can use an alternate default file extension for different projects by setting a directory local variable.
Files can also be added to a project from outside the sidebar with
binder-add-file (C-c :).
Items can be reordered with binder-sidebar-shift-up (M-p | M-up) and
binder-sidebar-shift-down (M-n | M-down).
Remove items with binder-sidebar-remove (d) -- this does not delete
the files, only removes them from the project, but it does delete the
corresponding notes and tags.
Hide item file extensions by setting the binder-sidebar-hide-file-extensions
option. This can be toggled with binder-sidebar-toggle-file-extensions (E).
The sidebar can be resized with binder-sidebar-shrink-window ({) and
binder-sidebar-enlarge-window (}). The window size is changed by the
number of columns specified in option binder-sidebar-resize-window-step.
You can customize how the sidebar window is displayed by setting
binder-sidebar-display-alist option.
Notes
To open the notes buffer from the sidebar, call either
binder-sidebar-open-notes (z) to open and select the notes window, or
binder-sidebar-toggle-notes (i) to toggle the window.
To open a project file's notes from outside the sidebar, call
binder-toggle-notes (C-c ").
You need to call either binder-notes-save (C-x C-s) or
binder-notes-save-and-quit-window (C-c C-c) to save notes to the
project file.
Calling quit-window (C-c C-q | C-c C-k) or binder-toggle-sidebar
does not save notes.
You can embiggen the notes window, to pop it out from the sidebar and
edit like a regular buffer window, with binder-notes-expand-window (C-c C-l).
You can customize how the notes window is displayed by setting
binder-notes-display-alist option.
Tags
Tags can help organize a project. An item can have any number of tags.
Add a tag to an item with binder-sidebar-add-tag (t). Remove a tag
from an item with binder-sidebar-remove-tag (T). You can tag/untag
multiple items at once by using marks (see Marking below).
Items in the sidebar can be narrowed to only show items with a certain
tag with binder-sidebar-narrow-by-tag (/) and/or only show items
without a certain tag with binder-sidebar-exclude-by-tag (\). Each of
these commands can be called multiple times with additional tags.
Clear the sidebar filters with binder-sidebar-clear-filters (|).
Marking
Multiple items can be marked to add tags, toggle include state or
delete. Call binder-sidebar-mark (m) to mark an item or
binder-sidebar-unmark (u) to unmark an item.
To unmark all sidebar items, call binder-sidebar-unmark-all (U).
Requirements
- Emacs 24.4
- seq 2.20 (part of Emacs 25 and later)
Installation
The latest stable release of Binder is available via MELPA-stable. First, add MELPA-stable to your package archives:
M-x customize-option RET package-archives RET
Insert an entry named melpa-stable with URL:
https://stable.melpa.org/packages/
You can then find the latest stable version of binder in the list
returned by:
M-x list-packages RET
If you prefer the latest but perhaps unstable version, do the above using MELPA.
Advanced Installation
Download the latest tagged release, move this file into your load-path
and add to your init.el file:
(require 'binder)
(require 'binder-tutorial) ;; optional
If you wish to contribute to or alter Binder's code, clone the repository into your load-path and require as above:
git clone https://github.com/rnkn/binder.git
Bugs and Feature Requests
Send me an email (address in the package header). For bugs, please ensure you can reproduce with:
$ emacs -Q -l binder.el
Known issues are tracked with FIXME comments in the source.
Tutorial
Binder comes with a tutorial. Calling M-x binder-tutorial will prompt
for an empty directory in which to generate the tutorial files.