taro/README.md

taro

mblaze frontend in uxn and crystal

build and install

1. Install and configure mblaze (as well as probably mbsync and msmtp)
2. Install uxn and crystal
3. Edit config and probably the mhandle function in taro-reader (see next section)
4. Run 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 file format is supported - it can be crafted with 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 format can be used. They can be created/edited in 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+<up|down>: naive multiselect
• alt+<up|down|left|right>: 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!