Add man pages
This commit is contained in:
Drew DeVault
parent
fcdcd32de7
commit
fc719e47c4
7 changed files with 554 additions and 2 deletions
3
.gitignore
vendored
3
.gitignore
vendored
|
|
@ -1,4 +1,7 @@
|
|||
.go
|
||||
/aerc2
|
||||
/aerc
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
|
|
|
|||
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