🐝 I really like where this mua is(was?) headed, but it seems as though there has not been much activity recently.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

699 lines
16 KiB

3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
  1. .\" meli - meli.conf.5
  2. .\"
  3. .\" Copyright 2017-2019 Manos Pitsidianakis
  4. .\"
  5. .\" This file is part of meli.
  6. .\"
  7. .\" meli is free software: you can redistribute it and/or modify
  8. .\" it under the terms of the GNU General Public License as published by
  9. .\" the Free Software Foundation, either version 3 of the License, or
  10. .\" (at your option) any later version.
  11. .\"
  12. .\" meli is distributed in the hope that it will be useful,
  13. .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  14. .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  15. .\" GNU General Public License for more details.
  16. .\"
  17. .\" You should have received a copy of the GNU General Public License
  18. .\" along with meli. If not, see <http://www.gnu.org/licenses/>.
  19. .\"
  20. .Dd September 16, 2019
  21. .Dt MELI.CONF 5
  22. .Os
  23. .Sh NAME
  24. .Nm meli.conf
  25. .Nd configuration file for the Meli Mail User Agent
  26. .Sh SYNOPSIS
  27. .Pa $XDG_CONFIG_HOME/meli/config.toml
  28. .Sh DESCRIPTION
  29. Configuration for meli is written in TOML.
  30. Few things to consider before writing TOML (quoting the spec):
  31. .Pp
  32. .Bl -bullet -compact
  33. .It
  34. TOML is case sensitive.
  35. .It
  36. A TOML file must be a valid UTF-8 encoded Unicode document.
  37. .It
  38. Whitespace means tab (0x09) or space (0x20).
  39. .It
  40. Newline means LF (0x0A) or CRLF (0x0D 0x0A).
  41. .El
  42. .Pp
  43. Refer to TOML documentation for valid TOML syntax.
  44. .sp
  45. Though not part of TOML syntax,
  46. .Nm
  47. can have nested configuration files by using the following
  48. .Xr m4 1
  49. include macro:
  50. .Dl include(\&"/path/to/file\&")
  51. .Sh SECTIONS
  52. The top level sections of the config are accounts, shortcuts, notifications, pager, listing, composing, pgp, terminal.
  53. .Sh EXAMPLES
  54. example configuration
  55. .sp
  56. .Bd -literal
  57. # Setting up a Maildir account
  58. [accounts.account-name]
  59. root_mailbox = "/path/to/root/folder"
  60. format = "Maildir"
  61. index_style = "Compact"
  62. identity="email@address.tld"
  63. subscribed_mailboxes = ["folder", "folder/Sent"] # or [ "*", ] for all mailboxes
  64. display_name = "Name"
  65. # Set mailbox-specific settings
  66. [accounts.account-name.mailboxes]
  67. "INBOX" = { alias="Inbox" } #inline table
  68. "drafts" = { alias="Drafts" } #inline table
  69. [accounts.account-name.mailboxes."foobar-devel"] # or a regular table
  70. ignore = true # don't show notifications for this mailbox
  71. # Setting up an mbox account
  72. [accounts.mbox]
  73. root_mailbox = "/var/mail/username"
  74. format = "mbox"
  75. index_style = "Compact"
  76. identity="username@hostname.local"
  77. [pager]
  78. filter = "/usr/bin/pygmentize"
  79. html_filter = "w3m -I utf-8 -T text/html"
  80. [notifications]
  81. script = "notify-send"
  82. [composing]
  83. # required for sending e-mail
  84. mailer_cmd = 'msmtp --read-recipients --read-envelope-from'
  85. editor_cmd = 'vim +/^$'
  86. [shortcuts]
  87. [shortcuts.composing]
  88. edit_mail = 'e'
  89. [shortcuts.listing]
  90. new_mail = 'm'
  91. set_seen = 'n'
  92. [terminal]
  93. theme = "light"
  94. .Ed
  95. .Pp
  96. available options are listed below.
  97. .Sy default values are shown in parentheses.
  98. .Sh ACCOUNTS
  99. .Bl -tag -width 36n
  100. .It Ic root_mailbox Ar String
  101. the backend-specific path of the root_mailbox, usually INBOX.
  102. .It Ic format Ar String Op maildir mbox imap notmuch jmap
  103. the format of the mail backend.
  104. .It Ic subscribed_mailboxes Ar [String,]
  105. an array of mailbox paths to display in the UI.
  106. Paths are relative to the root mailbox (eg "INBOX/Sent", not "Sent").
  107. The glob wildcard
  108. .Em \&*
  109. can be used to match every mailbox name and path.
  110. .It Ic identity Ar String
  111. your e-mail address that is inserted in the From: headers of outgoing mail
  112. .It Ic index_style Ar String
  113. set the way mailboxes are displayed
  114. .El
  115. .TS
  116. allbox tab(:);
  117. lb l.
  118. conversations:shows one entry per thread
  119. compact:shows one row per thread
  120. threaded:shows threads as a tree structure
  121. plain:shows one row per mail, regardless of threading
  122. .TE
  123. .Bl -tag -width 36n
  124. .It Ic display_name Ar String
  125. (optional) a name which can be combined with your address:
  126. "Name <email@address.tld>"
  127. .It Ic read_only Ar boolean
  128. attempt to not make any changes to this account.
  129. .Pq Em false
  130. .It Ic manual_refresh Ar boolean
  131. (optional) if true, do not monitor account for changes (shortcut listing.refresh)
  132. .Pq Em false
  133. .It Ic refresh_command Ar String
  134. (optional) command to execute when manually refreshing (shortcut listing.refresh)
  135. .Pq Em None
  136. .It Ic cache_type Ar String
  137. (optional) choose which cache backend to use.
  138. Available options are 'none' and 'sqlite3'
  139. .Pq Em "sqlite3"
  140. .It Ic vcard_folder Ar String
  141. (optional) Folder that contains .vcf files.
  142. They are parsed and imported read-only.
  143. .It Ic mailboxes Ar mailbox
  144. (optional) configuration for each mailbox.
  145. Its format is described below in
  146. .Sx mailboxes Ns
  147. \&.
  148. .El
  149. .Sh notmuch only
  150. .Ic root_mailbox
  151. points to the directory which contains the
  152. .Pa .notmuch/
  153. subdirectory.
  154. notmuch mailboxes are virtual, since they are defined by user-given notmuch queries.
  155. Thus you have to explicitly state the mailboxes you want in the
  156. .Ic mailboxes
  157. field and set the
  158. .Ar query
  159. property to each of them.
  160. Example:
  161. .Bd -literal
  162. [accounts.notmuch]
  163. format = "notmuch"
  164. \&...
  165. [accounts.notmuch.mailboxes]
  166. "INBOX" = { query="tag:inbox", subscribe = true }
  167. "Drafts" = { query="tag:draft", subscribe = true }
  168. "Sent" = { query="from:username@server.tld from:username2@server.tld", subscribe = true }
  169. .Ed
  170. .Sh IMAP only
  171. IMAP specific options are:
  172. .Bl -tag -width 36n
  173. .It Ic server_hostname Ar String
  174. example:
  175. .Qq mail.example.tld
  176. .It Ic server_username Ar String
  177. .It Ic server_password Ar String
  178. .It Ic server_port Ar number
  179. (optional)
  180. .\" default value
  181. .Pq Em 143
  182. .It Ic use_starttls Ar boolean
  183. (optional) if port is 993 and use_starttls is unspecified, it becomes false by default.
  184. .\" default value
  185. .Pq Em true
  186. .It Ic danger_accept_invalid_certs Ar boolean
  187. (optional) do not validate TLS certificates.
  188. .\" default value
  189. .Pq Em false
  190. .El
  191. .Sh JMAP only
  192. JMAP specific options are:
  193. .Bl -tag -width 36n
  194. .It Ic server_hostname Ar String
  195. example:
  196. .Qq mail.example.tld
  197. .It Ic server_username Ar String
  198. .It Ic server_password Ar String
  199. .It Ic server_port Ar number
  200. (optional)
  201. .\" default value
  202. .Pq Em 443
  203. .It Ic danger_accept_invalid_certs Ar boolean
  204. (optional) do not validate TLS certificates.
  205. .\" default value
  206. .Pq Em false
  207. .El
  208. .Sh mailboxes
  209. .Bl -tag -width 36n
  210. .It Ic alias Ar String
  211. (optional) show a different name for this mailbox in the UI
  212. .It Ic autoload Ar boolean
  213. (optional) load this mailbox on startup (not functional yet)
  214. .It Ic subscribe Ar boolean
  215. (optional) watch this mailbox for updates
  216. .\" default value
  217. .Pq Em true
  218. .It Ic ignore Ar boolean
  219. (optional) silently insert updates for this mailbox, if any
  220. .\" default value
  221. .Pq Em false
  222. .It Ic usage Ar boolean
  223. (optional) special usage of this mailbox.
  224. Valid values are:
  225. .Bl -bullet -compact
  226. .It
  227. .Ar Normal
  228. .It
  229. .Ar Inbox
  230. .It
  231. .Ar Archive
  232. .It
  233. .Ar Drafts
  234. .It
  235. .Ar Flagged
  236. .It
  237. .Ar Junk
  238. .It
  239. .Ar Sent
  240. .It
  241. .Ar Trash
  242. .El
  243. otherwise usage is inferred from the mailbox title.
  244. .It Ic conf_override Ar boolean
  245. (optional) override global settings for this mailbox.
  246. Available sections to override are
  247. .Em pager, notifications, shortcuts, composing
  248. and the account options
  249. .Em identity and index_style Ns
  250. \&.
  251. Example:
  252. .Bd -literal
  253. [accounts."imap.domain.tld".mailboxes."INBOX"]
  254. index_style = "plain"
  255. [accounts."imap.domain.tld".mailboxes."INBOX".pager]
  256. filter = ""
  257. .Ed
  258. .El
  259. .Sh COMPOSING
  260. .Bl -tag -width 36n
  261. .It Ic mailer_cmd Ar String
  262. command to pipe new mail to, exit code must be 0 for success.
  263. .It Ic editor_cmd Ar String
  264. command to launch editor.
  265. Can have arguments.
  266. Draft filename is given as the last argument.
  267. If it's missing, the environment variable $EDITOR is looked up.
  268. .It Ic embed Ar boolean
  269. (optional) embed editor within meli
  270. .\" default value
  271. .Pq Em false
  272. .It Ic format_flowed Ar boolean
  273. (optional) set format=flowed [RFC3676] in text/plain attachments.
  274. .\" default value
  275. .Pq Em true
  276. .It Ic default_header_values Ar hash table String[String]
  277. Default header values used when creating a new draft.
  278. .El
  279. .Sh SHORTCUTS
  280. Shortcuts can take the following values:
  281. .Qq Em Backspace
  282. .Qq Em Left
  283. .Qq Em Right
  284. .Qq Em Up
  285. .Qq Em Down
  286. .Qq Em Home
  287. .Qq Em End
  288. .Qq Em PageUp
  289. .Qq Em PageDown
  290. .Qq Em Delete
  291. .Qq Em Insert
  292. .Qq Em Enter
  293. .Qq Em Tab
  294. .Qq Em Esc
  295. .Qq Em F1..F12
  296. .Qq Em M-char
  297. .Qq Em C-char
  298. and
  299. .Qq Em char Ns
  300. , where char is a single character string.
  301. .sp
  302. The headings before each list indicate the map key of the shortcut list.
  303. For example for the first list titled
  304. .Em general
  305. the configuration is typed as follows:
  306. .Bd -literal
  307. [shortcuts.general]
  308. next_tab = 'T'
  309. .Ed
  310. .sp
  311. and for
  312. .Em compact-listing Ns
  313. :
  314. .Bd -literal
  315. [shortcuts.compact-listing]
  316. open_thread = "Enter"
  317. exit_thread = 'i'
  318. .Ed
  319. .sp
  320. .Pp
  321. .Em general
  322. .Bl -tag -width 36n
  323. .It Ic next_tab
  324. Go to next tab.
  325. .\" default value
  326. .Pq Em T
  327. .It Ic go_to_tab
  328. Go to the
  329. .Em n Ns
  330. th tab
  331. .Pq Em cannot be redefined
  332. .El
  333. .sp
  334. .Em listing
  335. .Bl -tag -width 36n
  336. .It Ic prev_page
  337. Go to previous page.
  338. .\" default value
  339. .Pq Em PageUp
  340. .It Ic next_page
  341. Go to next page.
  342. .\" default value
  343. .Pq Em PageDown
  344. .It Ic prev_mailbox
  345. Go to previous mailbox.
  346. .\" default value
  347. .Pq Em K
  348. .It Ic next_mailbox
  349. Go to next mailbox.
  350. .\" default value
  351. .Pq Em J
  352. .It Ic prev_account
  353. Go to previous account.
  354. .\" default value
  355. .Pq Em l
  356. .It Ic next_account
  357. Go to next account.
  358. .\" default value
  359. .Pq Em h
  360. .It Ic new_mail
  361. Start new mail draft in new tab
  362. .\" default value
  363. .Pq Em m
  364. .It Ic set_seen
  365. Set thread as seen.
  366. .\" default value
  367. .Pq Em n
  368. .It Ic refresh
  369. Manually request a mailbox refresh.
  370. .\" default value
  371. .Pq Em F5
  372. .It Ic search
  373. Search within list of e-mails.
  374. .\" default value
  375. .Pq Em /
  376. .It Ic toggle_menu_visibility
  377. Toggle visibility of side menu in mail list.
  378. .\" default value
  379. .Pq Em `
  380. .El
  381. .sp
  382. .Em compact-listing
  383. .Bl -tag -width 36n
  384. .It Ic exit_thread
  385. Exit thread view
  386. .\" default value
  387. .Pq Em i
  388. .It Ic open_thread
  389. Open thread.
  390. .\" default value
  391. .Pq Em Enter
  392. .It Ic select_entry
  393. Select thread entry.
  394. .\" default value
  395. .Pq Em v
  396. .El
  397. .sp
  398. .Em pager
  399. .Bl -tag -width 36n
  400. .It Ic scroll_up
  401. Scroll up pager.
  402. .\" default value
  403. .Pq Em k
  404. .It Ic scroll_down
  405. Scroll down pager.
  406. .\" default value
  407. .Pq Em j
  408. .It Ic page_up
  409. Go to previous pager page
  410. .\" default value
  411. .Pq Em PageUp
  412. .It Ic page_down
  413. Go to next pager pag
  414. .\" default value
  415. .Pq Em PageDown
  416. .El
  417. .sp
  418. .Em contact-list
  419. .Bl -tag -width 36n
  420. .It Ic create_contact
  421. Create new contact.
  422. .\" default value
  423. .Pq Em c
  424. .It Ic edit_contact
  425. Edit contact under cursor
  426. .\" default value
  427. .Pq Em e
  428. .It Ic mail_contact
  429. Mail contact under cursor
  430. .\" default value
  431. .Pq Em m
  432. .It Ic toggle_menu_visibility
  433. Toggle visibility of side menu in mail list.
  434. .\" default value
  435. .Pq Em `
  436. .El
  437. .sp
  438. .sp
  439. .Em composing
  440. .Bl -tag -width 36n
  441. .It Ic send_mail
  442. Deliver draft to mailer
  443. .\" default value
  444. .Pq Em s
  445. .It Ic edit_mail
  446. Edit mail.
  447. .\" default value
  448. .Pq Em e
  449. .El
  450. .sp
  451. .Em envelope-view
  452. .Pp
  453. To "select" an attachment, type its index (you will see the typed result in the command buffer on your bottom right of the status line) and then issue the corresponding command.
  454. .Bl -tag -width 36n
  455. .It Ic add_addresses_to_contacts Ns
  456. Select addresses from envelope to add to contacts.
  457. .\" default value
  458. .Pq Em c
  459. .It Ic view_raw_source
  460. View raw envelope source in a pager.
  461. .\" default value
  462. .Pq Em M-r
  463. .It Ic reply
  464. Reply to envelope.
  465. .\" default value
  466. .Pq Em R
  467. .It Ic edit
  468. Open envelope in composer.
  469. .\" default value
  470. .Pq Em e
  471. .It Ic return_to_normal_view
  472. Return to envelope if viewing raw source or attachment.
  473. .\" default value
  474. .Pq Em r
  475. .It Ic open_attachment
  476. Opens selected attachment with
  477. .Cm xdg-open
  478. .\" default value
  479. .Pq Em a
  480. .It Ic open_mailcap
  481. Opens selected attachment according to its mailcap entry.
  482. See
  483. .Xr meli.1 FILES
  484. for the mailcap file locations.
  485. .\" default value
  486. .Pq Em m
  487. .It Ic go_to_url
  488. Go to url of given index
  489. .\" default value
  490. .Pq Em g
  491. .It Ic toggle_url_mode
  492. Toggles url open mode.
  493. When active, it prepends an index next to each url that you can select by typing and open by issuing
  494. .Ic go_to_url
  495. .\" default value
  496. .Pq Em u
  497. .It Ic toggle_expand_headers
  498. Expand extra headers (References and others)
  499. .\" default value
  500. .Pq Em h
  501. .El
  502. .sp
  503. .Em thread-view
  504. .Bl -tag -width 36n
  505. .It Ic reverse_thread_order
  506. Reverse thread order.
  507. .\" default value
  508. .Pq Em r
  509. .It Ic toggle_mailview
  510. Toggle mail view visibility.
  511. .\" default value
  512. .Pq Em p
  513. .It Ic toggle_threadview
  514. Toggle thread view visibility.
  515. .\" default value
  516. .Pq Em t
  517. .It Ic collapse_subtree
  518. Collapse thread branches.
  519. .\" default value
  520. .Pq Em h
  521. .It Ic prev_page
  522. Go to previous page.
  523. .\" default value
  524. .Pq Em PageUp
  525. .It Ic next_page
  526. Go to next page.
  527. .\" default value
  528. .Pq Em PageDown
  529. .El
  530. .sp
  531. .Sh NOTIFICATIONS
  532. .Bl -tag -width 36n
  533. .It Ic enable Ar boolean
  534. enable freedesktop-spec notifications.
  535. this is usually what you want
  536. .\" default value
  537. .Pq Em true
  538. .It Ic script Ar String
  539. (optional) script to pass notifications to, with title as 1st arg and body as 2nd
  540. .\" default value
  541. .Pq Em none
  542. .It Ic xbiff_file_path Ar String
  543. (optional) file that gets its size updated when new mail arrives
  544. .Pq Em none
  545. .\" default value
  546. .It Ic play_sound Ar boolean
  547. (optional) play theme sound in notifications if possible
  548. .Pq Em false
  549. .\" default value
  550. .It Ic sound_file Ar String
  551. (optional) play sound file in notifications if possible
  552. .\" default value
  553. .Pq Em none
  554. .El
  555. .Sh PAGER
  556. .Bl -tag -width 36n
  557. .It Ic pager_context Ar num
  558. (optional) number of context lines when going to next page.
  559. (Unimplemented)
  560. .\" default value
  561. .Pq Em 0
  562. .It Ic headers_sticky Ar boolean
  563. (optional) always show headers when scrolling.
  564. .\" default value
  565. .Pq Em true
  566. .It Ic html_filter Ar String
  567. (optional) pipe html attachments through this filter before display
  568. .\" default value
  569. .Pq Em none
  570. .It Ic filter Ar String
  571. (optional) a command to pipe mail output through for viewing in pager.
  572. .\" default value
  573. .Pq Em none
  574. .It Ic format_flowed Ar bool
  575. (optional) respect format=flowed
  576. .\" default value
  577. .Pq Em true
  578. .It Ic split_long_lines Ar bool
  579. (optional) Split long lines that would overflow on the x axis.
  580. .\" default value
  581. .Pq Em true
  582. .It Ic minimum_width Ar num
  583. (optional) Minimum text width in columns.
  584. .\" default value
  585. .Pq Em 80
  586. .El
  587. .Sh LISTING
  588. .Bl -tag -width 36n
  589. .It Ic context_lines Ar num
  590. (optional) number of context lines when going to next page.
  591. (Unimplemented)
  592. .\" default value
  593. .Pq Em 0
  594. .It Ic datetime_fmt Ar String
  595. (optional) datetime formatting passed verbatim to strftime(3).
  596. .\" default value
  597. .Pq Em \&%Y-\&%m-\&%d \&%T
  598. .It Ic recent_dates Ar Boolean
  599. (optional) Show recent dates as `X {minutes,hours,days} ago`, up to 7 days.
  600. .\" default value
  601. .Pq Em true
  602. .El
  603. .Sh TAGS
  604. .Bl -tag -width 36n
  605. .It Ic colours Ar hash table String[Color]
  606. (optional) set UI colors for tags
  607. .It Ic ignore_tags Ar Array String
  608. (optional) hide tags (not the tagged messages themselves)
  609. .El
  610. .sp
  611. example configuration:
  612. .sp
  613. .Bd -literal
  614. [tags]
  615. # valid inputs: #HHHHHH, #ABC -> #AABBCC, XTERM_NAME, 0-255 byte
  616. colors = { signed="#Ff6600", replied="DeepSkyBlue4", draft="#f00", replied="8" }
  617. [accounts.dummy]
  618. \&...
  619. [accounts.dummy.mailboxes]
  620. # per mailbox override:
  621. "INBOX" = { tags.ignore_tags=["inbox", ] }
  622. .Ed
  623. .Sh PGP
  624. .Bl -tag -width 36n
  625. .It Ic auto_verify_signatures Ar boolean
  626. auto verify signed e-mail according to RFC3156
  627. .\" default value
  628. .Pq Em true
  629. .It Ic auto_sign Ar boolean
  630. (optional) always sign sent messages
  631. .\" default value
  632. .Pq Em false
  633. .It Ic key Ar String
  634. (optional) key to be used when signing/encrypting (not functional yet)
  635. .\" default value
  636. .Pq Em none
  637. .It Ic gpg_binary Ar String
  638. (optional) gpg binary name or file location to use
  639. .\" default value
  640. .Pq Em "gpg2"
  641. .El
  642. .Sh TERMINAL
  643. .Bl -tag -width 36n
  644. .It Ic theme Ar String
  645. (optional) select between these themes: light / dark
  646. .\" default value
  647. .Pq Em dark
  648. .It Ic ascii_drawing Ar boolean
  649. (optional) if true, box drawing will be done with ascii characters.
  650. .\" default value
  651. .Pq Em false
  652. .It Ic use_color Ar boolean
  653. (optional) if false, no ANSI colors are used
  654. .\" default value
  655. .Pq Em true
  656. .It Ic window_title Ar String
  657. (optional) set window title in xterm compatible terminals (empty string means no window title is set)
  658. .\" default value
  659. .Pq Em "meli"
  660. .It Ic themes Ar hash table String[String[Attribute]]
  661. define UI themes.
  662. See
  663. .Xr meli-themes 5
  664. for details.
  665. .Bd -literal
  666. [terminal]
  667. theme = "themeB"
  668. [terminal.themes.themeA]
  669. "mail.view.body" = {fg = "HotPink3", bg = "LightSalmon1"}
  670. \&...
  671. [terminal.themes.themeB]
  672. "mail.view.body" = {fg = "CadetBlue", bg = "White"}
  673. \&...
  674. [terminal.themes.themeC]
  675. \&...
  676. .Ed
  677. .El
  678. .Sh SEE ALSO
  679. .Xr meli 1 ,
  680. .Xr meli-themes 5
  681. .Sh CONFORMING TO
  682. TOML Standard v.0.5.0 https://github.com/toml-lang/toml/blob/master/versions/en/toml-v0.5.0.md
  683. .Sh AUTHORS
  684. Copyright 2017-2019
  685. .An Manos Pitsidianakis Aq epilys@nessuent.xyz
  686. Released under the GPL, version 3 or greater.
  687. This software carries no warranty of any kind.
  688. (See COPYING for full copyright and warranty notices.)
  689. .Pp
  690. .Aq https://meli.delivery