aboutsummaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'README.md')
-rw-r--r--README.md224
1 files changed, 136 insertions, 88 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