# taro [mblaze](https://git.vuxu.org/mblaze) frontend in [uxn](https://wiki.xxiivv.com/site/uxn.html) and [crystal](https://crystal-lang.org) [![screenshot - taro-ls showing Archives/2022 mailbox selected with a search query active listing mail from the uxn mailing list, and a reader window open next to it reading the initial uxn metadata proposal, with a prompt at the bottom for managing attachments, replying, forwarding, or quitting](./screenshot.png)](./screenshot.png) ## build and install 1. [Install](https://git.vuxu.org/mblaze) and [configure mblaze](https://git.vuxu.org/mblaze/about/man/mblaze-profile.5) (as well as probably [mbsync](https://isync.sourceforge.io) and [msmtp](https://marlam.de/msmtp)) 2. Install [uxn](https://git.sr.ht/~rabbits/uxn) and [crystal](https://crystal-lang.org/install/) 3. Edit [config](./config) and probably the `mhandle` function in [taro-reader](./taro-reader) (see next section) 4. Run [build.sh](./build.sh) (optionally with the `desktopfile` argument to fill out the `taro.desktop` file and put it in your user-level apps) 5. Copy `taro-ctl` to your path ## configuration ### taro-ctl The `config` file is processed into a bunch of constants for `taro-ctl` by the build script. Adjust them to your needs: - `MBOX_ROOT`: the directory where your maildirs are. - `TARO_LIB`: the directory where your runtime files (`taro-ls` rom, `taro-reader` script, `.theme` and `font.icn` files, etc.) will be installed to, as well as a copy of `uxnemu` - `TARO_DOWNLOADS`: directory where attachments are downloaded to. - `UXN_EMU`: name the `uxnemu` will be copied to - this is a hack to set the `_NET_WM_CLASS`. - `TARO_ENV`: environment variables as you type them in the terminal, that you can use for the `READER_PROG` and `COMPOSE_PROG` commands - `READER_PROG`: command to spawn to read mail - by default it calls the `st` terminal with some environment variables and options set, and runs `taro-reader` - `COMPOSE_PROG`: command to spawn to write mail - by default it calls the `st` terminal with some environment variables and options set and runs `mcom` from `mblaze` ### taro-ls The [.theme](https://wiki.xxiivv.com/site/theme.html) file format is supported - it can be crafted with [nasu](https://git.sr.ht/~rabbits/nasu) and should be located at `TARO_LIB/.theme`. The following details the purpose (and default) of each color: 1. Background and text color when hilighted (black) 2. Hilight, scrollbar, button hover color (turquoise) 3. Soft fg color eg. resize handle, textbox help (medium gray) 4. Foreground/text color (whitish gray) Any 8x8 1bpp ASCII font in [icn](https://wiki.xxiivv.com/site/icn_format.html) format can be used. They can be created/edited in [nasu](https://git.sr.ht/~rabbits/nasu) and should located at `TARO_LIB/font.icn`. ## usage `taro` is a multi-window MUA with three types of windows: - `taro-ls`: the main `uxn` window where you will check your inbox and organize your mail - `taro-reader`: a terminal window that runs a shell script to read mail - `taro-compose`: a terminal window running `mcom` The windows are managed by a master program, `taro-ctl`, which talks to them with `messages` (see below). ### mail management The `taro-ls` window has three main areas: - Mailboxes: it's assumed by taro-ctrl that your inbox is named INBOX, and it exists; it's put first, and the rest are shown in alphabetical order - Mail List: your mail in the default scan-format given in your mblaze-profile is shown here - Actions: button list and initially hidden text input area Left clicking on a mailbox switches to that mailbox. Left-clicking on mail selects that mail. You can do multiselect by holding shift when clicking. Right-clicking on mail opens that mail (only the first in the selection if 2 or more are selected). You can also use the `Enter` key to open mail. The buttons on the bottom are as follows (with equivalent keybinds): - compose [`n`]: open a compose window to write new mail - refresh [`r`]: refresh the current mailbox, removing search query - mark all read [`.`]: this - search [`/`]: search mail with a regex (only headers, case insensitive) - refile [`m`]: move mail to the given folder - trash [`Del`]: move mail to the Trash folder, unless it's already in the Trash, in which case it's deleted In the bottom-left of the window is an indicator area with in which the following symbols may appear: - `$`: search query is active - refresh or switch mailboxes to deactivate - `*`: an operation is pending (ie, more messages have been sent than received) There is a resize handle in the bottom right - clicking and dragging it resizes the window. Additional keybindings: - `[shift+]tab`: change mailboxes - `up/down`: navigate through mail - `shift+`: naive multiselect - `alt+`: resize ### reading mail Reading mail is currently done in a terminal that pipes the mail content into `less` and gives some keybind options: - `q`: quit - `r`: reply - `f`: forward - `o`: open an attachment - you are presented with the MIME structure of the mail with parts numbered and prompted to select a number to open. The programs to open each mimetype are in the aforementioned `handle` function of the script. - `s`: save an attachment - like `o` but selecting a MIME part saves it to the folder `TARO_DOWNLOADS` in `config.cr` The attachment actions loop until you enter nothing or a non-numeric value. The whole script loops until you quit. ### writing mail Writing mail is currently done by opening a terminal and calling `mcom`, which lets you compose in your `EDITOR` of choice and prompts for additional action. ### crypto If you try to decrypt/sign with either `pinenetry-tty` or `pinentry-curses`, GPG will attach it to the stdio of `taro-ctl`, not the terminal window where you are viewing/composing mail. Use a graphical pinentry program instead. ### what it doesn't do - manage your contacts (there are other programs for this) - manage your calendar (and that) - add/remove mailboxes (how many times a year do you do this?) ## TODO - Add options to search (case-sensitive, search mail body, etc) - Add option to refile to copy instead of move - Flag/star messages? I never use this fature if IMAP... - Real `uxn` implementaions of reader/compose windows? Probably overkill ## messages (IPC) Messages are in the format `[1][2:3][...]`: - byte 1 is the message type - bytes 2 and 3 are the length of the message, in bytes - bytes 4 and beyond are the message itself (payload) - won't be present if the length is 0 Even messages go from `taro-ctl` to the `uxn` windows. - `0`: mailbox list (truncated to 4k - this should be enough) - `2`: list mail in current mailbox (or search results) (truncated to 32k - if you need more, use search) Odd messages go from the `uxn` windows to `taro-ctl` (or from `taro-ctl` to itself). - `1`: change/refresh mailbox; payload is the mailbox to read - `3`: mark all as read in current mailbox; no payload - `5`: search mail; payload is the regex - `7`: refile mail; payload is the beginning and end of the `mmsg` range in u16, and then the mailbox name - `9`: trash mail; payload is the beginning and end of the `mmsg` range in u16 - `11`: read mail; payload is a single u16 `mmsg` number in the current sequence - `13`: compose mail; no payload - `15`: push view update (keeps search query, for after replying/writing mail or when new mail comes in); no payload ## socket (other IPC) `taro-ctl` creates a socket at `TARO_LIB/taro.sock` and listens for bytes on it. Every time a byte is written to the socket, `taro-ctl` will use message `15` to update the inbox. Whatever method you use to sync your maildirs to your mailserver, it can write a byte to this socket when you receive mail!