diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/aerc-config.5.scd | 7 | ||||
| -rw-r--r-- | doc/aerc-templates.7.scd | 149 |
2 files changed, 141 insertions, 15 deletions
diff --git a/doc/aerc-config.5.scd b/doc/aerc-config.5.scd index d48e38ad..dcaa3dd4 100644 --- a/doc/aerc-config.5.scd +++ b/doc/aerc-config.5.scd @@ -805,9 +805,10 @@ 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 -template name. +Template files 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. The available symbols and functions are described in +*aerc-templates*(7). aerc ships with some default templates installed in the share directory (usually _/usr/share/aerc/templates_). diff --git a/doc/aerc-templates.7.scd b/doc/aerc-templates.7.scd index 6c9e3190..67d5c112 100644 --- a/doc/aerc-templates.7.scd +++ b/doc/aerc-templates.7.scd @@ -8,6 +8,8 @@ aerc-templates - template file specification for *aerc*(1) aerc uses the go text/template package for the template parsing. Refer to the go text/template documentation for the general syntax. +The template syntax described below can be used for message template files and +for dynamic formatting of some UI widgets. Template files are composed of headers, followed by a newline, followed by the body text. @@ -39,11 +41,14 @@ 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. + - _{{.Peer}}_: List of senders or To recipients if the message is from + you. + - _{{.To}}_: List of To recipients. Not always Available. + - _{{.ReplyTo}}_: List of ReplyTo 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: @@ -51,6 +56,7 @@ available always. Get the name of the first sender. ``` {{(index .From 0).Name}} + {{index (.From | names) 0}} ``` Get the email address of the first sender. @@ -62,22 +68,63 @@ 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. + To format the date fields, _dateFormat_ and _.Local_ are provided. Refer to the *TEMPLATE FUNCTIONS* section for details. *Subject* - The subject of the email is available for quoted reply and forward. + The subject of the email. + ``` {{.Subject}} + ``` + +*Flags* + List of message flags, not available when composing, replying nor + forwarding. This is a list of strings that may be converted to a single + string with *join*. + + ``` + {{.Flags | join ""}} + ``` + +*Labels* + Message labels (for example notmuch tags). Not available when composing, + replying nor forwarding. This is a list of strings that may be converted + to a single string with *join*. + + ``` + {{.Labels | join " "}} + ``` + +*Size* + The size of the message in bytes. Not available when composing, replying + nor forwarding. It can be formatted with *humanReadable*. + + ``` + {{.Size | humanReadable}} + ``` + +*Any header value* + Any header value of the email. + + ``` + {{.Header "x-foo-bar"}} + ``` + + Any header values of the original forwared or replied message: + + ``` + {{.OriginalHeader "x-foo-bar"}} + ``` *MIME Type* MIME Type is available for quoted reply and forward. - - _OriginalMIMEType_: MIME type info of quoted mail part. Usually + - _{{.OriginalMIMEType}}_: MIME type info of quoted mail part. Usually _text/plain_ or _text/html_. *Original Message* @@ -88,6 +135,19 @@ available always. {{.OriginalText}} ``` +*Account info* + The current account name: + + ``` + {{.Account}} + ``` + + Currently selected mailbox folder: + + ``` + {{.Folder}} + ``` + # TEMPLATE FUNCTIONS Besides the standard functions described in go's text/template documentation, @@ -107,6 +167,49 @@ aerc provides the following additional functions: {{quote .OriginalText}} ``` +*join* + Join the provided list of strings with a separator: + + ``` + {{.To | names | join ", "}} + ``` + +*names* + Extracts the names part from a mail.Address list. If there is no name + available, the email address is returned instead. + + ``` + {{.To | names | join ", "}} + {{index (.To | names) 0}} + ``` + +*emails* + Extracts the addresses part from a mail.Address list. + + ``` + {{.To | emails | join ", "}} + {{index (.To | emails) 0}} + ``` + +*mboxes* + Extracts the mbox part from a mail.Address list (i.e. _smith_ from + _smith@example.com_). + + ``` + {{.To | mboxes | join ", "}} + {{index (.To | mboxes) 0}} + ``` + +*persons* + Formats a list of mail.Address into a list of strings containing the + human readable form of RFC5322 (e.g. _Firstname Lastname + <email@address.tld>_). + + ``` + {{.To | persons | join ", "}} + {{index (.To | persons) 0}} + ``` + *exec* Execute external command, provide the second argument to its stdin. @@ -114,11 +217,11 @@ aerc provides the following additional functions: {{exec `/usr/local/share/aerc/filters/html` .OriginalText}} ``` -*toLocal* +*.Local* Convert the date to the local timezone as specified by the locale. ``` - {{toLocal .Date}} + {{.Date.Local}} ``` *dateFormat* @@ -129,6 +232,28 @@ aerc provides the following additional functions: {{dateFormat .Date "Mon Jan 2 15:04:05 -0700 MST 2006"}} ``` + You can also use the _.DateAutoFormat_ method to format the date + according to *\*-time\*format* settings: + + ``` + {{.DateAutoFormat .OriginalDate.Local}} + ``` + +*humanReadable* + Return the human readable form of an integer value. + + ``` + {{humanReadable 3217653721}} + ``` + +*cwd* + Return the current working directory with the user home dir replaced by + _~_. + + ``` + {{cwd}} + ``` + *version* Returns the version of aerc, which can be useful for things like X-Mailer. |