From e8834710c2c9c4fa803a1b5f4d6bccf3345463e5 Mon Sep 17 00:00:00 2001
From: Mark Redeman <markredeman@gmail.com>
Date: Sat, 23 Jun 2018 15:28:27 +0200
Subject: [PATCH] Docs: improve irc documentation

Explain how `+pass-user-fields` works and show a basic example for
configuring a pass entry to be used by circe.

Show how to connect to IRC and show a list of commands that can be used
in circe buffers.
---
 modules/app/irc/README.org | 40 ++++++++++++++++++++++++++++++++++----
 1 file changed, 36 insertions(+), 4 deletions(-)

diff --git a/modules/app/irc/README.org b/modules/app/irc/README.org
index caf043a6d..b06d136fc 100644
--- a/modules/app/irc/README.org
+++ b/modules/app/irc/README.org
@@ -3,10 +3,12 @@
 This module turns adds an IRC client to Emacs ([[https://github.com/jorgenschaefer/circe][~circe~)]] with native notifications ([[https://github.com/eqyiel/circe-notifications][circe-notifications]]).
 
 * Table of Contents :TOC:
-- [[#dependencies][Dependencies]]
-- [[#configure][Configure]]
-  - [[#pass-the-unix-password-manager][Pass: the unix password manager]]
-  - [[#emacs-auth-source-api][Emacs' auth-source API]]
+- [[Dependencies][Dependencies]]
+- [[Configure][Configure]]
+  - [[Pass: the unix password manager][Pass: the unix password manager]]
+  - [[Emacs' auth-source API][Emacs' auth-source API]]
+- [[Appendix][Appendix]]
+  - [[Commands][Commands]]
 
 * Dependencies
 This module has no dependencies, besides =gnutls-cli= or =openssl= for secure connections.
@@ -52,6 +54,15 @@ But wait, there's more! This stores your password in a public variable which cou
 
 And you're good to go!
 
+Note that =+pass-get-user= tries to find your username by looking for the fields
+listed in =+pass-user-fields= (by default =login=, =user==, =username== and =email=)=).
+An example configuration looks like
+
+#+BEGIN_SRC txt :tangle no
+mysecretpassword
+username: myusername
+#+END_SRC
+
 ** Emacs' auth-source API
 ~auth-source~ is built into Emacs. As suggested [[https://github.com/jorgenschaefer/circe/wiki/Configuration#safer-password-management][in the circe wiki]], you can store (and retrieve) encrypted passwords with it.
 
@@ -78,3 +89,24 @@ And you're good to go!
       :channels ("#emacs")))
 #+END_SRC
 
+* Appendix
+** Commands
+Here is a list of available commands, their default keybindings (defined in
+[[../../private/default/+bindings.el][private/default/+bindings.el]]), and corresponding ex commands (if any -- defined
+in [[../../private/default/+evil-commands.el][private/default/+evil-commands.el]]).
+
+| command | key       | description                               |
+|---------+-----------+-------------------------------------------|
+| ~=irc~  | =SPC o I= | Connect to IRC and all configured servers |
+
+When in a circe buffer these keybindings will be available.
+
+| command                | key       | description                                  |
+|------------------------+-----------+----------------------------------------------|
+| ~tracking-next-buffer~ | =SPC m a= | Switch to the next active buffer             |
+| ~circe-command-JOIN~   | =SPC m j= | Join a channel                               |
+| ~+irc/send-message~    | =SPC m m= | Send a private message                       |
+| ~circe-command-NAMES~  | =SPC m n= | List the names of the current channel        |
+| ~circe-command-PART~   | =SPC m p= | Part the current channel                     |
+| ~+irc/quit~            | =SPC m Q= | Kill the current circe session and workgroup |
+| ~circe-reconnect~      | =SPC m R= | Reconnect the current server                 |