aboutsummaryrefslogtreecommitdiff
path: root/binder.el
diff options
context:
space:
mode:
Diffstat (limited to 'binder.el')
-rw-r--r--binder.el220
1 files changed, 134 insertions, 86 deletions
diff --git a/binder.el b/binder.el
index 400b48a..0109663 100644
--- a/binder.el
+++ b/binder.el
@@ -25,37 +25,48 @@
;;; Commentary:
-;; # Binder #
+;; Binder
+;; ======
-;; Binder is global minor mode (and associated major modes) to facilitate
-;; working on a writing project in multiple files. It is heavily inspired
-;; by the binder feature in the [macOS writing app Scrivener][1].
+;; 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][3].
;; The rationale behind working this way is to split a large writing
-;; project into much smaller pieces.
+;; project into smaller pieces.
-;; [1]: https://www.literatureandlatte.com/scrivener/
-;; ## Features ##
+;; 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. (You can change the name of this file with the
-;; binder-default-file option.)
+;; project directory.
-;; ## Navigation ##
+;; A project can be thought of an ordered list of files with the following
+;; associated data:
+
+;; - item notes (see **Notes** below)
+;; - item tags (see **Tags** below)
+;; - item include state (see **Concatenating** below)
+
+
+;; 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 binder, and
-;; - binder-previous (C-c [) visits the previous.
+;; - 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 prefix key/s.
+;; can be repeated without the prefix key.
-;; ## Sidebar ##
+
+;; Sidebar
+;; -------
;; You'll mostly interact with the project structure via the sidebar.
@@ -71,13 +82,13 @@
;; These things mean:
+;; | key | description |
;; |------|-------------------------------------------------|
;; | x | item is included when concatenating the project |
;; | * | item has notes |
;; | ? | the item's corresponding file cannot be found |
;; | name | the file name (or custom display name) |
;; | #tag | arbitrary item tags |
-;; |------|-------------------------------------------------|
;; 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).
@@ -93,19 +104,19 @@
;; 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.
+;; > 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 :).
-;; 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.
-
;; 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).
@@ -116,105 +127,142 @@
;; You can customize how the sidebar window is displayed by setting
;; binder-sidebar-display-alist option.
-;; ### Marking ###
-;; Multiple items can be marked to add tags, toggle include state or
-;; delete.
+;; 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 ").
-;; Call binder-sidebar-mark (m) to mark an item and binder-sidebar-unmark (u)
-;; to unmark an item or binder-sidebar-unmark-all (U) for all sidebar items.
+;; 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.
-;; ### Tags ###
+;; Calling quit-window (C-c C-q | C-c C-k) or binder-toggle-sidebar
+;; does not save notes.
-;; A project is strictly a linear list. As your project grows, you may find
-;; the number of items becomes unweidly. Tags can help organize a project.
-;; An item can have any number of tags.
+;; 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.
+;; multiple items at once by using marks (see **Marking** below).
-;; Items listed 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. Reset the sidebar with binder-sidebar-refresh (g).
+;; 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.
-;; ## Notes ##
+;; Reset the sidebar filters with binder-sidebar-refresh (g).
-;; Project items can have notes, which are stored within the project file.
-;; 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 when visiting that file, call binder-toggle-notes
-;; (C-c ").
+;; Marking
+;; -------
-;; > n.b. Notes are not automatically saved.
+;; 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.
-;; Calling quit-window (C-c C-q | C-c C-k) or binder-toggle-sidebar
-;; does not save notes. You need to call either binder-notes-save (C-x C-s)
-;; or binder-notes-save-and-quit-window (C-c C-c).
+;; To unmark all sidebar items, call binder-sidebar-unmark-all (U).
-;; 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).
-;; If you want the notes buffer to stay in sync with the item under the
-;; cursor in the sidebar, change the option binder-notes-keep-in-sync. This
-;; can be disconcerting, and again, notes are not automatically saved!
+;; Concatenating
+;; -------------
-;; You can customize how the notes window is displayed by setting
-;; binder-notes-display-alist option.
+;; A writing project in discrete pieces probably has an end goal of being
+;; put together. Each project item has a property of being "included" or
+;; not. In the sidebar, an item's include state is toggled with
+;; binder-sidebar-toggle-include (x).
-;; ## Concatenate ##
+;; When calling binder-sidebar-concat (c | v), project items marked as
+;; included will be concatenated in a new buffer. The default mode of this
+;; buffer is set by binder-default-concat-mode.
-;; A writing project written in discrete pieces probably has an end goal of
-;; being put together. Each Binder project item has a property of being
-;; "included" or not. In the sidebar, an item's include state is toggled
-;; with binder-sidebar-toggle-include (x).
+;; > Hint: you can use an alternate default mode for different projects by
+;; > setting a directory local variable.
+
+;; When in the *Binder Concat View* buffer, calling
+;; binder-concat-find-original (C-c RET) will visit the original file
+;; corresponding to the text at point.
+
+
+;; Requirements
+;; ------------
+
+;; - Emacs 24.4
+;; - seq 2.20 (part of Emacs 25.1+)
-;; When calling binder-sidebar-concat (c | v), project items marked as
-;; included will be concatenated in a new buffer (separated by
-;; binder-concat-separator string.) The default mode of this buffer is set
-;; by binder-default-concat-mode.
-;; > Hint: you can use an alternate default mode for different projects by
-;; > setting a directory local variable.
+;; Installation
+;; ------------
-;; In this buffer, calling binder-concat-find-original (C-c RET) will
-;; visit the original file corresponding to the text at point.
+;; The latest stable release of Binder is available via [MELPA-stable][1].
+;; First, add MELPA-stable to your package archives:
-;; ## Why not just use Org Mode? ##
+;; M-x customize-option RET package-archives RET
-;; [Org Mode] is nice, but it's also a very *heavy* tool that almost
-;; insists that everything be done within Org Mode. This isn't useful if
-;; you want to write in a different format, e.g. [Markdown] or
-;; [Fountain].
+;; Insert an entry named melpa-stable with URL:
+;; https://stable.melpa.org/packages/
-;; Also, I prefer to keep my writing in a collection of separate text
-;; files. It feels nicer to work on something small and self-contained than
-;; to organize a large file with headings and use indirect buffers with
-;; narrowing.
+;; You can then find the latest stable version of binder in the list
+;; returned by:
-;; [org mode]: https://orgmode.org
-;; [markdown]: https://jblevins.org/projects/markdown-mode/
-;; [fountain]: https://github.com/rnkn/fountain-mode
+;; M-x list-packages RET
-;; ## Requirements ##
+;; If you prefer the latest but perhaps unstable version, do the above
+;; using [MELPA][2].
-;; - Emacs 24.4
-;; - seq 2.20
-;; ## Bugs and Feature Requests ##
+;; Advanced Installation
+;; ---------------------
-;; Report bugs and feature requests at:
-;; <https://github.com/rnkn/binder/issues>
+;; Download the [latest release][4], move this file into your load-path
+;; and add to your init.el file:
-;; ## Tutorial ##
+;; (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
+
+
+;; Tutorial
+;; --------
;; Binder comes with a tutorial. Calling M-x binder-tutorial will prompt
;; for an empty directory in which to generate the tutorial files.
+
+;; [1]: https://stable.melpa.org/#/binder
+;; [2]: https://melpa.org/#/binder
+;; [3]: https://www.literatureandlatte.com/scrivener/
+;; [4]: https://github.com/rnkn/binder/releases/latest
+
;;; Code: