Skip to content

rnkn/binder

master
Switch branches/tags
Code

Binder

MELPA Stable MELPA

screenshot

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 project
  • binder-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 sidebar
  • binder-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:

  1. * denotes that this item has some notes (see Notes below), or...
  2. ? denotes that the item's corresponding file cannot be found
  3. either the file relative to the project directory, or an arbitrary display name
  4. #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.

About

Emacs global minor mode facilitating multi-file writing projects

Topics

Resources

License

Stars

Watchers

Forks