aboutsummaryrefslogtreecommitdiff
path: root/README.md
blob: 3ba072354bb41046c81a9b37c7dec52a72493475 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
Binder
======

[![MELPA Stable](https://stable.melpa.org/packages/binder-badge.svg)][1]
[![MELPA](https://melpa.org/packages/binder-badge.svg)][2]

![screenshot](screenshots/01.png)

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 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 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 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 items is a file reference relative to the project
directory. Items are displayed as:

    x * name        #tag1 #tag2

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)`.

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.

Reset the sidebar filters with `binder-sidebar-refresh (g)`.


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)`.


Concatenating
-------------

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)`.

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`.

>  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+)


Installation
------------

The latest stable release of Binder is available via [MELPA-stable][1].
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][2].


Advanced Installation
---------------------

Download the [latest release][4], 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


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