Add man pages
This commit is contained in:
parent
fcdcd32de7
commit
fc719e47c4
7 changed files with 554 additions and 2 deletions
3
.gitignore
vendored
3
.gitignore
vendored
|
@ -1,4 +1,7 @@
|
||||||
.go
|
.go
|
||||||
/aerc2
|
/aerc2
|
||||||
|
/aerc
|
||||||
log
|
log
|
||||||
raw.log
|
raw.log
|
||||||
|
*.1
|
||||||
|
*.5
|
||||||
|
|
26
Makefile
Normal file
26
Makefile
Normal file
|
@ -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
|
|
@ -8,7 +8,12 @@ Join the IRC channel: [#aerc on irc.freenode.net](http://webchat.freenode.net/?c
|
||||||
|
|
||||||
## Building
|
## Building
|
||||||
|
|
||||||
go build
|
$ make
|
||||||
|
|
||||||
|
## Installation
|
||||||
|
|
||||||
|
# make install
|
||||||
|
$ man aerc
|
||||||
|
|
||||||
## Usage
|
## Usage
|
||||||
|
|
||||||
|
@ -18,7 +23,7 @@ $ cp config/*.conf ~/.config/aerc/
|
||||||
$ vim ~/.config/aerc/accounts.conf
|
$ 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
|
## Contributing
|
||||||
|
|
||||||
|
|
319
doc/aerc-config.5.scd
Normal file
319
doc/aerc-config.5.scd
Normal file
|
@ -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.
|
46
doc/aerc-imap.5.scd
Normal file
46
doc/aerc-imap.5.scd
Normal file
|
@ -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.
|
50
doc/aerc-smtp.5.scd
Normal file
50
doc/aerc-smtp.5.scd
Normal file
|
@ -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.
|
103
doc/aerc.1.scd
Normal file
103
doc/aerc.1.scd
Normal file
|
@ -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.
|
Loading…
Reference in a new issue