From ea8a388c1b021f5777755ccfa4e085c02f640ba1 Mon Sep 17 00:00:00 2001
From: Trey Blancher <trey@blancher.net>
Date: Sun, 30 Apr 2023 17:16:48 -0400
Subject: [PATCH] Fleshed out README.md

---
 README.md | 47 ++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 46 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 6fa9d29..32a96ed 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,48 @@
 # asyncomplete-muttgoobook.vim
 
-A vim plugin for mail files to select email addresses from the mutt aliases file, and Google Contacts (using goobook).
\ No newline at end of file
+A vim plugin for mail files to select email addresses from the mutt aliases file, and Google Contacts (using goobook).
+
+## Prerequisites
+* This has been tested with the [vim-plug](https://github.com/junegunn/vim-plug) minimalist Vim plugin manager.  Other plugin managers may work.
+* This is designed to work with the [asyncomplete](https://github.com/prabirshrestha/asyncomplete.vim) code completion subsystem, which is writtin in pure Vim (v8) script.
+* [goobook](http://gitlab.com/goobook/goobook) for interacting with your Google Contacts from the command line.  This has been tested with Goobook 3.5.2, but 1.x may work if your distribution still uses Python 2.7+.
+* This is designed to work in mutt, but is not mutt-specific (except for reading _${HOME}/.mutt/aliases_).  Using vim to edit the file type `mail` should be enough to get it working.
+
+As of this writing (2023-04-30), this has only been tested in Vim v9, but is also writtin in Vim v8 script so should work in older versions.
+
+## Installation
+1.  Clone this repository into your Vim plugin directory. For vim-plug in Vim on Linux, this is usually _${HOME}/.vim/plugged_, but vim-plug will place it here automatically if you merely configure $MYVIMRC properly.  Place the following line between `call plug#begin(..)` and `call plug#end()`: 
+    ```vim
+    call plug#begin('...')
+    " ...
+    Plug 'https://git.eldon.me/trey/asyncomplete-muttgoobook.vim'
+    
+    " ...
+    call plug#end()
+    ```
+    Then, inside Vim, run `:PlugInstall`.  You can check that the muttgoobook plugin is installed successfully with `:PlugStatus`.
+1.  Configure Vim in $MYVIMRC to load the `muttgoobook` source using the following:  
+    ```vim
+    autocmd User asyncomplete_setup call asyncomplete#register_source({
+        \ 'name':       'muttgoobook',
+        \ 'allowlist':  ['mail'],
+        \ 'completor':  function('asyncomplete#sources#muttgoobook#completor'),
+        \ })
+    ```
+    If you have other file types to use this plugin, you may add them to the `allowlist` above.
+
+1.  By default, this plugin tries to determine if the cursor is in an email address field ('From:', 'To:', 'Cc:', 'Bcc:', in English).  The matching is case-insensitive.  If you use another language, that names these fields differently, you can modify this in $MYVIMRC by adding the `g:muttgoobook_address_fields` global variable.  This is designed to be a Vim regular expression, replace `['from', 'to', 'b\?cc']` accordingly:
+    ```
+    let g:muttgoobook_address_fields = '^\s*\(from\|to\|b\?cc\):\s*'
+    ```
+    The above pattern is the default if this variable isn't specified.
+1.  Also, if your mutt aliases file is in a different path than _${HOME}/.mutt/aliases_, you can override it in $MYVIMRC with the global variable `g:mutt_aliases`:
+    ```
+    let g:mutt_aliases = '~/.mutt/aliases'
+    ```
+    Again, what appears above is the default if not set explicitly to something else.  Any double-quotes (`"`) and backslashes (`\`) in the mutt aliases file will be removed.
+
+## TODO
+* possibly set up some kind of trigger to post an email address from the mutt aliases file or Google Contacts, within the body of the message.
+* Perform more testing!
+