~callum/barszcz

cb06c5af5a73b0e108ce4a0b4e85157c13946c87 — Callum Brown 1 year, 10 months ago cbd324b
Update README

Add links to todo and lists
Note about list of things interface
Reformat command docs
1 files changed, 62 insertions(+), 16 deletions(-)

M README.md
M README.md => README.md +62 -16
@@ 1,10 1,13 @@
# barszcz

Barszcz is intended to be a TUI and music player plugin for
[beets](https://beets.io/).
It is currently mostly non-existent, and how far I will get is uncertain.
Barszcz is intended to be a vi-like terminal user-interface (TUI) and music
player plugin for [beets](https://beets.io/).
It is named after a type of Polish beetroot soup.

Barszcz is a Polish beetroot soup.
Currently, barszcz provides a configurable interface for beets' `list` command.

- [todo list and issue tracker](https://todo.sr.ht/~callum/barszcz)
- [mailing list for questions and contributions](https://lists.sr.ht/~callum/barszcz)


## How to use it


@@ 31,26 34,68 @@ Run barszcz with:
beet barszcz
```


### Interface

Barszcz is based around lists of so-called "things".
A thing could be a representation of a beets' album or item,
an attribute of an album or item, or a heading.
Different types of things may have their own configuration options,
and may be treated differently by commands.


### Commands

The command input line at the bottom of the screen can be brought up by typing
a colon (":").

'Thing' is used to refer to beets items and albums collectively.
Positional arguments of commands are in [brackets].
Required arguments are CAPITALISED.

| command       | short form | description |
| ---           | ---        | --- |
| quit          | q          | Quit Barszcz |
| list  [query] | ls         | List albums and items matching the [query]. Default: [query] is blank, list all. |
| lista [query] | lsa        | List albums matching the [query]. Default: [query] is blank, list all. |
| listi [query] | lsi        | List items matching the [query]. Default: [query] is blank, list all. |
| focus [INDEX] |            | Change focus to the thing at the given [INDEX]. A negative [INDEX] focuses the last thing. Indices are not displayed; this command is intended for internal use and shortcuts. |
| up [n]        |            | Change focus up [n] things (wraps). Default: [n] = 1. |
| down [n]      |            | Change focus down [n] things (wraps). Default: [n] = 1. |
| more          |            | Show more information about the focused thing. If an album or item is focused, its attributes will be listed. If an attribute is focused, albums and items with that attribute will be listed. |
|               |            | Blank command clears input line. |

#### `quit`
Quit barszcz.

Short form: `q`

#### `list [query]`
List albums and items matching the [query].
Default: [query] is blank, list all albums and items.

Short form: `ls`

#### `lista [query]`
List albums matching the [query].
Default: [query] is blank, list all albums.

Short form: `lsa`

#### `listi [query]`
List items matching the [query].
Default: [query] is blank, list all items.

Short form: `lsi`

#### `focus [INDEX]`
Change focus to the thing at the given [INDEX].
A negative [INDEX] focuses the last thing.
Indices are not displayed; this command is intended for internal use and shortcuts.

#### `up [n]`
Change focus up [n] things (wraps).
Default: [n] = 1.

#### `down [n]`
Change focus down [n] things (wraps).
Default: [n] = 1.

#### `more`
Show more information about the focused thing.
If an album or item is focused, its attributes will be listed.
If an attribute is focused, albums and items with that attribute will be listed.

#### _blank_
A blank command clears the input line and shortcut input.


### Shortcuts


@@ 60,6 105,7 @@ typing them in.
A sequence of digits preceding a shortcut can be passed as an argument to
commands, for example typing `3` followed by the down arrow key will move the
focus three things down (using the default configuration).
The current shortcut input can be seen in the bottom right of the screen.

For the default shortcuts and how to define shortcuts, see the Configuration
section.