aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorWilliam Rankin <william@bydasein.com>2020-09-26 17:34:39 +1000
committerWilliam Rankin <william@bydasein.com>2020-09-27 16:29:32 +1000
commit577bf2640408e432fb79b96ff6b853d15444f4a9 (patch)
tree9c56d6caf6fc823908f62f527d76f8330fc69eb3
parent8e67ca845524037290fe9573aee8b32f60360fe2 (diff)
downloadbinder-577bf2640408e432fb79b96ff6b853d15444f4a9.zip
Update README/Commentary
-rw-r--r--README.md224
-rw-r--r--binder.el220
2 files changed, 270 insertions, 174 deletions
diff --git a/README.md b/README.md
index 2e2a284..95b623f 100644
--- a/README.md
+++ b/README.md
@@ -1,39 +1,50 @@
-# Binder #
+Binder
+======
-[![MELPA Stable](https://stable.melpa.org/packages/binder-badge.svg)](https://stable.melpa.org/#/binder)
-[![MELPA](https://melpa.org/packages/binder-badge.svg)](https://melpa.org/#/binder)
+[![MELPA Stable](https://stable.melpa.org/packages/binder-badge.svg)][1]
+[![MELPA](https://melpa.org/packages/binder-badge.svg)][2]
![screenshot](https://user-images.githubusercontent.com/1256849/87218460-464a3300-c396-11ea-9ce7-30f7a5bc4377.png)
-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.
@@ -49,13 +60,13 @@ directory. Items are displayed as:
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)`.
@@ -71,19 +82,19 @@ 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.
+> 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)`.
@@ -94,101 +105,138 @@ 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.
-### 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 ")`.
+
+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.
-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.
-### Tags ###
+Tags
+----
-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.
+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 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`.
+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+)
-> Hint: you can use an alternate default mode for different projects by
-> setting a directory local variable.
-In this buffer, calling `binder-concat-find-original (C-c RET)` will
-visit the original file corresponding to the text at point.
+Installation
+------------
-## Why not just use Org Mode? ##
+The latest stable release of Binder is available via [MELPA-stable][1].
+First, add MELPA-stable to your package archives:
-[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][].
+ M-x customize-option RET package-archives RET
+
+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
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: