pensieve.love/README.md

In progress. Manage a directory tree containing plain-text notes (with [some
line drawings](http://akkartik.name/lines.html)). Notes/files can have
[cross-links](https://merveilles.town/@akkartik/108766067153506592) (not
hyperlinks, but that's planned) with other notes, which are saved outside the
plain-text in a corresponding .json file.

pensieve.love is a compatible fork of [lines.love](http://akkartik.name/lines.html),
an editor for plain text where you can also seamlessly insert line drawings.
Designed above all to be easy to modify and give you early warning if your
modifications break something.

## Requirements

LÖVE. Get it from https://love2d.org (5MB)

## Invocation, and where your notes will live

To try out pensieve.love with some sample data, run the following command from
this repo's top-level directory:

```
love . sample
```

This will read the notes from the `data.sample/` directory in this repo to
give you a flavor for what the app is like.

While the sample gives you stuff to browse, don't use it to write any real
notes. LÖVE limits what directories apps can list files from (which is great
for privacy), but has some confusing rules around them. Each app can only
write to files under a single directory, the app's _save directory_
([love.filesystem.getSaveDirectory()](https://love2d.org/wiki/love.filesystem.getSaveDirectory)).
In addition, reads will also fall back to read from the repo directory,
enabling the sample experience. However, edits you make will not modify the
`data.sample/` directory in this repo. Your notes will fragment between two
directories, which can get confusing.

To create your own directory of notes, run without an argument:

```
love .
```

pensieve.love will then create a `data/` directory in the app's save directory
as above. Confusing location, but everything will be in one place.

## Modifying the app

Hit `ctrl+w` from within the to modify its code. The infrastructure works, but
it isn't advertised within the app because this particular app is currently
too large to comfortably modify from within itself. I use more specialized
editors while I improve the editing infrastructure further.

## Known issues

* No support yet for Unicode graphemes spanning multiple codepoints.

* No support yet for right-to-left languages.

* Editing a note grows sluggish if it grows larger than 1.5KB or so. Either
  use smaller notes (I haven't seen any slowdowns with lots of notes on the
  surface) or maximize large notes when editing them.

* Editing a note larger than 50KB grows sluggish (particularly during
  undo/redo) even when maximized.

* If you kill the process, say by force-quitting because things things get
  sluggish, you can lose data.

* Searching is slow. There's no index yet. Searching happens in the same
  thread as UI updates, so UI may go unresponsive with really large notes. I
  haven't observed this in practice.

* Pressing keys while editing will try to always keep the text cursor on
  screen. This can have some strange implications:

    * A long series of drawings will get silently skipped when you hit
      page-down, until a line of text can be showed on screen.
    * If there's no line of text at the top of the file, you may not be able
      to scroll back up to the top with page-up.

  So far this app isn't really designed for drawing-heavy files. For now I'm
  targeting mostly-text files with a few drawings mixed in.

* No clipping yet for drawings. In particular, circles/squares/rectangles and
  point labels can overflow a drawing.

* Long wrapping lines can't yet distinguish between the cursor at end of one
  screen line and start of the next, so clicking the mouse to position the
  cursor can very occasionally do the wrong thing.

* Touchpads can drag the mouse pointer using a light touch or a heavy click.
  On Linux, drags using the light touch get interrupted when a key is pressed.
  You'll have to press down to drag.

* Can't scroll while selecting text with mouse.

* No scrollbars yet. That stuff is hard.

* When editing sources, selecting text is not yet completely implemented.

## Mirrors and Forks

This repo is a fork of [lines.love](http://akkartik.name/lines.html). Updates
to it can be downloaded from:

* https://git.sr.ht/~akkartik/pensieve.love

Further forks are encouraged. If you show me your fork, I'll link to it here.

## Associated tools

* https://git.sr.ht/~akkartik/capture.love provides a blank-slate UI into the
  same notes directory as pensieve.love.
* https://codeberg.org/akkartik/lines2md exports lines.love files to Markdown
  and (non-editable) SVG.

## Feedback

[Most appreciated.](http://akkartik.name/contact)

In particular, pensieve.love has been exclusively tested so far with a US
keyboard layout. If you use a different layout, please let me know if things
worked, or if you found anything amiss.