README

Taverner <https://raw.github.com/Earnestly/taverner>

INTRODUCTION

  Taverner is a small collection of shell scripts (read: 2) designed
  to generate and maintain a bunch of game launchers (or anything else
  really). It uses a modified {dmenu}[dmenu] for creating list of entries
  along with a nice cover image and an accompanying tool to make creating
  these entries a bit more convenient.

  Screenshot: <https://raw.github.com/Earnestly/taverner/master/scrot.png>

REQUIRES

  - bash 4.2+
  - graphicsmagick
  - dmenu-pango-imlib <https://github.com/Cloudef/dmenu-pango-imlib>

INSTALL

  I keep my local binaries in LOCALDIR/bin:

    make PREFIX="$LOCALDIR" install

  Optionally you can add the launch script's directory to PATH:

    export PATH="$PATH:${LOCALDIR-$HOME/local}/data/taverner/bin"

WHAT & HOW

  Briefly, a typical session may look like this

    % barkeep -h
    Usage: barkeep [-h] [mk | ls | ed | rm]
        Each mode has an -h flag which produces a summary of its help section.

        -e      Preferred editor, uses $EDITOR if not set.

    Create a new menu entry.  Uses $EDITOR to complete the new entry.

        mk [-c <cover>] -t <template> <entry>
            -t      Select a template to base the new entry on.
            -c      Path or url to a cover image.  (Note: This is destructive)
            entry   The name for the new launcher script.

    List entries and templates.

        ls [-t]
            -t      List all available templates.

            If no arguments given this will list all entries.

    Edit the selected entry or template.  Only one entry may be edited per
    invocation.

        ed [-t <template>] [-c <cover>] [entry]
            -t      Attempts to open the template with $EDITOR.
            -c      Replace the cover for entry, note that the entry is required
                    for this operation.
            entry   Attempts to open the entry with $EDITOR.

        Issue: If -c is specified for an entry, it will both update the entries
               cover image but also offer to edit the entry as well.

    Remove selected entries and corresponding covers.  If no argument given,
    attempt to remove all entires.

        rm [entry [entry]]
            entry   The chosen entry to remove.

    Examples:
        # Creates an entry using the psx template called wipeout_3 using emacs
        # as the editor.
        barkeep mk -e emacs -t psx -c ~/wipeout.png wipeout_3

        # Removes both wipeout_3 and crash_bandicoot launchers along with any
        # cover images if found.
        barkeep rm wipeout_3 crash_bandicoot

    % barkeep ls -t
    ppsspp
    wine

    % barkeep mk wipeout_pulse -t ppsspp -c ~/wipeout_pulse_cover.jpg
    ‘/home/earnest/wipeout_pure_cover.jpg’ -> ‘/home/earnest/local/data/taverner/covers/wipeout_pure’
    ‘/home/earnest/local/data/taverner/templates/ppsspp’ -> ‘/home/earnest/local/data/taverner/bin/wipeout_pure’

  At this point you'll get prompted with your editor to make any changes
  to the template such as specifying what to execute, and where the data
  files are located. Here is an example template with places left for you
  to fill in:

    #!/bin/bash
    # Title: Wipeout Pure (PSP 2005)

    exec ppsspp --fullscreen "$LOCALDIR"/data/games/psp/wipeout_pure.iso

  Here the title is read and passed to dmenu, if "# Title:" isn't present,
  taverner will fallback on the file name of the launch script.

  After editing the template, run taverner.

WHY

  I wanted to turn an old machine into a game box that could play various
  emulated games on the SNES, PSX, PSP and some older ones via WINE while
  unifying the UI. Many existing solutions were quite sophisticated,
  beautiful but complex graphical frontends, usually existing to serve a
  specific set of emulators.

  Since the machine I was planning to use is quite limited in terms of
  hardware I wanted something simple (and not very clever) which did as
  little as possible and with enough flexibility for anything I might
  conceivably throw at it.

  As Cloudef <https://github.com/Cloudef> had been working on providing
  extra functionality for dmenu which allows me to embed images based on
  the entry selected, I decided that would be perfect to list a bunch of
  games including any cover art.

  Initially I simply wrote a few lines of shell that passed a handwritten
  list to dmenu which launched a second script that contained all the
  logic necessary for starting the program. Eventually this manual
  insertion and deletion of list entries became inconvenient which
  resulted in the creation of the `taverner` script that generates menus
  on the fly.

  Now that was reasonably well solved, I still had the issue of manually
  writing the launcher scripts and setting up the cover image along with
  other potential tweaks. This is where `barkeep` comes in, it exists
  simply to aid me in creating the launchers, copying over templates and
  letting me just add any necessary tweaks.

COLOPHON

  The barkeep script can only read the Title if the launcher is text, this
  could be changed with a better design but for now it means all launchers
  must be text files if the Title is needed.

  Taverner makes use of a personal convention called "LOCALDIR", it
  behaves like the DESTDIR convention from makefiles and supplants the XDG
  Base Directory Specification.

  Under LOCALDIR a familiar hierarchy to the FHS is found with a few
  changes.

  See <https://github.com/Earnestly/dotfiles/blob/master/README> for some
  more information.