Add man pages

7 files changed, 554 insertions, 2 deletions

diff --git a/.gitignore b/.gitignore
index 8fc975f..90e1624 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,4 +1,7 @@
 .go
 /aerc2
+/aerc
 log
 raw.log
+*.1
+*.5
diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000..66dc650
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,26 @@
+aerc:
+	go build -o aerc
+
+%.1: doc/%.1.scd
+	scdoc < $< > $@
+
+%.5: doc/%.5.scd
+	scdoc < $< > $@
+
+DOCS := \
+	aerc.1 \
+	aerc-config.5 \
+	aerc-imap.5 \
+	aerc-smtp.5
+
+all: aerc $(DOCS)
+
+clean:
+	rm -f *.1 *.5 aerc
+
+install:
+	# TODO: install binary, man pages, example config, and filters from contrib
+
+.DEFAULT_GOAL := all
+
+.PHONY: aerc clean install
diff --git a/README.md b/README.md
index f6ab192..1f77d5a 100644
--- a/README.md
+++ b/README.md
@@ -8,7 +8,12 @@ Join the IRC channel: [#aerc on irc.freenode.net](http://webchat.freenode.net/?c
 
 ## Building
 
-    go build
+    $ make
+
+## Installation
+
+    # make install
+    $ man aerc
 
 ## Usage
 
@@ -18,7 +23,7 @@ $ cp config/*.conf ~/.config/aerc/
 $ vim ~/.config/aerc/accounts.conf
 ```
 
-Fill in your account details and configure the rest to taste, then run `aerc2`.
+Fill in your account details and configure the rest to taste, then run `aerc`.
 
 ## Contributing
 
diff --git a/doc/aerc-config.5.scd b/doc/aerc-config.5.scd
new file mode 100644
index 0000000..a221723
--- /dev/null
+++ b/doc/aerc-config.5.scd
@@ -0,0 +1,319 @@
+aerc-config(5)
+
+# NAME
+
+aerc-config - configuration file formats for *aerc*(1)
+
+# CONFIGURATION
+
+There are three aerc config files: *aerc.conf*, *binds.conf*, and
+*accounts.conf*. The last one must be kept secret, as it may include your
+account credentials. We look for these files in your XDG config home plus
+"aerc", which defaults to ~/.config/aerc.
+
+Examples of these config files are typically included with your installation of
+aerc and are usually installed in /usr/share/aerc.
+
+Each file uses the _ini_ format, and consists of sections with keys and values.
+A line beginning with # is considered a comment and ignored, as are empty lines.
+New sections begin with [section-name] on a single line, and keys and values are
+separated with "=".
+
+# AERC.CONF
+
+This file is used for configuring the general appearance and behavior of aerc.
+
+## UI OPTIONS
+
+These options are configured in the *[ui]* section of aerc.conf.
+
+*index-format*
+	Describes the format for each row in a mailbox view. This field is
+	compatible with mutt's printf-like syntax. TODO: document properly
+
+	Default: %4C %Z %D %-17.17n %s
+
+*timestamp-format*
+	See strftime(3)
+
+	Default: %F %l:%M %p (ISO 8501 + 12 hour time)
+
+*sidebar-width*
+	Width of the sidebar, including the border. Set to zero to disable the
+	sidebar.
+
+	Default: 20
+
+*empty-message*
+	Message to display when viewing an empty folder.
+
+	Default: (no messages)
+
+## VIEWER
+
+These options are configured in the *[viewer]* section of aerc.conf.
+
+*pager*
+	Specifies the pager to use when displaying emails. Note that some filters
+	may add ANSI escape sequences to add color to rendered emails, so you may
+	want to use a pager which supports ANSI.
+
+	Default: less -R
+
+*alternatives*
+	If an email offers several versions (multipart), you can configure which
+	mimetype to prefer. For example, this can be used to prefer plaintext over
+	HTML emails.
+
+	Default: text/plain,text/html
+
+## COMPOSE
+
+These options are configured in the *[viewer]* section of aerc.conf.
+
+*editor*
+	Specifies the command to run the editor with. It will be shown in an
+	embedded terminal, though it may also launch a graphical window if the
+	environment supports it. Defaults to *$EDITOR*, or *vi*(1).
+
+## FILTERS
+
+Filters allow you to pipe an email body through a shell command to render
+certain emails differently, e.g. highlighting them with ANSI escape codes.
+They are configured in the *[filters]* section of aerc.conf.
+
+The first filter which matches the email's mimetype will be used, so order
+them from most to least specific.
+
+You can also match on non-mimetypes, by prefixing with the header to match
+against (non-case-sensitive) and a comma, e.g. subject,text will match a
+subject which contains "text". Use header,~regex to match against a regex.
+
+Most aerc installations come with some useful filters, typically installed in
+/usr/share/aerc/filters. Here is an example config which uses these filters:
+
+```
+subject,~^\[PATCH=/usr/share/aerc/filters/hldiff.py
+text/html=/usr/share/aerc/filters/html
+text/*=/usr/share/aerc/filters/plaintext.py
+```
+
+Note that the filters which are installed with aerc have additional
+dependencies, such as Python, sockify, and w3m.
+
+# ACCOUNTS.CONF
+
+This file is used for configuring each mail account used for aerc. Each section
+is the name of an account you want to configure, and the keys & values in that
+section specify details of that account's configuration. In addition to the
+options documented here, specific transports for incoming and outgoing emails
+may have additional configuration parameters, documented on their respective man
+pages.
+
+Note that many of these configuration options are written for you, such as
+*source* and *outgoing*, when you run the account configuration wizard
+(*:new-account*).
+
+*copy-to*
+	Specifies a folder to copy sent mails to, usually "Sent".
+
+	Default: none
+
+*default*
+	Specifies the default folder to open in the message list when aerc
+	configures this account.
+
+	Default: INBOX
+
+*folders*
+	Specifies the list of folders to display in the sidebar.
+
+	Default: all folders
+
+*from*
+	The default value to use for the From header in new emails. This should be
+	an RFC 5322-compatible string, such as "Your Name <you@example.org>".
+
+	Default: none
+
+*outgoing*
+	Specifies the transport for sending outgoing emails on this account.  It
+	should be a connection string, and the specific meaning of each component
+	varies depending on the protocol in use.  See each protocol's man page for
+	more details:
+
+	- *aerc-smtp*(5)
+
+*source*
+	Specifies the source for reading incoming emails on this account. This key
+	is required for all accounts. It should be a connection string, and the
+	specific meaning of each component varies depending on the protocol in use.
+	See each protocol's man page for more details:
+
+	- *aerc-imap*(5)
+
+	Default: none
+
+# BINDS.CONF
+
+This file is used for configuring keybindings used in the aerc interactive
+client. You may configure different keybindings for different contexts by
+writing them into different *[sections]* of the ini file. The available contexts
+are:
+
+*[messages]*
+	keybindings for the message list
+
+*[view]*
+	keybindings for the message viewer
+
+*[compose]*
+	keybindings for the message composer
+
+*[compose::editor]*
+	keybindings for the composer, when the editor is focused
+
+*[compose::review]*
+	keybindings for the composer, when reviewing the email before it's sent
+
+*[terminal]*
+	keybindings for terminal tabs
+
+You may also configure global keybindings by placing them at the beginning of
+the file, before specifying any context-specific sections. For each *key=value*
+option specified, the _key_ is the keystrokes pressed (in order) to invoke this
+keybinding, and _value_ specifies keystrokes that aerc will simulate when the
+keybinding is invoked. Generally this is used to execute commands, for example:
+
+	rq = :reply -q<Enter>
+
+Pressing r, then q, will simulate typing in ":reply -q<Enter>", and execute
+:reply -q accordingly. It is also possible to invoke keybindings recursively in
+a similar fashion. Additionally, the following special options are available in
+each binding context:
+
+*$noinherit*
+	If set to "true", global keybindings will not be effective in this context.
+
+	Default: false
+
+*$ex*
+	This can be set to a keystroke which will bring up the command input in this
+	context.
+	
+	Default: <semicolon>
+
+In addition to letters, special keys may be specified in <angle brackets>. The
+following special keys are supported:
+
+[[ *Name*
+:- *Description*
+|  space
+:  " "
+|  semicolon
+:  ;
+|  tab
+:  
+|  enter
+:  
+|  up
+:  
+|  down
+:  
+|  right
+:  
+|  left
+:  
+|  pgup
+:  
+|  pgdn
+:  
+|  home
+:  
+|  end
+:  
+|  insert
+:  
+|  delete
+:  
+|  exit
+:  
+|  cancel
+:  
+|  print
+:  
+|  pause
+:  
+|  backtab
+|  c-space
+:  Ctrl+Space
+|  c-a
+:  Ctrl+a
+|  c-b
+:  Ctrl+b
+|  c-c
+:  Ctrl+c
+|  c-d
+:  Ctrl+d
+|  c-e
+:  Ctrl+e
+|  c-f
+:  Ctrl+f
+|  c-g
+:  Ctrl+g
+|  c-h
+:  Ctrl+h
+|  c-i
+:  Ctrl+i
+|  c-j
+:  Ctrl+j
+|  c-k
+:  Ctrl+k
+|  c-l
+:  Ctrl+l
+|  c-m
+:  Ctrl+m
+|  c-n
+:  Ctrl+n
+|  c-o
+:  Ctrl+o
+|  c-p
+:  Ctrl+p
+|  c-q
+:  Ctrl+q
+|  c-r
+:  Ctrl+r
+|  c-s
+:  Ctrl+s
+|  c-t
+:  Ctrl+t
+|  c-u
+:  Ctrl+u
+|  c-v
+:  Ctrl+v
+|  c-w
+:  Ctrl+w
+|  c-x
+:  Ctrl+x
+|  c-y
+:  Ctrl+y
+|  c-z
+:  Ctrl+z
+|  c-]
+:  Ctrl+]
+|  c-[
+:  Ctrl+[
+|  c-^
+:  Ctrl+^
+|  c-_
+:  Ctrl+_
+
+# SEE ALSO
+
+*aerc*(1) *aerc-imap*(5) *aerc-smtp*(5)
+
+# AUTHORS
+
+Maintained by Drew DeVault <sir@cmpwn.com>, who is assisted by other open
+source contributors. For more information about aerc development, see
+https://git.sr.ht/~sircmpwn/aerc.
diff --git a/doc/aerc-imap.5.scd b/doc/aerc-imap.5.scd
new file mode 100644
index 0000000..5899a34
--- /dev/null
+++ b/doc/aerc-imap.5.scd
@@ -0,0 +1,46 @@
+aerc-imap(5)
+
+# NAME
+
+aerc-imap - IMAP configuration for *aerc*(1)
+
+# SYNOPSIS
+
+aerc implements the IMAP protocol as specified by RFC 3501, with the following
+IMAP extensions:
+
+- IDLE (RFC 2177)
+
+# CONFIGURATION
+
+IMAP configuration may be done interactively with the :new-account command.
+
+In accounts.conf (see *aerc-config*(5)), the following IMAP-specific options are
+available:
+
+*source*
+	imap[s][+insecure]://username[:password]@hostname[:port]
+
+	Remember that all fields must be URL encoded. The "@" symbol, when URL
+	encoded, is *%40*.
+
+	The meaning of the scheme component is:
+
+	*imap://*:
+		IMAP with STARTTLS
+
+	*imap+insecure://*:
+		IMAP without STARTTLS
+
+	*imaps*:
+		IMAP with TLS/SSL
+
+# SEE ALSO
+
+*aerc*(1) *aerc-config*(5) *aerc-smtp*(5)
+
+# AUTHORS
+
+Maintained by Drew DeVault <sir@cmpwn.com>, who is assisted by other open
+source contributors. For more information about aerc development, see
+https://git.sr.ht/~sircmpwn/aerc.
diff --git a/doc/aerc-smtp.5.scd b/doc/aerc-smtp.5.scd
new file mode 100644
index 0000000..7d07125
--- /dev/null
+++ b/doc/aerc-smtp.5.scd
@@ -0,0 +1,50 @@
+aerc-smtp(5)
+
+# NAME
+
+aerc-smtp - SMTP configuration for *aerc*(1)
+
+# SYNOPSIS
+
+aerc implements the SMTP protocol as specified by RFC 5321.
+
+# CONFIGURATION
+
+SMTP configuration may be done interactively with the :new-account command.
+
+In accounts.conf (see *aerc-config*(5)), the following SMTP-specific options are
+available:
+
+*outgoing*
+	smtp[s][+plain|+none]://username[:password]@hostname[:port]
+
+	Remember that all fields must be URL encoded. The "@" symbol, when URL
+	encoded, is *%40*.
+
+	The meaning of the scheme component is:
+
+	*smtp://*:
+		Unencrypted SMTP
+
+	*smtps://*:
+		SMTP with TLS/SSL
+
+	Additionally, you can specify an authentication mechansim like so:
+
+	*+none*:
+		No authentication is required to use this SMTP server. You may omit the
+		username and password in this case.
+
+	*+plain*:
+		Authenticate with a username and password using AUTH PLAIN. This is the
+		default behavior.
+
+# SEE ALSO
+
+*aerc*(1) *aerc-config*(5) *aerc-smtp*(5)
+
+# AUTHORS
+
+Maintained by Drew DeVault <sir@cmpwn.com>, who is assisted by other open
+source contributors. For more information about aerc development, see
+https://git.sr.ht/~sircmpwn/aerc.
diff --git a/doc/aerc.1.scd b/doc/aerc.1.scd
new file mode 100644
index 0000000..5d501f0
--- /dev/null
+++ b/doc/aerc.1.scd
@@ -0,0 +1,103 @@
+aerc(1)
+
+# NAME
+
+aerc - the world's best email client
+
+# SYNOPSIS
+
+_aerc_
+
+Starts the interactive aerc mail client on /dev/tty.
+
+# RUNTIME COMMANDS
+
+To execute a command, press : to summon the command interface. Commands may also
+be bound to keys, see *aerc-config*(5) for details.
+
+Different commands work in different contexts, depending on the kind of tab you
+have selected.
+
+## GLOBAL COMMANDS
+
+These commands work in any context.
+
+*cd* <directory>
+	Changes aerc's current working directory.
+
+*term* [command...]
+	Opens a new terminal tab with a shell running in the current working
+	directory, or the specified command.
+
+*prev-tab* [n], *next-tab* [n]
+	Cycles to the previous or next tab in the list, repeating n times
+	(default: 1).
+
+*quit*
+	Exits aerc.
+
+## MESSAGE LIST COMMANDS
+
+*cf* <folder>
+	Change the folder shown in the message list.
+
+*compose*
+	Open the compose window to send a new email. The new email will be sent with
+	the current account's outgoing transport configuration, see
+	*aerc-config*(5) for details on configuring outgoing emails.
+
+*copy* <target>
+	Copies the selected message to the target folder.
+
+*delete-message*
+	Deletes the selected message.
+
+*move* <target>
+	Moves the selected message to the target folder.
+
+*next-folder* <n>, *prev-folder* <n>
+	Cycles to the next (or previous) folder shown in the sidebar, repeated n
+	times (default: 1).
+
+*next-message* <n>[%], *prev-message* <n>[%]
+	Selects the next (or previous) message in the message list. If specified as
+	a percentage, the percentage is applied to the number of messages shown on
+	screen and the cursor advances that far.
+
+*pipe* <cmd>
+	Downloads and pipes the selected message into the given shell command, and
+	opens a new terminal tab to show the result.
+
+*reply* [-aq]
+	Opens the composer to reply to the selected message.
+
+	*-a*: Reply all
+
+	*-q*: Insert a quoted version of the selected message into the reply editor
+
+*select-message* <n>
+	Selects the nth message in the message list (and scrolls it into view if
+	necessary).
+
+*view-message*
+	Opens the message viewer to display the selected message.
+
+## MESSAGE VIEW COMMANDS
+
+*close*
+	Closes the message viewer.
+
+## TERMINAL COMMANDS
+
+*close*
+	Closes the terminal.
+
+# SEE ALSO
+
+*aerc-config*(5) *aerc-imap*(5) *aerc-smtp*(5)
+
+# AUTHORS
+
+Maintained by Drew DeVault <sir@cmpwn.com>, who is assisted by other open
+source contributors. For more information about aerc development, see
+https://git.sr.ht/~sircmpwn/aerc.