diff options
| -rw-r--r-- | CONTRIBUTING.md | 27 | ||||
| -rw-r--r-- | doc/aerc-config.5.scd | 567 | ||||
| -rw-r--r-- | doc/aerc-imap.5.scd | 62 | ||||
| -rw-r--r-- | doc/aerc-maildir.5.scd | 8 | ||||
| -rw-r--r-- | doc/aerc-notmuch.5.scd | 40 | ||||
| -rw-r--r-- | doc/aerc-search.1.scd | 40 | ||||
| -rw-r--r-- | doc/aerc-sendmail.5.scd | 6 | ||||
| -rw-r--r-- | doc/aerc-smtp.5.scd | 40 | ||||
| -rw-r--r-- | doc/aerc-stylesets.7.scd | 182 | ||||
| -rw-r--r-- | doc/aerc-templates.7.scd | 26 | ||||
| -rw-r--r-- | doc/aerc-tutorial.7.scd | 20 | ||||
| -rw-r--r-- | doc/aerc.1.scd | 413 |
12 files changed, 738 insertions, 693 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a291ee3d..4b93682f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -240,6 +240,32 @@ by running `make fmt`. If gofumpt accepts your code it's most likely properly formatted. +### Man pages + +All `doc/*.scd` files are written in the [scdoc][scdoc] format and compiled to +man pages. + +For consistent rendering, please respect the following guidelines: + +- use `*:command*` to reference commands +- use `*-x*` for flags +- use `_<arg>_` argument placeholders that must be replaced by a suitable value +- use `_foobar.conf_` for file paths +- use `_true_`, `_0_`, `_constant_` for literal constants that must be typed as is +- use `[*-x*]` or `[_<arg>_]` for optional flags/arguments +- use `*-x*|*-y*` for mutually exclusive flags/arguments +- use `*[section]*` to reference sections in configuration files +- use `*foo*` or `*[section].foo*` to reference settings +- if an option does **not** have a default value, simply omit it +- use `*FOO*` and `*$FOO*` for environment variables +- only use `_"quoted values"_` when white space matters +- put command alternatives/aliases on separate lines with `++` suffixes +- use `*<c-x>*` or `*<enter>*` to reference key strokes +- use `# UPPER CASE` for man page sections +- use `*aerc-config*(5)` to reference other man pages +- use `aerc` (instead of `*aerc*` or `_aerc_`) to reference the aerc project or + the aerc program + [git-send-email-tutorial]: https://git-send-email.io/ [git-trailers]: https://git.wiki.kernel.org/index.php/CommitMessageConventions [godoc-comments]: https://go.dev/blog/godoc @@ -247,3 +273,4 @@ If gofumpt accepts your code it's most likely properly formatted. [linux-coding-style]: https://www.kernel.org/doc/html/v5.19-rc8/process/coding-style.html [linux-review]: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#using-reported-by-tested-by-reviewed-by-suggested-by-and-fixes [linux-signoff]: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin +[scdoc]: https://git.sr.ht/~sircmpwn/scdoc diff --git a/doc/aerc-config.5.scd b/doc/aerc-config.5.scd index bdb74bdf..3cfd697c 100644 --- a/doc/aerc-config.5.scd +++ b/doc/aerc-config.5.scd @@ -6,18 +6,18 @@ 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 +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. +_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. +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 "=". +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 @@ -25,25 +25,25 @@ This file is used for configuring the general appearance and behavior of aerc. ## GENERAL OPTIONS -These options are configured in the *[general]* section of aerc.conf. +These options are configured in the *[general]* section of _aerc.conf_. *default-save-path* Used as a default path for save operations if no other path is specified. *pgp-provider* - If set to "gpg", aerc will use system gpg binary and keystore for all + If set to _gpg_, aerc will use system gpg binary and keystore for all crypto operations. Otherwise, the internal openpgp implementation will be used. - Default: internal + Default: _internal_ *unsafe-accounts-conf* - By default, the file permissions of accounts.conf must be restrictive + By default, the file permissions of _accounts.conf_ must be restrictive and only allow reading by the file owner (_0600_). Set this option to - *true* to ignore this permission check. Use this with care as it may + _true_ to ignore this permission check. Use this with care as it may expose your credentials. - Default: false + Default: _false_ *log-file* Output log messages to specified file. A path starting with _~/_ is @@ -61,60 +61,60 @@ These options are configured in the *[general]* section of aerc.conf. ## UI OPTIONS -These options are configured in the *[ui]* section of aerc.conf. +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. - Default: %D %-17.17n %s + Default: _%D %-17.17n %s_ [- *Format specifier* :[ *Description* -| %% +| _%%_ : literal % -| %a +| _%a_ : sender address -| %A +| _%A_ : reply-to address, or sender address if none -| %C +| _%C_ : message number -| %d +| _%d_ : formatted message timestamp -| %D +| _%D_ : formatted message timestamp converted to local timezone -| %f +| _%f_ : sender name and address -| %F +| _%F_ : author name, or recipient name if the message is from you. The address is shown if no name part. -| %g +| _%g_ : message labels (for example notmuch tags) -| %i +| _%i_ : message id -| %n +| _%n_ : sender name, or sender address if none -| %r +| _%r_ : comma-separated list of formatted recipient names and addresses -| %R +| _%R_ : comma-separated list of formatted CC names and addresses -| %s +| _%s_ : subject -| %t +| _%t_ : the (first) address the new email was sent to -| %T +| _%T_ : the account name which received the email -| %u +| _%u_ : sender mailbox name (e.g. "smith" in "smith@example.net") -| %v +| _%v_ : sender first name (e.g. "Alex" in "Alex Smith <smith@example.net>") -| %Z +| _%Z_ : flags (O=old, N=new, r=answered, D=deleted, !=flagged, \*=marked) *timestamp-format* See time.Time#Format at https://godoc.org/time#Time.Format - Default: "2006-01-02 03:04 PM" (ISO 8601 + 12 hour time) + Default: _2006-01-02 03:04 PM_ (ISO 8601 + 12 hour time) *this-day-time-format* Index-only time format for messages that were received/sent today. @@ -148,125 +148,125 @@ These options are configured in the *[ui]* section of aerc.conf. Width of the sidebar, including the border. Set to zero to disable the sidebar. - Default: 20 + Default: _20_ *empty-message* Message to display when viewing an empty folder. - Default: (no messages) + Default: _(no messages)_ *empty-dirlist* Message to display when no folders exists or are all filtered. - Default: (no folders) + Default: _(no folders)_ *mouse-enabled* Enable mouse events in the ui, e.g. clicking and scrolling with the mousewheel - Default: false + Default: _false_ *new-message-bell* Ring the bell when a new message is received. - Default: true + Default: _true_ *pinned-tab-marker* Marker to show before a pinned tab's name. - Default: ` + Default: _`_ *spinner* - Animation shown while loading, split by spinner-delimiter (below) + Animation shown while loading, split by *spinner-delimiter* (below) Examples: - - spinner = "\-\_-,\_-\_" - - spinner = '. , .' - - spinner = "\,|,/,-" + - *spinner* = _"\-\_-,\_-\_"_ + - *spinner* = _'. , .'_ + - *spinner* = _"\,|,/,-"_ - Default: "[..] , [..] , [..] , [..] , [..], [..] , [..] , [..] " + Default: _"[..] , [..] , [..] , [..] , [..], [..] , [..] , [..] "_ *spinner-delimiter* Spinner delimiter to split string into an animation - Default: "," + Default: _,_ *sort* List of space-separated criteria to sort the messages by, see *sort* - command in *aerc*(1) for reference. Prefixing a criterion with "-r " + command in *aerc*(1) for reference. Prefixing a criterion with _-r_ reverses that criterion. Example: - sort = from -r date + *sort* = _from -r date_ *dirlist-format* Describes the format string to use for the directory list. - Default: %n %>r + Default: _%n %>r_ [- *Format specifier* :[ *Description* -| %% +| _%%_ : literal % -| %n +| _%n_ : directory name -| %N +| _%N_ : compacted directory name -| %r +| _%r_ : recent/unseen/total message count -| %>X +| _%>X_ : make format specifier 'X' be right justified *dirlist-delay* Delay after which the messages are actually listed when entering a directory. This avoids loading messages when skipping over folders and makes the UI more responsive. If you do not want that, set it to - 0s. + _0s_. - Default: 200ms + Default: _200ms_ *dirlist-tree* Display the directory list as a foldable tree. - Default: false + Default: _false_ *dirlist-collapse* - If dirlist-tree is enabled, set level at which folders are collapsed - by default. Set to 0 to disable. + If *dirlist-tree* is enabled, set level at which folders are collapsed + by default. Set to _0_ to disable. - Default: 0 + Default: _0_ *next-message-on-delete* Moves to next message when the current message is deleted, archived, or moved. - Default: true + Default: _true_ *auto-mark-read* - Set the "seen" flag when a message is opened in the message viewer. + Set the _seen_ flag when a message is opened in the message viewer. - Default: true + Default: _true_ *completion-popovers* Shows potential auto-completions for text inputs in popovers. - Default: true + Default: _true_ *completion-delay* How long to wait after the last input before auto-completion is triggered. - Default: 250ms + Default: _250ms_ *completion-min-chars* The minimum required characters to allow auto-completion to be triggered after *completion-delay*. - Default: 1 + Default: _1_ -*border-char-vertical* +*border-char-vertical*++ *border-char-horizontal* - Set stylable characters (via the 'border' element) for vertical and + Set stylable characters (via the *border* element) for vertical and horizontal borders. - Default: spaces + Default: _" "_ *stylesets-dirs* The directories where the stylesets are stored. The config takes @@ -282,10 +282,10 @@ These options are configured in the *[ui]* section of aerc.conf. *styleset-name* The name of the styleset to be used to style the ui elements. The - stylesets are stored in the 'stylesets' directory in the config + stylesets are stored in the _stylesets_ directory in the config directory. - Default: default + Default: _default_ Have a look at *aerc-stylesets*(7) as to how a styleset looks like. @@ -296,13 +296,13 @@ These options are configured in the *[ui]* section of aerc.conf. *icon-encrypted* The icon to display for encrypted mails. - Default: [e] + Default: _[e]_ *icon-signed* The icon to display for signed mails where the signature was successfully validated. - Default: [s] + Default: _[s]_ *icon-signed-encrypted* The icon to display for signed and encrypted mails where the signature @@ -313,12 +313,12 @@ These options are configured in the *[ui]* section of aerc.conf. The icon to display for signed mails which could not be verified due to the key being unknown. - Default: [s?] + Default: _[s?]_ *icon-invalid* The icon to display for signed mails where verification failed. - Default: [s!] + Default: _[s!]_ *fuzzy-complete* When typing a command or option, the popover will now show not only the @@ -332,7 +332,7 @@ These options are configured in the *[ui]* section of aerc.conf. order will put the oldest (lowest UID) message on top. This can be useful in cases where the backend does not support sorting. - Default: false + Default: _false_ *reverse-thread-order* Reverse display of the mesage threads. Default order is the the intial @@ -340,7 +340,7 @@ These options are configured in the *[ui]* section of aerc.conf. reverse option will put the initial message at the bottom with the replies on top. - Default: false + Default: _false_ *sort-thread-siblings* Sort the thread siblings according to the sort criteria for the messages. If @@ -348,19 +348,19 @@ These options are configured in the *[ui]* section of aerc.conf. the message UID. This option is only applicable for client-side threading with a backend that enables sorting. - Default: false + Default: _false_ *threading-enabled* Enable a threaded view of messages. If this is not supported by the backend (IMAP server or notmuch), threads will be built by the client. - Default: false + Default: _false_ *force-client-threads* Force threads to be built client-side. Backends that don't support threading will always build threads client side. - Default: false + Default: _false_ ## CONTEXTUAL UI CONFIGURATION @@ -373,17 +373,17 @@ The contextual UI configuration is merged to the base UiConfig in the following order: *Base UIConfig > Account Context > Folder Context > Subject Context.* -*[ui:account=<AccountName>]* +*[ui:account=*_AccountName_*]* Adds account specific configuration with the account name. -*[ui:folder=<FolderName>]* +*[ui:folder=*_FolderName_*]* Add folder specific configuration with the folder name. -*[ui:folder~<Regex>]* +*[ui:folder~*_Regex_*]* Add folder specific configuration for folders whose names match the regular expression. -*[ui:subject~<Regex>]* +*[ui:subject~*_Regex_*]* Add specialized ui configuration for messages that match a given regular expression. @@ -404,121 +404,122 @@ index-format=... ## STATUSLINE -These options are configured in the *[statusline]* section of aerc.conf. +These options are configured in the *[statusline]* section of _aerc.conf_. *render-format* Describes the format string for the statusline format. For a minimal statusline that only shows the current account and - the connection information, use [%a] %c. + the connection information, use _[%a] %c_. To completely mute the statusline (except for push notifications), use - %m only. + _%m_ only. - Default: [%a] %S %>%T + Default: _[%a] %S %>%T_ [- *Format specifier* :[ *Description* -| %% +| _%%_ : literal % -| %a +| _%a_ : active account name -| %d +| _%d_ : active directory name -| %c +| _%c_ : connection state -| %p +| _%p_ : current path -| %m +| _%m_ : mute statusline and show only push notifications -| %S +| _%S_ : general status information (e.g. connection state, filter, search) -| %T +| _%T_ : general on/off information (e.g. passthrough, threading, sorting) -| %> +| _%>_ : does not print anything but all format specifier that follow will be right justified. *separator* Specifies the separator between grouped statusline elements (e.g. for - the %S and %T specifiers in *render-format*). + the _%S_ and _%T_ specifiers in *render-format*). - Default: " | " + Default: _" | "_ *display-mode* Defines the mode for displaying the status elements. - Options: text, icon - - Default: text + Options: _text_, _icon_ + Default: _text_ ## VIEWER -These options are configured in the *[viewer]* section of aerc.conf. +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 + 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 + Default: _text/plain,text/html_ *header-layout* Defines the default headers to display when viewing a message. To display - multiple headers in the same row, separate them with a pipe, e.g. "From|To". + multiple headers in the same row, separate them with a pipe, e.g. _From|To_. Rows will be hidden if none of their specified headers are present in the message. Notmuch tags can be displayed by adding Labels. Authentication information from the Authentication-Results header can be - displayed by adding DKIM, SPF or DMARC. To show more information - than just the authentication result, append a plus sign (+) to the header name - (e.g. DKIM+). + displayed by adding _DKIM_, _SPF_ or _DMARC_. To show more information + than just the authentication result, append a plus sign (*+*) to the header name + (e.g. _DKIM+_). - Default: From|To,Cc|Bcc,Date,Subject + Default: _From|To,Cc|Bcc,Date,Subject_ *show-headers* Default setting to determine whether to show full headers or only parsed ones in message viewer. - Default: false + Default: _false_ *always-show-mime* Whether to always show the mimetype of an email, even when it is just a single part. - Default: false + Default: _false_ *parse-http-links* Parses and extracts http links when viewing a message. Links can then be - accessed with the open-link command. + accessed with the *open-link* command. - Default: true + Default: _true_ ## COMPOSE -These options are configured in the *[compose]* section of aerc.conf. +These options are configured in the *[compose]* 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). + environment supports it. + + Defaults to *$EDITOR*, or *vi*(1). *header-layout* Defines the default headers to display when composing a message. To display - multiple headers in the same row, separate them with a pipe, e.g. "To|From". + multiple headers in the same row, separate them with a pipe, e.g. _To|From_. - Default: To|From,Subject + Default: _To|From,Subject_ *address-book-cmd* Specifies the command to be used to tab-complete email addresses. Any - occurrence of "%s" in the address-book-cmd will be replaced with anything + occurrence of _%s_ in the *address-book-cmd* will be replaced with anything the user has typed after the last comma. The command must output the completions to standard output, one completion @@ -527,28 +528,28 @@ These options are configured in the *[compose]* section of aerc.conf. if present, will be treated as the contact name. Additional fields are ignored. - This parameter can also be set per account in accounts.conf. + This parameter can also be set per account in _accounts.conf_. Example: - address-book-cmd = khard email --remove-first-line --parsable '%s' + *address-book-cmd* = _khard email --remove-first-line --parsable %s_ *file-picker-cmd* Specifies the command to be used to select attachments. Any occurence of - '%s' in the file-picker-cmd will be replaced with the argument <arg> - to :attach -m <arg>. + _%s_ in the *file-picker-cmd* will be replaced with the argument _<arg>_ + to *:attach -m* _<arg>_. The command must output the selected files to standard output, one file per line. Example: - file-picker-cmd = fzf --multi --query=%s + *file-picker-cmd* = _fzf --multi --query=%s_ *reply-to-self* - If set to false, do not mail yourself when replying (e.g., if replying + If set to _false_, do not mail yourself when replying (e.g., if replying to emails previously sent by yourself, address your replies to the - original To: and Cc:). + original To and Cc). - Default: true + Default: _true_ *no-attachment-warning* Specifies a regular expression against which an email's body should be @@ -557,32 +558,30 @@ These options are configured in the *[compose]* section of aerc.conf. disable this feature. Uses Go's regexp syntax, documented at https://golang.org/s/re2syntax. - The "(?im)" flags are set by default (case-insensitive and multi-line). + The _(?im)_ flags are set by default (case-insensitive and multi-line). Example: - no-attachment-warning = ^[^>]\*attach(ed|ment) - - Default: none + *no-attachment-warning* = _^[^>]\*attach(ed|ment)_ ## 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. +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. +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_. aerc ships with some default filters installed in the share directory (usually _/usr/share/aerc/filters_). Note that these may have additional dependencies that aerc does not have alone. -The filter commands are invoked with sh -c [command]. The following folders are -appended to the system $PATH to allow referencing filters from their name only. +The filter commands are invoked with _sh -c command_. The following folders are +appended to the system *$PATH* to allow referencing filters from their name only. ``` ${XDG_CONFIG_HOME:-~/.config}/aerc/filters @@ -593,15 +592,15 @@ $PREFIX/share/aerc/filters The following variables are defined in the filter command environment: -_AERC_MIME_TYPE_ +*AERC_MIME_TYPE* the part MIME type/subtype -_AERC_FORMAT_ +*AERC_FORMAT* the part content type format= parameter (e.g. format=flowed) -_AERC_FILENAME_ +*AERC_FILENAME* the attachment filename (if any) -_AERC_SUBJECT_ +*AERC_SUBJECT* the message Subject header value -_AERC_FROM_ +*AERC_FROM* the message From header value Note that said email body is converted into UTF-8 before being passed to @@ -627,9 +626,9 @@ image/*=catimg -w $(tput cols) - Openers allow you to specify the command to use for the *:open* action on a per-MIME-type basis. They are configured in the *[openers]* section of -aerc.conf. +_aerc.conf_. -*{}* is expanded as the temporary filename to be opened. If it is not +_{}_ is expanded as the temporary filename to be opened. If it is not encountered in the command, the temporary filename will be appened to the end of the command. Environment variables are also expanded. Tilde is not expanded. @@ -646,7 +645,7 @@ message/rfc822=thunderbird Triggers specify commands to execute when certain events occur. -They are configured in the *[triggers]* section of aerc.conf. +They are configured in the *[triggers]* section of _aerc.conf_. *new-email* Executed when a new email arrives in the selected folder. @@ -658,14 +657,14 @@ They are configured in the *[triggers]* section of aerc.conf. ## TEMPLATES -Templates are used to populate the body of an email. The compose, reply -and forward commands can be called with the -T flag with the name of the +Templates are used to populate the body of an email. The *:compose*, *:reply* +and *:forward* commands can be called with the *-T* flag with the name of the template name. aerc ships with some default templates installed in the share directory (usually _/usr/share/aerc/templates_). -These options are configured in the *[templates]* section of aerc.conf. +These options are configured in the *[templates]* section of _aerc.conf_. *template-dirs* The directory where the templates are stored. The config takes @@ -682,17 +681,17 @@ These options are configured in the *[templates]* section of aerc.conf. *new-message* The default template to be used for new messages. - Default: "new_message" + Default: _new_message_ *quoted-reply* The default template to be used for quoted replies. - Default: "quoted_reply" + Default: _quoted_reply_ *forwards* The default template to be used for forward as body. - Default: "forward_as_body" + Default: _forward_as_body_ # ACCOUNTS.CONF @@ -710,7 +709,7 @@ Note that many of these configuration options are written for you, such as *archive* Specifies a folder to use as the destination of the *:archive* command. - Default: Archive + Default: _Archive_ *check-mail* Specifies an interval to check for new mail. Mail will be checked at @@ -720,40 +719,40 @@ Note that many of these configuration options are written for you, such as conjunction with this option. See *aerc-maildir* and *aerc-notmuch* for more information. - Setting this option to 0 will disable check-mail + Setting this option to _0_ will disable *check-mail* Example: - check-mail = 5m + *check-mail* = _5m_ - Default: 0 + Default: _0_ *copy-to* - Specifies a folder to copy sent mails to, usually "Sent". + Specifies a folder to copy sent mails to, usually _Sent_. *default* Specifies the default folder to open in the message list when aerc configures this account. - Default: INBOX + Default: _INBOX_ *folders* Specifies the comma separated list of folders to display in the sidebar. - Names prefixed with ~ are interpreted as regular expressions. + Names prefixed with _~_ are interpreted as regular expressions. Default: all folders *folders-exclude* Specifies the comma separated list of folders to exclude from the sidebar. - Names prefixed with ~ are interpreted as regular expressions. + Names prefixed with _~_ are interpreted as regular expressions. Note that this overrides anything from *folders*. Default: no folders *enable-folders-sort* - If true, folders are sorted, first by specified folders (see *folders-sort*), + If _true_, folders are sorted, first by specified folders (see *folders-sort*), then alphabetically. - Default: true + Default: _true_ *folders-sort* Specifies a comma separated list of folders to be shown at the top of the @@ -761,12 +760,13 @@ Note that many of these configuration options are written for you, such as *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>". + an RFC 5322-compatible string, such as _Your Name <you@example.org>_. *aliases* All aliases of the current account. These will be used to fill in the From: field. Make sure that your email server accepts this value, or for example - use *aerc-sendmail*(5) in combination with msmtp and --read-envelope-from. + use *aerc-sendmail*(5) in combination with *msmtp*(1) and + *--read-envelope-from*. *outgoing* Specifies the transport for sending outgoing emails on this account. It @@ -782,37 +782,37 @@ Note that many of these configuration options are written for you, such as *outgoing-cred-cmd-cache* By default, the credentials returned by the command will be cached until - aerc is shut down. If set to false, *outgoing-cred-cmd* will be executed + aerc is shut down. If set to _false_, *outgoing-cred-cmd* will be executed every time an email is to be sent. - Default: true + Default: _true_ *pgp-auto-sign* - If true, all outgoing emails from this account will be signed (if a signing + If _true_, all outgoing emails from this account will be signed (if a signing key is available). - Default: false + Default: _false_ *pgp-key-id* Specify the key id to use when signing a message. Can be either short or long key id. If unset, aerc will look up the key by email. *pgp-opportunistic-encrypt* - If true, any outgoing email from this account will be encrypted when all - recipients (including "cc" and "bcc" field) have a public key available in + If _true_, any outgoing email from this account will be encrypted when all + recipients (including Cc and Bcc field) have a public key available in the keyring. - Default: false + Default: _false_ *postpone* Specifies the folder to save postponed messages to. - Default: Drafts + Default: _Drafts_ *send-as-utc* Converts the timestamp of the Date header to UTC. - Default: false + Default: _false_ *source* Specifies the source for reading incoming emails on this account. This key @@ -833,7 +833,7 @@ Note that many of these configuration options are written for you, such as to emails sent from this account. *signature-cmd* - Specifies the command to execute in *sh* in order to obtain the + Specifies the command to execute with _sh -c_ in order to obtain the signature to be added to emails sent from this account. If the command fails then *signature-file* is used instead. @@ -841,17 +841,17 @@ Note that many of these configuration options are written for you, such as Comma-separated list of trustworthy hostnames from which the Authentication Results header will be displayed. Entries can be regular expressions. If you want to trust any host (e.g. for debugging), - use the wildcard \*. + use the wildcard _\*_. *subject-re-pattern* When replying to a message, this is the regular expression that will be used to match the prefix of the original message's subject that has to be removed, to create the subject line of the new message. - Typically, this will be used to avoid a repetition of the "Re: " + Typically, this will be used to avoid a repetition of the Re: prefix in the subject header. The default will match known - translations for the common "Re: ". + translations for the common Re:. - Default: (?i)^((AW|RE|SV|VS|ODP|R): ?)+ + Default: _(?i)^((AW|RE|SV|VS|ODP|R): ?)+_ # BINDS.CONF @@ -868,7 +868,7 @@ are: *[view::passthrough]* keybindings for the viewer, when in key passthrough mode - (toggled with :toggle-key-passthrough) + (toggled with *:toggle-key-passthrough*) *[compose]* keybindings for the message composer @@ -884,18 +884,19 @@ are: You may also configure account specific key bindings for each context: -*[context:account=<AccountName>]* - keybindings for this context and account, where <AccountName> matches - the account name you provided in *accounts.conf*. +*[context:account=*_AccountName_*]* + keybindings for this context and account, where _AccountName_ matches + the account name you provided in _accounts.conf_. Folder-specific bindings can be configured for message lists: -*[messages:folder=<FolderName>]* +*[messages:folder=*_FolderName_*]* keybindings under this section will be specific to the folder named - <FolderName>. Keybindings from a *folder* specifier will take precedence - over *account* specifiers + _FolderName_. Keybindings from a folder specifier will take precedence + over account specifiers Example: + ``` [messages:account=Mailbox] c = :cf path:mailbox/** and<space> @@ -915,212 +916,212 @@ 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 +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. + If set to _true_, global keybindings will not be effective in this context. - Default: false + Default: _false_ *$ex* This can be set to a keystroke which will bring up the command input in this context. - Default: ':' + Default: _:_ -In addition to letters, special keys may be specified in <angle brackets>. The +In addition to letters, special keys may be specified in *<angle brackets>*. The following special keys are supported: [[ *Name* :- *Description* -| space +| *<space>* : " " -| semicolon +| *<semicolon>* : ; -| tab +| *<tab>* : Tab -| enter +| *<enter>* : Enter -| up +| *<up>* : Up arrow -| c-up +| *<c-up>* : Ctrl+Up -| a-up +| *<a-up>* : Alt+Up -| down +| *<down>* : Down arrow -| c-down +| *<c-down>* : Ctrl+Down -| a-down +| *<a-down>* : Alt+Down -| right +| *<right>* : Right arrow -| c-right +| *<c-right>* : Ctrl+Right -| a-right +| *<a-right>* : Alt+Right -| left +| *<left>* : Left arrow -| c-left +| *<c-left>* : Ctrl+Left -| a-left +| *<a-left>* : Alt+Left -| pgup +| *<pgup>* : Page Up -| c-pgup +| *<c-pgup>* : Ctrl+PageUp -| a-pgup +| *<a-pgup>* : Alt+PageUp -| pgdn +| *<pgdn>* : Page Down -| c-pgdn +| *<c-pgdn>* : Ctrl+PageDn -| a-pgdn +| *<a-pgdn>* : Alt+PageDn -| home +| *<home>* : Home -| end +| *<end>* : End -| insert +| *<insert>* : Insert -| delete +| *<delete>* : Delete -| exit +| *<exit>* : Exit -| cancel +| *<cancel>* : Cancel -| print +| *<print>* : Print screen -| pause +| *<pause>* : Pause -| backtab +| *<backtab>* : Shift+Tab -| c-space +| *<c-space>* : Ctrl+Space -| a-space +| *<a-space>* : Alt+Space -| c-a +| *<c-a>* : Ctrl+a | a-a : Alt+a -| c-b +| *<c-b>* : Ctrl+b -| a-b +| *<a-b>* : Alt+b -| c-c +| *<c-c>* : Ctrl+c -| a-c +| *<a-c>* : Alt+c -| c-d +| *<c-d>* : Ctrl+d -| a-d +| *<a-d>* : Alt+d -| c-e +| *<c-e>* : Ctrl+e -| a-e +| *<a-e>* : Alt+e -| c-f +| *<c-f>* : Ctrl+f -| a-f +| *<a-f>* : Alt+f -| c-g +| *<c-g>* : Ctrl+g -| a-g +| *<a-g>* : Alt+g -| c-h +| *<c-h>* : Ctrl+h -| a-h +| *<a-h>* : Alt+h -| c-i +| *<c-i>* : Ctrl+i -| a-i +| *<a-i>* : Alt+i -| c-j +| *<c-j>* : Ctrl+j -| a-j +| *<a-j>* : Alt+j -| c-k +| *<c-k>* : Ctrl+k -| a-k +| *<a-k>* : Alt+k -| c-l +| *<c-l>* : Ctrl+l -| a-l +| *<a-l>* : Alt+l -| c-m +| *<c-m>* : Ctrl+m -| a-m +| *<a-m>* : Alt+m -| c-n +| *<c-n>* : Ctrl+n -| a-n +| *<a-n>* : Alt+n -| c-o +| *<c-o>* : Ctrl+o -| a-o +| *<a-o>* : Alt+o -| c-p +| *<c-p>* : Ctrl+p -| a-p +| *<a-p>* : Alt+p -| c-q +| *<c-q>* : Ctrl+q -| a-q +| *<a-q>* : Alt+q -| c-r +| *<c-r>* : Ctrl+r -| a-r +| *<a-r>* : Alt+r -| c-s +| *<c-s>* : Ctrl+s -| a-s +| *<a-s>* : Alt+s -| c-t +| *<c-t>* : Ctrl+t -| a-t +| *<a-t>* : Alt+t -| c-u +| *<c-u>* : Ctrl+u -| a-u +| *<a-u>* : Alt+u -| c-v +| *<c-v>* : Ctrl+v -| a-v +| *<a-v>* : Alt+v -| c-w +| *<c-w>* : Ctrl+w -| a-w +| *<a-w>* : Alt+w -| c-x +| *<c-x>* : Ctrl+x -| a-x +| *<a-x>* : Alt+x -| c-y +| *<c-y>* : Ctrl+y -| a-y +| *<a-y>* : Alt+y -| c-z +| *<c-z>* : Ctrl+z -| a-z +| *<a-z>* : Alt+z -| c-] +| *<c-]>* : Ctrl+] -| a-] +| *<a-]>* : Alt+] -| c-[ +| *<c-[>* : Ctrl+[ -| a-[ +| *<a-[>* : Alt+[ -| c-^ +| *<c-^>* : Ctrl+^ -| a-^ +| *<a-^>* : Alt+^ -| c-\_ +| *<c-\_>* : Ctrl+\_ -| a-\_ +| *<a-\_>* : Alt+\_ # SEE ALSO diff --git a/doc/aerc-imap.5.scd b/doc/aerc-imap.5.scd index b3dc5166..e26003dc 100644 --- a/doc/aerc-imap.5.scd +++ b/doc/aerc-imap.5.scd @@ -13,53 +13,53 @@ IMAP extensions: # CONFIGURATION -IMAP configuration may be done interactively with the :new-account command. +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: +In _accounts.conf_ (see *aerc-config*(5)), the following IMAP-specific options +are available: *source* - imap[s][+insecure|+oauthbearer|+xoauth2]://username[:password]@hostname[:port]?[:oauth2_params] + _<scheme>_://_<username>_[_:<password>_]_@<hostname>_[_:<port>_]_?_[_<oauth2_params>_] - Remember that all fields must be URL encoded. The "@" symbol, when URL - encoded, is *%40*. + Remember that all fields must be URL encoded. The _@_ symbol, when URL + encoded, is _%40_. - The meaning of the scheme component is: + Possible values of _<scheme>_ are: - *imap://*: + _imap_ IMAP with STARTTLS - *imap+insecure://*: + _imap+insecure_ IMAP without STARTTLS - *imaps*: + _imaps_ IMAP with TLS/SSL - *imaps+oauthbearer://* + _imaps+oauthbearer_ IMAP with TLS/SSL using OAUTHBEARER Authentication - *oauth2_params:* + _<oauth2_params>_: - If specified and a token_endpoint is provided, the configured password - is used as a refresh token to obtain an access token. If token_endpoint + If specified and a _token_endpoint_ is provided, the configured password + is used as a refresh token to obtain an access token. If _token_endpoint_ is omitted, refresh token exchange is skipped, and the password acts like an access token instead. - - token_endpoint (optional) - - client_id (optional) - - client_secret (optional) - - scope (optional) + - _token_endpoint_ (optional) + - _client_id_ (optional) + - _client_secret_ (optional) + - _scope_ (optional) Example: imaps+oauthbearer://...?token_endpoint=https://...&client_id= - *imaps+xoauth2://* + _imaps+xoauth2_ IMAP with TLS/SSL using XOAUTH2 Authentication. Parameters are the same as OAUTHBEARER. *source-cred-cmd* Specifies the command to run to get the password for the IMAP - account. This command will be run using `sh -c [command]`. If a + account. This command will be run using _sh -c command_. If a password is specified in the *source* option, the password will take precedence over this command. @@ -70,7 +70,7 @@ available: Maximum delay to establish a connection to the IMAP server. See https://pkg.go.dev/time#ParseDuration. - Default: 30s + Default: _30s_ *keepalive-period* The interval between the last data packet sent (simple ACKs are not @@ -96,50 +96,50 @@ available: truncated. By default, the system tcp socket settings are used. - If keepalive-period is specified, this option defaults to 3s. + If *keepalive-period* is specified, this option defaults to _3s_. This option is only supported on linux. On other platforms, it will be ignored. *check-mail-include* Specifies the comma separated list of folders to include when checking for - new mail with *check-mail*. Names prefixed with ~ are interpreted as regular + new mail with *:check-mail*. Names prefixed with _~_ are interpreted as regular expressions. By default, all folders are included. *check-mail-exclude* Specifies the comma separated list of folders to exclude when checking for - new mail with *check-mail*. Names prefixed with ~ are interpreted as regular + new mail with *:check-mail*. Names prefixed with _~_ are interpreted as regular expressions. Note that this overrides anything from *check-mail-include*. By default, no folders are excluded. *cache-headers* - If set to true, headers will be cached. The cached headers will be stored - in $XDG_CACHE_HOME/aerc, which defaults to ~/.cache/aerc. + If set to _true_, headers will be cached. The cached headers will be stored + in _$XDG_CACHE_HOME/aerc_, which defaults to _~/.cache/aerc_. - Default: false + Default: _false_ *cache-max-age* Defines the maximum age of cached files. Note: the longest unit of time - cache-max-age can be specified in is hours. Set to 0 to disable cleaning + *cache-max-age* can be specified in is hours. Set to _0_ to disable cleaning the cache - Default: 720h (30 days) + Default: _720h_ (30 days) *idle-timeout* The length of time the client will wait for the server to send any final update before the IDLE is closed. - Default: 10ms + Default: _10ms_ *idle-debounce* Specifies the length of time from the last client command until the idler starts. - Default: 10ms + Default: _10ms_ # SEE ALSO diff --git a/doc/aerc-maildir.5.scd b/doc/aerc-maildir.5.scd index ebd76b06..d11140ac 100644 --- a/doc/aerc-maildir.5.scd +++ b/doc/aerc-maildir.5.scd @@ -10,8 +10,8 @@ aerc implements the maildir format. # CONFIGURATION -Maildir accounts currently are not supported with the :new-account command and -must be added manually to the *aerc-config*(5) file. +Maildir accounts currently are not supported with the *:new-account* command and +must be added manually to the _accounts.conf_ file. The following maildir-specific options are available: @@ -29,13 +29,13 @@ The following maildir-specific options are available: Default: 10s *source* - maildir://path + maildir://_<path>_ The *source* indicates the path to the directory containing your maildirs rather than one maildir specifically. The path portion of the URL following _maildir://_ must be either an absolute - path prefixed by */* or a path relative to your home directory prefixed with + path prefixed by _/_ or a path relative to your home directory prefixed with *~*. For example: source = maildir:///home/me/mail diff --git a/doc/aerc-notmuch.5.scd b/doc/aerc-notmuch.5.scd index e94cc057..0964ec29 100644 --- a/doc/aerc-notmuch.5.scd +++ b/doc/aerc-notmuch.5.scd @@ -9,15 +9,15 @@ aerc-notmuch - notmuch configuration for *aerc*(1) aerc supports using the notmuch email system as a backend, for fast indexing and searching. -For this to be enabled, aerc needs to be build with notmuch support.++ +For this to be enabled, aerc needs to be build with notmuch support. Refer to the installation instructions for details. # CONFIGURATION -Notmuch accounts currently are not supported with the :new-account command and +Notmuch accounts currently are not supported with the *:new-account* command and must be added manually. -In accounts.conf (see *aerc-config*(5)), the following notmuch-specific +In _accounts.conf_ (see *aerc-config*(5)), the following notmuch-specific options are available: *check-mail-cmd* @@ -34,48 +34,50 @@ options are available: Default: 10s *source* - notmuch://path + notmuch://_<path>_ The *source* indicates the path to the directory containing your notmuch - database (usually a .notmuch folder). + database (usually a _.notmuch/_ folder). The path portion of the URL following _notmuch://_ must be either an absolute - path prefixed by */* or a path relative to your home directory prefixed with - *~*. For example: + path prefixed by _/_ or a path relative to your home directory prefixed with + _~_. For example: source = notmuch:///home/me/mail source = notmuch://~/mail *query-map* - Path to a file containing a mapping from display name to notmuch query in - the form of NAME=QUERY.++ -Multiple entries can be specified, one per line.++ -Lines starting with '#' are ignored and serve as comments. + Path to a file containing a mapping from display name to notmuch query + in the form of *<NAME>*=_<QUERY>_. + + Multiple entries can be specified, one per line. Lines starting with _#_ + are ignored and serve as comments. e.g. inbox=tag:inbox and not tag:archived *exclude-tags* Comma separated list of tags which will be excluded from query results, - unless explicitly mentioned in the query.++ -This can for example be useful if you use an archive or spam tag. + unless explicitly mentioned in the query. + + This can for example be useful if you use an _archive_ or _spam_ tag. *maildir-store* Path to the maildir store containing the message files backing the notmuch database. This is often the same as the notmuch database path. This is optional. If specified, it will be used by aerc to list - available folders and enable commands such as :delete and :archive. + available folders and enable commands such as *:delete* and *:archive*. # USAGE -Notmuch shows slightly different behavior than for example imap.++ -Some commands are slightly different in semantics and mentioned below: +Notmuch shows slightly different behavior than for example imap. Some commands +are slightly different in semantics and mentioned below: -*cf* <notmuch query> +*cf* _<notmuch query>_ The change folder command allows for arbitrary notmuch queries. Performing a - cf command will perform a new top-level notmuch query. + *:cf* command will perform a new top-level notmuch query. -*filter* <notmuch query> +*filter* _<notmuch query>_ The filter command for notmuch backends takes in arbitrary notmuch queries. It applies the query on the set of messages shown in the message list. This can be used to perform successive filters/queries. It is equivalent to diff --git a/doc/aerc-search.1.scd b/doc/aerc-search.1.scd index c99bc0fd..119e222d 100644 --- a/doc/aerc-search.1.scd +++ b/doc/aerc-search.1.scd @@ -6,11 +6,11 @@ aerc-search - search and filter patterns and options for *aerc*(1) # MAILDIR & IMAP -*search* [-ruba] [-x <flag>] [-X <flag>] [-f <from>] [-t <to>] [-c <cc>] [terms...] +*search* [*-ruba*] [*-x* _<flag>_] [*-X* _<flag>_] [*-f* _<from>_] [*-t* _<to>_] [*-c* _<cc>_] [_<terms>_...] Searches the current folder for messages matching the given set of conditions. - Each space separated term of *terms*, if provided, is searched + Each space separated term of _<terms>_, if provided, is searched case-insensitively among subject lines unless *-b* or *-a* are provided. @@ -18,41 +18,39 @@ aerc-search - search and filter patterns and options for *aerc*(1) *-u*: Search for unread messages - *-x <flag>*, *-X <flag>*: Restrict search to messages with or without <flag> + *-x* _<flag>_, *-X* _<flag>_: Restrict search to messages with or without _<flag>_ + Use *-x* to search for messages with the flag set. + Use *-X* to search for messages without the flag set. - Use *-x* to search for messages with the flag set. - Use *-X* to search for messages without the flag set. - - Possible values are: - - Seen - Read messages - - Answered - Replied messages - - Flagged - Flagged messages + Possible values are: + _Seen_ + Read messages + _Answered_ + Replied messages + _Flagged_ + Flagged messages *-b*: Search in the body of the messages *-a*: Search in the entire text of the messages - *-f <from>*: Search for messages from <from> + *-f* _<from>_: Search for messages from _<from>_ - *-t <to>*: Search for messages to <to> + *-t* _<to>_: Search for messages to _<to>_ - *-c <cc>*: Search for messages cc'ed to <cc> + *-c* _<cc>_: Search for messages cc'ed to _<cc>_ # NOTMUCH -*search* <query...> +*search* _query_... You can use the full notmuch query language as described in *notmuch-search-terms*(7). The query will only apply on top of the active folder query. - Example: jump to next unread `:search tag:unread` + Example, jump to next unread: + + :search tag:unread # SEE ALSO diff --git a/doc/aerc-sendmail.5.scd b/doc/aerc-sendmail.5.scd index 51e89a7f..f85f9da3 100644 --- a/doc/aerc-sendmail.5.scd +++ b/doc/aerc-sendmail.5.scd @@ -10,14 +10,14 @@ aerc can defer to sendmail for the delivery of outgoing messages. # CONFIGURATION -In accounts.conf (see *aerc-config*(5)), the following sendmail-specific +In _accounts.conf_ (see *aerc-config*(5)), the following sendmail-specific options are available: *outgoing* - /path/to/sendmail + _</path/to/sendmail>_ This should be set to the path to the sendmail binary you wish to use, - which is generally /usr/sbin/sendmail. aerc will execute it with a list of + which is generally _/usr/sbin/sendmail_. aerc will execute it with a list of recipients on the command line and pipe the message to deliver to stdin. # SEE ALSO diff --git a/doc/aerc-smtp.5.scd b/doc/aerc-smtp.5.scd index 3a731b45..be7e727c 100644 --- a/doc/aerc-smtp.5.scd +++ b/doc/aerc-smtp.5.scd @@ -10,50 +10,50 @@ aerc implements the SMTP protocol as specified by RFC 5321. # CONFIGURATION -SMTP configuration may be done interactively with the :new-account command. +SMTP configuration may be done interactively with the *:new-account* command. -In accounts.conf (see *aerc-config*(5)), the following SMTP-specific options are +In _accounts.conf_ (see *aerc-config*(5)), the following SMTP-specific options are available: *outgoing* - smtp[s][+plain|+login|+none|+oauthbearer|+xoauth2]://username[:password]@hostname[:port]?[:oauth2_params] + _<scheme>_+_<auth>_://_<username>_[_:<password>_]_@<hostname>_[_:<port>_]?[_<oauth2_params>_] - Remember that all fields must be URL encoded. The "@" symbol, when URL - encoded, is *%40*. + Remember that all fields must be URL encoded. The _@_ symbol, when URL + encoded, is _%40_. - The meaning of the scheme component is: + The value of _<scheme>_ can be: - *smtp://*: + _smtp_ Unencrypted SMTP - *smtps://*: + _smtps_ SMTP with TLS/SSL Additionally, you can specify an authentication mechanism like so: - *+none*: + _none_ No authentication is required to use this SMTP server. You may omit the username and password in this case. - *+plain*: + _plain_ Authenticate with a username and password using AUTH PLAIN. This is the default behavior. - *+login*: + _login_ Authenticate with a username and password using AUTH LOGIN. This is an obsolete protocol, but is required for some common webmail providers. - *+oauthbearer*: - SMTP with TLS/SSL using OAUTHBEARER Authentication. See documentation in - *aerc-imap*(5) for usage. + _oauthbearer_ + SMTP with TLS/SSL using OAUTHBEARER Authentication. See + documentation in *aerc-imap*(5) for usage. - *+xoauth2*: - SMTP with TLS/SSL using XOAUTH2 Authentication. See documentation in - *aerc-imap*(5) for usage. + _xoauth2_ + SMTP with TLS/SSL using XOAUTH2 Authentication. See + documentation in *aerc-imap*(5) for usage. *outgoing-cred-cmd* Specifies the command to run to get the password for the SMTP - account. This command will be run using `sh -c [command]`. If a + account. This command will be run using _sh -c [command]_. If a password is specified in the *outgoing* option, the password will take precedence over this command. @@ -61,8 +61,8 @@ available: outgoing-cred-cmd = pass hostname/username *smtp-starttls* - Set this to `yes` if the server uses STARTTLS. In that case you should also - use *smtp* instead of *smtps*. + Set this to _yes_ if the server uses STARTTLS. In that case you should also + use _smtp://_ instead of _smtps://_. # SEE ALSO diff --git a/doc/aerc-stylesets.7.scd b/doc/aerc-stylesets.7.scd index c3994d6c..06efeba2 100644 --- a/doc/aerc-stylesets.7.scd +++ b/doc/aerc-stylesets.7.scd @@ -11,21 +11,17 @@ its ui. # STYLESET CONFIGURATION -Aerc uses a simple configuration file to describe a styleset. The -styleset is described as key, value pairs. In each line, the key -represents the style object it signifies and the color/attribute of -that is modified. +The styleset is described as *<object>*.*<attribute>* = _<value>_ pairs. For example, in the line below, the foreground color of the -style object "msglist_unread" is set to "cornflowerblue" -``` -msglist_unread.fg=cornflowerblue -``` +style object *msglist_unread* is set to _cornflowerblue_ + + *msglist_unread*.*fg* = _cornflowerblue_ The configuration also allows wildcard matching of the keys to configure multiple style objects at a time. -## STYLE +## ATTRIBUTES The following options are available to be modified for each of the style objects. @@ -33,55 +29,58 @@ style objects. *fg* The foreground color of the style object is set. - Syntax: `<style_object>.fg=<color>` + Syntax: *<object>*.*fg* = _<color>_ *bg* The background color of the style object is set. - Syntax: `<style_object>.bg=<color>` + Syntax: *<object>*.*bg* = _<color>_ *bold* The bold attribute of the style object is set/unset. - Syntax: `<style_object>.bold=<true|false|toggle>` + Syntax: *<object>*.*bold* = _true_|_false_|_toggle_ *blink* The blink attribute of the style object is set/unset. - _The terminal needs to support blinking text_ + The terminal needs to support blinking text. - Syntax: `<style_object>.blink=<true|false|toggle>` + Syntax: *<object>*.*blink* = _true_|_false_|_toggle_ *underline* The underline attribute of the style object is set/unset. - _The terminal needs to support underline text_ + The terminal needs to support underline text. - Syntax: `<style_object>.underline=<true|false|toggle>` + Syntax: *<object>*.*underline* = _true_|_false_|_toggle_ *italic* The italic attribute of the style object is set/unset. - _The terminal needs to support italic text_ + The terminal needs to support italic text. - Syntax: `<style_object>.italic=<true|false|toggle>` + Syntax: *<object>*.*italic* = _true_|_false_|_toggle_ *reverse* Reverses the color of the style object. Exchanges the foreground and background colors. - Syntax: `<style_object>.reverse=<true|false|toggle>` - _If the value is false, it doesn't change anything_ + Syntax: *<object>*.*reverse* = _true_|_false_|_toggle_ + + If the value is _false_, it doesn't change anything. *normal* All the attributes of the style object are unset. - Syntax: `<style_object>.normal=<true>` - _The value doesn't matter_ + Syntax: *<object>*.*normal* = true + + The value doesn't matter. *default* Set the style object to the default style of the context. Usually based on the terminal. - Syntax: `<style_object>.default=<true>` - _The value doesn't matter_ + Syntax: *<object>*.*default* = true + + The value doesn't matter. ## STYLE OBJECTS @@ -90,63 +89,63 @@ styling. [[ *Style Object* :[ *Description* -| default +| *default* : The default style object used for normal ui elements while not using specialized configuration. -| error +| *error* : The style used to show errors. -| warning +| *warning* : The style used when showing warnings. -| success +| *success* : The style used for success messages. -| title +| *title* : The style object used to style titles in ui elements. -| header +| *header* : The style object used to style headers in ui elements. -| statusline_default +| *statusline_default* : The default style applied to the statusline. -| statusline_error +| *statusline_error* : The style used for error messages in statusline. -| statusline_success +| *statusline_success* : The style used for success messages in statusline. -| msglist_default +| *msglist_default* : The default style for messages in a message list. -| msglist_unread +| *msglist_unread* : Unread messages in a message list. -| msglist_read +| *msglist_read* : Read messages in a message list. -| msglist_flagged +| *msglist_flagged* : The messages with the flagged flag. -| msglist_deleted +| *msglist_deleted* : The messages marked as deleted. -| msglist_marked +| *msglist_marked* : The messages with the marked flag. -| msglist_result +| *msglist_result* : The messages which match the current search. -| dirlist_default +| *dirlist_default* : The default style for directories in the directory list. -| dirlist_unread +| *dirlist_unread* : The style used for directories with unread messages -| dirlist_recent +| *dirlist_recent* : The style used for directories with recent messages -| completion_default +| *completion_default* : The default style for the completion engine. -| completion_gutter +| *completion_gutter* : The completion gutter. -| completion_pill +| *completion_pill* : The completion pill. -| tab +| *tab* : The style for the tab bar. -| stack +| *stack* : The style for ui stack element. -| spinner +| *spinner* : The style for the loading spinner. -| border -: The style used to draw borders. *Only the background color is used unless you customize border-char-vertical and/or border-char-horizontal in aerc.conf*. -| selector_default +| *border* +: The style used to draw borders (only the *bg* color is used unless you customize *border-char-vertical* and/or *border-char-horizontal* in _aerc.conf_). +| *selector_default* : The default style for the selector ui element. -| selector_focused +| *selector_focused* : The focused item in a selector ui element. -| selector_chooser +| *selector_chooser* : The item chooser in a selector ui element. ## FNMATCH STYLE WILDCARD MATCHING @@ -155,81 +154,82 @@ The styleset configuration can be made simpler by using the fnmatch style wildcard matching for the style object. The special characters used in the fnmatch wildcards are: + [[ *Pattern* :[ *Meaning* -| \* +| *\** : Matches everything -| \? +| *\?* : Matches any single character For example, the following wildcards can be made using this syntax. + [[ *Example* -:[ Description -| \*.fg=blue +:[ *Description* +| *\**.*fg* = _blue_ : Set the foreground color of all style objects to blue. -| \*list.bg=hotpink +| *\*list*.*bg* = _hotpink_ : Set the background color of all style objects that end in list to hotpink. ## SELECTED MODIFIER -The selected modifier can be applied to any style object. The style provided for -the selected modifier is applied on top of the style object it corresponds to. +The *selected* modifier can be applied to any style object. The style provided for +the *selected* modifier is applied on top of the style object it corresponds to. If you would like to make sure message that are flagged as read in the msglist appear in yellow foreground and black background. You can specify that with this: - msglist_default.selected.fg=yellow + *msglist_default*.*selected*.*fg* = _yellow_ - msglist_default.selected.bg=black + *msglist_default*.*selected*.*bg* = _black_ If we specify the global style selected modifier using fnmatch as below: - \*.selected.reverse=toggle + *\**.*selected*.*reverse* = _toggle_ This toggles the reverse switch for selected version of all the style objects. ## LAYERED STYLES -Some styles, (currently the `msglist\*` and `dirlist\*` ones) are applied in layers. If -a style differs from the base (in this case `\{msglist|dirlist\}_default`) then that style -applies, unless overridden by a higher layer. The order that `msglist` styles -are applied in is, from first to last: +Some styles, (currently the *msglist_\** and *dirlist_\** ones) are applied in +layers. If a style differs from the base (in this case *\*list_default*) then +that style applies, unless overridden by a higher layer. + +The order that *msglist_\** styles are applied in is, from first to last: + +1. *msglist_default* +2. *msglist_unread* +3. *msglist_read* +4. *msglist_flagged* +5. *msglist_deleted* +6. *msglist_marked* -``` -msglist_default -msglist_unread -msglist_read -msglist_flagged -msglist_deleted -msglist_marked -``` +So, the marked style will override all other msglist styles. -So, the marked style will override all other msglist styles. The order for `dirlist` styles is: +The order for *dirlist_\** styles is: -``` -dirlist_default -dirlist_unread -dirlist_recent -``` +1. *dirlist_default* +2. *dirlist_unread* +3. *dirlist_recent* ## COLORS The color values are set using the values accepted by the tcell library. The values can be one of the following. - *default* - The color is set as per the system or terminal default. +_default_ + The color is set as per the system or terminal default. - *<Color name>* - Any w3c approved color name is used to set colors for the style. +_<Color name>_ + Any w3c approved color name is used to set colors for the style. - *<Hex code>* - Hexcode for a color can be used. The format must be "\#XXXXXX" +_<Hex code>_ + Hexcode for a color can be used. The format must be _#XXXXXX_. - *<Dec number>* - Color based on the palette index. Valid numbers are between 0 - and 255. +_<Dec number>_ + Color based on the terminal palette index. Valid numbers are + between _0_ and _255_. # SEE ALSO diff --git a/doc/aerc-templates.7.scd b/doc/aerc-templates.7.scd index 62d5b488..6c9e3190 100644 --- a/doc/aerc-templates.7.scd +++ b/doc/aerc-templates.7.scd @@ -6,7 +6,7 @@ aerc-templates - template file specification for *aerc*(1) # SYNOPSIS -aerc uses the go "text/template" package for the template parsing. +aerc uses the go text/template package for the template parsing. Refer to the go text/template documentation for the general syntax. Template files are composed of headers, followed by a newline, followed by the @@ -39,11 +39,11 @@ available always. An array of mail.Address. That can be used to add sender or recipient names to the template. - - From: List of senders. - - To: List of To recipients. Not always Available. - - Cc: List of Cc recipients. Not always Available. - - Bcc: List of Cc recipients. Not always Available. - - OriginalFrom: List of senders of the original message. + - _From_: List of senders. + - _To_: List of To recipients. Not always Available. + - _Cc_: List of Cc recipients. Not always Available. + - _Bcc_: List of Cc recipients. Not always Available. + - _OriginalFrom_: List of senders of the original message. Available for quoted reply and forward. Example: @@ -62,12 +62,12 @@ available always. The date and time information is always available and can be easily formatted. - - Date: Date and time information when the compose window is opened. - - OriginalDate: Date and time when the original message of received. + - _Date_: Date and time information when the compose window is opened. + - _OriginalDate_: Date and time when the original message of received. Available for quoted reply and forward. To format the date fields, _dateFormat_ and _toLocal_ are provided. - Refer to the _TEMPLATE FUNCTIONS_ section for details. + Refer to the *TEMPLATE FUNCTIONS* section for details. *Subject* The subject of the email is available for quoted reply and forward. @@ -77,12 +77,12 @@ available always. *MIME Type* MIME Type is available for quoted reply and forward. - - OriginalMIMEType: MIME type info of quoted mail part. Usually - "text/plain" or "text/html". + - _OriginalMIMEType_: MIME type info of quoted mail part. Usually + _text/plain_ or _text/html_. *Original Message* When using quoted reply or forward, the original message is available in a - field called ".OriginalText". + field called _OriginalText_. ``` {{.OriginalText}} @@ -101,7 +101,7 @@ aerc provides the following additional functions: ``` *quote* - Prepends each line with "> ". + Prepends each line with _"> "_. ``` {{quote .OriginalText}} diff --git a/doc/aerc-tutorial.7.scd b/doc/aerc-tutorial.7.scd index c71dde61..af49c8a1 100644 --- a/doc/aerc-tutorial.7.scd +++ b/doc/aerc-tutorial.7.scd @@ -11,7 +11,7 @@ the client. This tutorial is a man page - you can read it again later with *:help tutorial* from aerc, or *man aerc-tutorial* from your terminal. First, let's introduce some basic keybindings. For convention, we'll use *<C-p>* -to represent Ctrl+p, which matches the convention used for writing keybindings +to represent _Ctrl+p_, which matches the convention used for writing keybindings for aerc. *<C-p>*, *<C-n>* @@ -35,8 +35,8 @@ your message list, we use vim-style keys to get around. *<Enter>* Opens the selected message -You can also search the selected folder with */*, or filter with *\\*. When -searching you can use n and p to jump to the next and previous result. +You can also search the selected folder with */*, or filter with *\\ *. When +searching you can use *n* and *p* to jump to the next and previous result. Filtering hides any non-matching message. # THE MESSAGE VIEWER @@ -54,9 +54,9 @@ alternative formats) show a part selector on the bottom of the message viewer. *q* Close the message viewer -To show HTML messages, uncomment the *text/html* filter in your aerc.conf -file (which is probably in ~/.config/aerc/) and install its dependencies: w3m -and dante-utils. +To show HTML messages, uncomment the _text/html_ filter in your _aerc.conf_ +file (which is probably in _~/.config/aerc/_) and install its dependencies: +*w3m* and *dante-utils*. You can also do many tasks you could do in the message list from here, like replying to emails, deleting the email, or view the next and previous message @@ -99,7 +99,7 @@ The message review screen is shown next. You have a chance now to revise the email before it's sent. Press *y* to send the email if it looks good. *Note*: when using the terminal in the message view, you can summon aerc's ex -command line by using *<C-x>*. ':' is sent to the editor. +command line by using *<C-x>*. *:* is sent to the editor. # USING THE TERMINAL @@ -119,7 +119,7 @@ following keybindings to open a terminal: Prompts for a command to run, then pipes the selected email into that command and displays the result on a new terminal tab -Try pressing *$* and entering "top". You can also use the *:cd* command to +Try pressing *$* and entering _top_. You can also use the *:cd* command to change aerc's working directory, and the directory in which new terminals run. Use *:pwd* to see it again if you're not sure where you are. @@ -128,13 +128,13 @@ Use *:pwd* to see it again if you're not sure where you are. ## COMMANDS Every keybinding is ultimately bound to an aerc command. You can also summon the -command line by pressing ':', then entering one of these commands. See *aerc*(1) +command line by pressing *:*, then entering one of these commands. See *aerc*(1) or *:help* for a full list of commands. ## MESSAGE FILTERS When displaying messages in the message viewer, aerc will pipe them through a -_message filter_ first. This allows you to decode messages in non-plaintext +message filter first. This allows you to decode messages in non-plaintext formats, add syntax highlighting, etc. aerc ships with a few default filters: - _text/plain_ parts are piped through the _colorized_ built-in filter which diff --git a/doc/aerc.1.scd b/doc/aerc.1.scd index 2830a8ae..afc8d90a 100644 --- a/doc/aerc.1.scd +++ b/doc/aerc.1.scd @@ -6,7 +6,7 @@ aerc - a pretty good email client. # SYNOPSIS -_aerc_ [-v] [-a <account-name[,account-name]>] [mailto:...] +*aerc* [*-v*] [*-a* _<account>_[,_<account>_]] [*mailto:*_..._] For a guided tutorial, use *:help tutorial* from aerc, or *man aerc-tutorial* from your terminal. @@ -16,40 +16,40 @@ from your terminal. *-v* Prints the installed version of aerc and exits. -*-a <account-name[,account-name]>* +*-a* _<account>_[,_<account>_] Load only the named accounts, as opposed to all configured accounts. List must be comma separated, with no spaces. The account order will be preserved. -*mailto:address[,address][?query[&query]]* - Opens the composer with the address(es) in the "to" field. These +*mailto:*_address[,address][?query[&query]]_ + Opens the composer with the address(es) in the To field. These addresses must not be percent encoded. - If _aerc_ is already running, the composer is started in this instance, - otherwise _aerc_ will be started. + If aerc is already running, the composer is started in this instance, + otherwise aerc will be started. The following (optional) query parameters are supported: [[ *Query* :[ *Description* -| subject=<text> -: Subject line will be completed with the text -| body=<text> -: Message body will be completed with the text -| cc=<address[,address]> -: CC header will be completed with the list of addresses -| bcc=<address[,address]> -: BCC header will be completed with the list of addresses -| in-reply-to=<\<message-id\>> +| _subject=<text>_ +: Subject line will be completed with the _<text>_ +| _body=<text>_ +: Message body will be completed with the _<text>_ +| _cc=<address>[,<address>]_ +: Cc header will be completed with the list of addresses +| _bcc=<address>[,<address>]_ +: Bcc header will be completed with the list of addresses +| _in-reply-to=<message-id>_ : In-reply-to header will be set to the message id -| account=<accountname> -: Specify the account (must be in accounts.conf; default is the selected account) +| _account=<accountname>_ +: Specify the account (must be in _accounts.conf_; default is the selected account) Note that reserved characters in the queries must be percent encoded. # RUNTIME COMMANDS -To execute a command, press ':' to bring up the command interface. Commands may +To execute a command, press *:* to bring up the command interface. Commands may also be bound to keys, see *aerc-config*(5) for details. In some contexts, such -as the terminal emulator, '<c-x>' is used to bring up the command interface. +as the terminal emulator, *<c-x>* is used to bring up the command interface. Different commands work in different contexts, depending on the kind of tab you have selected. @@ -62,113 +62,114 @@ forwards. These commands work in any context. -*cd* <directory> +*:cd* _<directory>_ Changes aerc's current working directory. -*z* <directory or zoxide query> +*:z* _<directory or zoxide query>_ Changes aerc's current working directory using zoxide. If zoxide is not on *$PATH*., the command will not be registered. -*change-tab* [+|-]<tab name or index> -*ct* [+|-]<tab name or index> +*:change-tab* [*+*|*-*]_<tab name or index>_++ +*:ct* [*+*|*-*]_<tab name or index>_ Changes the focus to the tab with the given name. If a number is given, - it's treated as an index. If + or - is specified, the number is interpreted + it's treated as an index. If *+* or *-* is specified, the number is interpreted as a delta from the selected tab. -*exec* <command...> +*:exec* _<command>_ Executes an arbitrary command in the background. Aerc will set the environment variables *$account* and *$folder* when the command is executed from an Account tab or an opened message. - *Note*: commands executed in this way are not executed with the shell. + Note: commands executed in this way are not executed with the shell. -*eml* [<path>] -*preview* +*:eml* [_<path>_]++ +*:preview* Opens an eml file and displays the message in the message viewer. Can also be used in the message viewer to open an rfc822 attachment or in the composer to preview the message. -*pwd* +*:pwd* Displays aerc's current working directory in the status bar. -*term* [command...] -*terminal* +*:term* [_<command>..._]++ +*:terminal* Opens a new terminal tab with a shell running in the current working directory, or the specified command. -*move-tab* [+|-]<index> - Moves the selected tab to the given index. If + or - is specified, the +*:move-tab* [_+_|_-_]_<index>_ + Moves the selected tab to the given index. If _+_ or _-_ is specified, the number is interpreted as a delta from the selected tab. -*prev-tab* [n], *next-tab* [n] - Cycles to the previous or next tab in the list, repeating n times - (default: 1). +*:prev-tab* [_<n>_]++ +*:next-tab* [_<n>_] + Cycles to the previous or next tab in the list, repeating _<n>_ times + (default: _1_). -*pin-tab* +*:pin-tab* Moves the current tab to the left of all non-pinned tabs and displays - the *pinned-tab-marker* (default: `) to the left of the tab title. + the *pinned-tab-marker* (default: _`_) to the left of the tab title. -*unpin-tab* +*:unpin-tab* Removes the *pinned-tab-marker* from the current tab and returns the tab to its previous location. -*prompt* <prompt> <command...> +*:prompt* _<prompt>_ _<command>..._ Displays the prompt on the status bar, waits for user input, then appends that input as the last argument to the command and executes it. The input is passed as one argument to the command, unless it is empty, in which case no extra argument is added. -*choose* -o <key> <text> <command> [-o <key> <text> <command>]... +*:choose* *-o* _<key>_ _<text>_ _<command>_ [*-o* _<key>_ _<text>_ _<command>_]... Prompts the user to choose from various options. -*quit* [-f] -*exit* [-f] +*:quit* [*-f*]++ +*:exit* [*-f*] Exits aerc. If a task is being performed that should not be interrupted (like sending a message), a normal quit call might fail. In this case, - closing aerc can be forced with the -f option. + closing aerc can be forced with the *-f* option. ## MESSAGE COMMANDS These commands are valid in any context that has a selected message (e.g. the message list, the message in the message viewer, etc). -*archive* <scheme> +*:archive* _<scheme>_ Moves the selected message to the archive. The available schemes are: - *flat*: No special structure, all messages in the archive directory + _flat_: No special structure, all messages in the archive directory - *year*: Messages are stored in folders per year + _year_: Messages are stored in folders per year - *month*: Messages are stored in folders per year and subfolders per month + _month_: Messages are stored in folders per year and subfolders per month -*accept* +*:accept* Accepts an iCalendar meeting invitation. -*accept-tentative* +*:accept-tentative* Accepts an iCalendar meeting invitation tentatively. -*copy* <target> -*cp* <target> +*:copy* _<target>_++ +*:cp* _<target>_ Copies the selected message to the target folder. -*decline* +*:decline* Declines an iCalendar meeting invitation. -*delete* -*delete-message* +*:delete*++ +*:delete-message* Deletes the selected message. -*envelope [-h] [-s <format-specifier>]* +*:envelope* [*-h*] [*-s* _<format-specifier>_] Opens the message envelope in a dialog popup. *-h*: Show all header fields - *-s* <format-specifier> - User-defined format specifier requiring two %s for the key and - value strings. Default format: '%-20.20s: %s' + *-s* _<format-specifier>_ + User-defined format specifier requiring two _%s_ for the key and + value strings. Default format: _%-20.20s: %s_ -*recall* [-f] +*:recall* [*-f*] Opens the selected message for re-editing. Messages can only be recalled from the postpone directory. The original message is deleted. @@ -176,24 +177,24 @@ message list, the message in the message viewer, etc). directory. The original message will be deleted only if it is in the postpone directory. -*forward* [-A | -F] [-T <template-file>] [address...] +*:forward* [*-A*|*-F*] [*-T* _<template-file>_] [_<address>_...] Opens the composer to forward the selected message to another recipient. *-A*: Forward the message and all attachments. *-F*: Forward the full message as an RFC 2822 attachment. - *-T* <template-file> + *-T* _<template-file>_ Use the specified template file for creating the initial message body. Unless *-F* is specified, this defaults to what - is set as _forwards_ in the _[templates]_ section of + is set as *forwards* in the *[templates]* section of _aerc.conf_. -*move* <target> -*mv* <target> +*:move* _<target>_++ +*:mv* _<target>_ Moves the selected message to the target folder. -*pipe* [-bmp] <cmd> +*:pipe* [*-bmp*] _<cmd>_ Downloads and pipes the selected message into the given shell command, and opens a new terminal tab to show the result. By default, the selected message part is used in the message viewer and the full message is used in @@ -208,59 +209,59 @@ message list, the message in the message viewer, etc). *-p*: Pipe just the selected message part, if applicable -*reply* [-aq] [-T <template-file>] +*:reply* [*-aq*] [*-T* _<template-file>_] 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 - *-T* <template-file> + *-T* _<template-file>_ Use the specified template file for creating the initial message body. If *-q* is specified, defaults to what is set as - _quoted-reply_ in the _[templates]_ section of _aerc.conf_. + *quoted-reply* in the *[templates]* section of _aerc.conf_. -*read* [-t] +*:read* [*-t*] Marks the marked or selected messages as read. *-t*: Toggle the messages between read and unread. -*unread* [-t] +*:unread* [*-t*] Marks the marked or selected messages as unread. *-t*: Toggle the messages between read and unread. -*flag* [-t] [-a | -x <flag>] +*:flag* [*-t*] [*-a* | *-x* _<flag>_] Sets (enables) a certain flag on the marked or selected messages. *-t*: Toggle the flag instead of setting (enabling) it. *-a*: Mark message as answered/unanswered. - *-x <flag>*: Mark message with specific flag. + *-x* _<flag>_: Mark message with specific flag. + The available flags are (adapted from RFC 3501, section 2.3.2): - The available flags are (adapted from RFC 3501, section 2.3.2): + _Seen_ + Message has been read + _Answered_ + Message has been answered + _Flagged_ + Message is flagged for urgent/special attention - Seen - Message has been read - Answered - Message has been answered - Flagged - Message is flagged for urgent/special attention +*:unflag* [*-t*] _<flag>_ + Operates exactly like *:flag*, defaulting to unsetting (disabling) flags. -*unflag* [-t] <flag> - Operates exactly like *flag*, defaulting to unsetting (disabling) flags. - -*modify-labels* <[+-]label>... -*tag* <[+-]label>... - Modify message labels (e.g. notmuch tags). Labels prefixed with a '+' are - added, those prefixed with a '-' removed. As a convenience, labels without +*:modify-labels* [_+_|_-_]_<label>_...++ +*:tag* [_+_|_-_]_<label>_... + Modify message labels (e.g. notmuch tags). Labels prefixed with a *+* are + added, those prefixed with a *-* removed. As a convenience, labels without either operand add the specified label. - Example: `modify-labels +inbox -spam unread` adds the labels inbox and unread - and removes spam + Example: add _inbox_ and _unread_ labels, remove _spam_ label. + + *:modify-labels* _+inbox_ _-spam_ _unread_ -*unsubscribe* +*:unsubscribe* Attempt to automatically unsubscribe the user from the mailing list through use of the List-Unsubscribe header. If supported, aerc may open a compose window pre-filled with the unsubscribe information or open the unsubscribe @@ -268,43 +269,46 @@ message list, the message in the message viewer, etc). ## MESSAGE LIST COMMANDS -*clear* [-s] +*:clear* [*-s*] Clears the current search or filter criteria. By default, the selected message will be kept. To clear the selected - message and move cursor to the top of the message list, use the -s flag. + message and move cursor to the top of the message list, use the *-s* flag. - *-s* - Selects the message at the top of the message list after clearing. + *-s*: Selects the message at the top of the message list after clearing. -*cf* <folder> +*:cf* _<folder>_ Change the folder shown in the message list. -*check-mail* +*:check-mail* Check for new mail on the selected account. Non-imap backends require check-mail-cmd to be set in order for aerc to initiate a check for new mail. - Issuing a manual :check-mail command will reset the timer for automatic checking. + Issuing a manual *:check-mail* command will reset the timer for automatic checking. -*compose* [-H] [<body>] [-T <template-file>] +*:compose* [*-H* _"<header>: <value>"_] [*-T* _<template-file>_] [_<body>_] Open the compose window to send a new email. The new email will be sent with the current account's outgoing transport configuration. For details on configuring outgoing mail delivery consult *aerc-config*(5). - *-H* <header> - Add the specified header to the message, e.g. 'compose -H "X-Custom: custom - value"' - *-T* <template-file> + *-H* _"<header>: <value>"_ + Add the specified header to the message, e.g: + + *:compose -H* _"X-Custom: custom value"_ + + *-T* _<template-file>_ Use the specified template file for creating the initial message body. -*filter* [options] <terms...> - Similar to *search*, but filters the displayed messages to only the search - results. See the documentation for *search* for more details. + _<body>_: The initial message body. + +*:filter* [_<options>_] _<terms>_... + Similar to *:search*, but filters the displayed messages to only the search + results. See the documentation for *:search* for more details. -*mkdir* <name> +*:mkdir* _<name>_ Creates a new folder for this account and changes to that folder. -*rmdir* [-f] +*:rmdir* [*-f*] Removes the current folder. By default, it will fail if the directory is non-empty (see *-f*). @@ -313,58 +317,63 @@ message list, the message in the message viewer, etc). Remove the directory even if it contains messages. Some programs that sync maildirs may recover deleted directories (e.g. - offlineimap). These can either be specially configured to properly + *offlineimap*). These can either be specially configured to properly handle directory deletion, or special commands need to be run to delete - directories (e.g. 'offlineimap --delete-folder'). + directories (e.g. _offlineimap --delete-folder_). - It is possible, with a slow connection and the 'imap' backend, that new - messages arrive in the directory before they show up - using 'rmdir' at + It is possible, with a slow connection and the imap backend, that new + messages arrive in the directory before they show up - using *:rmdir* at this moment would delete the directory and such new messages before the user sees them. -*next* <n>[%], *prev* <n>[%] -*next-message* <n>[%], *prev-message* <n>[%] +*:next* _<n>_[_%_]++ +*:next-message* _<n>_[_%_]++ +*:prev* _<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. -*next-folder* <n>, *prev-folder* <n> - Cycles to the next (or previous) folder shown in the sidebar, repeated n - times (default: 1). +*:next-folder* _<n>_++ +*:prev-folder* _<n>_ + Cycles to the next (or previous) folder shown in the sidebar, repeated + _<n>_ times (default: _1_). -*expand-folder*, *collapse-folder* +*:expand-folder*++ +*:collapse-folder* Expands or collapses the current folder when the directory tree is enabled. -*export-mbox* <file> +*:export-mbox* _<file>_ Exports all messages in the current folder to an mbox file. -*import-mbox* <file> +*:import-mbox* _<file>_ Imports all messages from an mbox file to the current folder. -*next-result*, *prev-result* +*:next-result*++ +*:prev-result* Selects the next or previous search result. -*search* +*:filter* [_<options>_] _<terms>_... Searches the current folder. The search syntax is dependent on the underlying backend. Refer to *aerc-search*(1) for details -*select* <n> -*select-message* <n> - Selects the nth message in the message list (and scrolls it into view if - necessary). - -*split* [+|-] [<n>] - Creates a horizontal split, showing a <n> messages and a message view - below the message list. If a + or - is prepended, the message list size - will grow or shrink accordingly. The split can be cleared by calling - :split 0, or just :split. The split can be toggled by calling split with - the same (absolute) size repeatedly. For example, :split 10 will create - a split. Calling :split 10 again will remove the split. Also see - *vsplit*. - -*sort* [[-r] <criterion>]... +*:select* _<n>_++ +*:select-message* _<n>_ + Selects the _<n>_\th message in the message list (and scrolls it into + view if necessary). + +*:split* [[_+_|_-_]_<n>_] + Creates a horizontal split, showing _<n>_ messages and a message view + below the message list. If a _+_ or _-_ is prepended, the message list + size will grow or shrink accordingly. The split can be cleared by + calling *:split* _0_, or just *:split*. The split can be toggled by + calling split with the same (absolute) size repeatedly. For example, + *:split* _10_ will create a split. Calling *:split* _10_ again will + remove the split. Also see *:vsplit*. + +*:sort* [[*-r*] _<criterion>_]... Sorts the message list by the given criteria. *-r* sorts the immediately following criterion in reverse order. @@ -372,57 +381,59 @@ message list, the message in the message viewer, etc). [[ *Criterion* :- *Description* -| arrival +| _arrival_ :- Date and time of the messages arrival -| cc -:- Addresses in the "cc" field -| date +| _cc_ +:- Addresses in the Cc field +| _date_ :- Date and time of the message -| from -:- Addresses in the "from" field -| read +| _from_ +:- Addresses in the From field +| _read_ :- Presence of the read flag -| size +| _size_ :- Size of the message -| subject +| _subject_ :- Subject of the message -| to -:- Addresses in the "to" field +| _to_ +:- Addresses in the To field -*toggle-threads* +*:toggle-threads* Toggles between message threading and the normal message list. -*view* [-p] -*view-message* [-p] +*:view* [*-p*]++ +*:view-message* [*-p*] Opens the message viewer to display the selected message. If the peek - flag -p is set, the message will not be marked as "seen" and ignores the - "auto-mark-read" config. + flag *-p* is set, the message will not be marked as seen and ignores the + *auto-mark-read* config. -*vsplit* [+|-] [<n>] +*:vsplit* [[_+_|_-_]_<n>_] Creates a vertical split of the message list. The message list will be - <n> columns wide, and a vertical message view will be shown to the right - of the message list. If a + or - is prepended, the message list size - will grow or shrink accordingly. The split can be cleared by calling - :vsplit 0, or just :vsplit. The split can be toggled by calling split - with the same (absolute) size repeatedly. For example, :vsplit 10 will - create a split. Calling :vsplit 10 again will remove the split. Also see - *split*. + _<n>_ columns wide, and a vertical message view will be shown to the + right of the message list. If a _+_ or _-_ is prepended, the message + list size will grow or shrink accordingly. The split can be cleared by + calling *:vsplit* _0_, or just *:vsplit*. The split can be toggled by + calling split with the same (absolute) size repeatedly. For example, + *:vsplit* _10_ will create a split. Calling *:vsplit* _10_ again will + remove the split. Also see *:split*. ## MESSAGE VIEW COMMANDS -*close* +*:close* Closes the message viewer. -*next* <n>[%], *prev* <n>[%] +*:next* _<n>_[_%_]++ +*:prev* _<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. -*next-part*, *prev-part* +*:next-part*++ +*:prev-part* Cycles between message parts being shown. The list of message parts is shown at the bottom of the message viewer. -*open* [args...] +*:open* [_<args...>_] Saves the current message part to a temporary file, then opens it. If no arguments are provided, it will open the current MIME part with the matching command in the *[openers]* section of _aerc.conf_. When no match @@ -432,18 +443,18 @@ message list, the message in the message viewer, etc). - The first argument must be the program to open the message part with. Subsequent args are passed to that program. - - *{}* will be expanded as the temporary filename to be opened. If it is + - _{}_ will be expanded as the temporary filename to be opened. If it is not encountered in the arguments, the temporary filename will be appened to the end of the command. -*save* [-fpa] <path> +*:save* [*-fpa*] _<path>_ Saves the current message part to the given path. - If the path is not an absolute path, general.default-save-path will be - prepended to the path given. - If path ends in a trailing slash or if a folder exists on disc or if -a + If the path is not an absolute path, *[general].default-save-path* from + _aerc.conf_ will be prepended to the path given. + If path ends in a trailing slash or if a folder exists on disc or if *-a* is specified, aerc assumes it to be a directory. - When passed a directory :save infers the filename from the mail part if - possible, or if that fails, uses "aerc_$DATE". + When passed a directory *:save* infers the filename from the mail part if + possible, or if that fails, uses _aerc\_$DATE_. *-f*: Overwrite the destination whether or not it exists @@ -451,7 +462,7 @@ message list, the message in the message viewer, etc). *-a*: Save all attachments. Individual filenames cannot be specified. -*mark* [-atvT] +*:mark* [*-atvT*] Marks messages. Commands will execute on all marked messages instead of the highlighted one if applicable. The flags below can be combined as needed. @@ -461,83 +472,89 @@ message list, the message in the message viewer, etc). *-v*: Enter / leave visual mark mode - *-V*: Same as -v but does not clear existing selection + *-V*: Same as *-v* but does not clear existing selection *-T*: Marks the displayed message thread of the selected message. -*unmark* [-at] +*:unmark* [*-at*] Unmarks messages. The flags below can be combined as needed. *-a*: Apply to all messages in the current folder *-t*: toggle the mark state instead of unmarking a message -*remark* +*:remark* Re-select the last set of marked messages. Can be used to chain commands after a selection has been acted upon ## MESSAGE COMPOSE COMMANDS -*abort* +*:abort* Close the composer without sending, discarding the message in progress. -*attach* [-m [<arg>] | <path>] +*:attach* _<path>_++ +*:attach* *-m* [_<arg>_] Attaches the file at the given path to the email. The path can contain globbing syntax described at https://godocs.io/path/filepath#Match. - *-m* [<arg>] - Runs the 'file-picker-cmd' to select files to be attached. - Requires an argument when 'file-picker-cmd' contains the '%s' verb. + *-m* [_<arg>_] + Runs the *file-picker-cmd* to select files to be attached. + Requires an argument when *file-picker-cmd* contains the _%s_ verb. -*attach-key* +*:attach-key* Attaches the public key for the configured account to the email. -*detach* [path] +*:detach* [_<path>_] Detaches the file with the given path from the composed email. If no path is specified, detaches the first attachment instead. -*cc* [addresses], *bcc* [addresses] +*:cc* _<addresses>_++ +*:bcc* _<addresses>_ Sets the Cc or Bcc header to the given addresses. If an editor for the header is not currently visible in the compose window, a new one will be added. -*edit* +*:edit* (Re-)opens your text editor to edit the message in progress. -*next-field*, *prev-field* +*:next-field*++ +*:prev-field* Cycles between input fields in the compose window. -*postpone* - Saves the current state of the message to the *postpone* folder for the - current account. +*:postpone* + Saves the current state of the message to the *postpone* folder (from + _accounts.conf_) for the current account. -*save* [-p] <path> - Saves the selected message part to the specified path. If -p is selected, +*:save* [*-p*] _<path>_ + Saves the selected message part to the specified path. If *-p* is selected, aerc will create any missing directories in the specified path. If the path - specified is a directory or ends in /, aerc will use the attachment filename + specified is a directory or ends in _/_, aerc will use the attachment filename if available or a generated name if not. -*send* +*:send* Sends the message using this accounts default outgoing transport configuration. For details on configuring outgoing mail delivery consult *aerc-config*(5). -*switch-account* <-n|-p|account-name> +*:switch-account* _<account-name>_++ +*:switch-account* *-n*++ +*:switch-account* *-p* Switches the account. Can be used to switch to a specific account from - its name or to cycle through accounts using the -p and -n flags. + its name or to cycle through accounts using the *-p* and *-n* flags. *-p*: switch to previous account + *-n*: switch to next account -*header* [-f] <field> [value] - Add a new email header. If the header already exists, -f must be +*:header* [*-f*] _<name>_ [_<value>_] + Add a new email header. If the header already exists, *-f* must be specified to replace the given value. -*toggle-headers* +*:toggle-headers* Toggles the visibility of the message headers. ## TERMINAL COMMANDS -*close* +*:close* Closes the terminal. # LOGGING |