From fc719e47c452564b56d2ed0b7828fc74e72fcef8 Mon Sep 17 00:00:00 2001 From: Drew DeVault Date: Fri, 17 May 2019 13:45:20 -0400 Subject: [PATCH] Add man pages --- .gitignore | 3 + Makefile | 26 ++++ README.md | 9 +- doc/aerc-config.5.scd | 319 ++++++++++++++++++++++++++++++++++++++++++ doc/aerc-imap.5.scd | 46 ++++++ doc/aerc-smtp.5.scd | 50 +++++++ doc/aerc.1.scd | 103 ++++++++++++++ 7 files changed, 554 insertions(+), 2 deletions(-) create mode 100644 Makefile create mode 100644 doc/aerc-config.5.scd create mode 100644 doc/aerc-imap.5.scd create mode 100644 doc/aerc-smtp.5.scd create mode 100644 doc/aerc.1.scd 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 ". + + 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 + +Pressing r, then q, will simulate typing in ":reply -q", 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: + +In addition to letters, special keys may be specified in . 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 , 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 , 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 , 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* + 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* + 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* + Copies the selected message to the target folder. + +*delete-message* + Deletes the selected message. + +*move* + Moves the selected message to the target folder. + +*next-folder* , *prev-folder* + Cycles to the next (or previous) folder shown in the sidebar, repeated n + times (default: 1). + +*next-message* [%], *prev-message* [%] + 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* + 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* + 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 , who is assisted by other open +source contributors. For more information about aerc development, see +https://git.sr.ht/~sircmpwn/aerc.