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.

697 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
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_folder = "/path/to/root/folder"
  60. format = "Maildir"
  61. index_style = "Compact"
  62. identity="email@address.tld"
  63. subscribed_folders = ["folder", "folder/Sent"] # or [ "*", ] for all folders
  64. display_name = "Name"
  65. # Set folder-specific settings
  66. [accounts.account-name.folders]
  67. "INBOX" = { alias="Inbox" } #inline table
  68. "drafts" = { alias="Drafts" } #inline table
  69. [accounts.account-name.folders."foobar-devel"] # or a regular table
  70. ignore = true # don't show notifications for this folder
  71. # Setting up an mbox account
  72. [accounts.mbox]
  73. root_folder = "/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_folder Ar String
  101. the backend-specific path of the root_folder, 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_folders Ar [String,]
  105. an array of folder paths to display in the UI.
  106. Paths are relative to the root folder (eg "INBOX/Sent", not "Sent").
  107. The glob wildcard
  108. .Em \&*
  109. can be used to match every folder 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 folders Ar folder_config
  144. (optional) configuration for each folder.
  145. Its format is described below in
  146. .Sx FOLDERS Ns
  147. \&.
  148. .El
  149. .Sh notmuch only
  150. .Ic root_folder
  151. points to the directory which contains the
  152. .Pa .notmuch/
  153. subdirectory.
  154. notmuch folders are virtual, since they are defined by user-given notmuch queries.
  155. Thus you have to explicitly state the folders you want in the
  156. .Ic folders
  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.folders]
  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 FOLDERS
  209. .Bl -tag -width 36n
  210. .It Ic alias Ar String
  211. (optional) show a different name for this folder in the UI
  212. .It Ic autoload Ar boolean
  213. (optional) load this folder on startup (not functional yet)
  214. .It Ic subscribe Ar boolean
  215. (optional) watch this folder for updates
  216. .\" default value
  217. .Pq Em true
  218. .It Ic ignore Ar boolean
  219. (optional) silently insert updates for this folder, if any
  220. .\" default value
  221. .Pq Em false
  222. .It Ic usage Ar boolean
  223. (optional) special usage of this folder.
  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 folder title.
  244. .It Ic conf_override Ar boolean
  245. (optional) override global settings for this folder.
  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".folders."INBOX"]
  254. index_style = "plain"
  255. [accounts."imap.domain.tld".folders."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. .El
  277. .Sh SHORTCUTS
  278. Shortcuts can take the following values:
  279. .Qq Em Backspace
  280. .Qq Em Left
  281. .Qq Em Right
  282. .Qq Em Up
  283. .Qq Em Down
  284. .Qq Em Home
  285. .Qq Em End
  286. .Qq Em PageUp
  287. .Qq Em PageDown
  288. .Qq Em Delete
  289. .Qq Em Insert
  290. .Qq Em Enter
  291. .Qq Em Tab
  292. .Qq Em Esc
  293. .Qq Em F1..F12
  294. .Qq Em M-char
  295. .Qq Em C-char
  296. and
  297. .Qq Em char Ns
  298. , where char is a single character string.
  299. .sp
  300. The headings before each list indicate the map key of the shortcut list.
  301. For example for the first list titled
  302. .Em general
  303. the configuration is typed as follows:
  304. .Bd -literal
  305. [shortcuts.general]
  306. next_tab = 'T'
  307. .Ed
  308. .sp
  309. and for
  310. .Em compact-listing Ns
  311. :
  312. .Bd -literal
  313. [shortcuts.compact-listing]
  314. open_thread = "Enter"
  315. exit_thread = 'i'
  316. .Ed
  317. .sp
  318. .Pp
  319. .Em general
  320. .Bl -tag -width 36n
  321. .It Ic next_tab
  322. Go to next tab.
  323. .\" default value
  324. .Pq Em T
  325. .It Ic go_to_tab
  326. Go to the
  327. .Em n Ns
  328. th tab
  329. .Pq Em cannot be redefined
  330. .El
  331. .sp
  332. .Em listing
  333. .Bl -tag -width 36n
  334. .It Ic prev_page
  335. Go to previous page.
  336. .\" default value
  337. .Pq Em PageUp
  338. .It Ic next_page
  339. Go to next page.
  340. .\" default value
  341. .Pq Em PageDown
  342. .It Ic prev_folder
  343. Go to previous folder.
  344. .\" default value
  345. .Pq Em K
  346. .It Ic next_folder
  347. Go to next folder.
  348. .\" default value
  349. .Pq Em J
  350. .It Ic prev_account
  351. Go to previous account.
  352. .\" default value
  353. .Pq Em l
  354. .It Ic next_account
  355. Go to next account.
  356. .\" default value
  357. .Pq Em h
  358. .It Ic new_mail
  359. Start new mail draft in new tab
  360. .\" default value
  361. .Pq Em m
  362. .It Ic set_seen
  363. Set thread as seen.
  364. .\" default value
  365. .Pq Em n
  366. .It Ic refresh
  367. Manually request a folder refresh.
  368. .\" default value
  369. .Pq Em F5
  370. .It Ic search
  371. Search within list of e-mails.
  372. .\" default value
  373. .Pq Em /
  374. .It Ic toggle_menu_visibility
  375. Toggle visibility of side menu in mail list.
  376. .\" default value
  377. .Pq Em `
  378. .El
  379. .sp
  380. .Em compact-listing
  381. .Bl -tag -width 36n
  382. .It Ic exit_thread
  383. Exit thread view
  384. .\" default value
  385. .Pq Em i
  386. .It Ic open_thread
  387. Open thread.
  388. .\" default value
  389. .Pq Em Enter
  390. .It Ic select_entry
  391. Select thread entry.
  392. .\" default value
  393. .Pq Em v
  394. .El
  395. .sp
  396. .Em pager
  397. .Bl -tag -width 36n
  398. .It Ic scroll_up
  399. Scroll up pager.
  400. .\" default value
  401. .Pq Em k
  402. .It Ic scroll_down
  403. Scroll down pager.
  404. .\" default value
  405. .Pq Em j
  406. .It Ic page_up
  407. Go to previous pager page
  408. .\" default value
  409. .Pq Em PageUp
  410. .It Ic page_down
  411. Go to next pager pag
  412. .\" default value
  413. .Pq Em PageDown
  414. .El
  415. .sp
  416. .Em contact-list
  417. .Bl -tag -width 36n
  418. .It Ic create_contact
  419. Create new contact.
  420. .\" default value
  421. .Pq Em c
  422. .It Ic edit_contact
  423. Edit contact under cursor
  424. .\" default value
  425. .Pq Em e
  426. .It Ic mail_contact
  427. Mail contact under cursor
  428. .\" default value
  429. .Pq Em m
  430. .It Ic toggle_menu_visibility
  431. Toggle visibility of side menu in mail list.
  432. .\" default value
  433. .Pq Em `
  434. .El
  435. .sp
  436. .sp
  437. .Em composing
  438. .Bl -tag -width 36n
  439. .It Ic send_mail
  440. Deliver draft to mailer
  441. .\" default value
  442. .Pq Em s
  443. .It Ic edit_mail
  444. Edit mail.
  445. .\" default value
  446. .Pq Em e
  447. .El
  448. .sp
  449. .Em envelope-view
  450. .Pp
  451. 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.
  452. .Bl -tag -width 36n
  453. .It Ic add_addresses_to_contacts Ns
  454. Select addresses from envelope to add to contacts.
  455. .\" default value
  456. .Pq Em c
  457. .It Ic view_raw_source
  458. View raw envelope source in a pager.
  459. .\" default value
  460. .Pq Em M-r
  461. .It Ic reply
  462. Reply to envelope.
  463. .\" default value
  464. .Pq Em R
  465. .It Ic edit
  466. Open envelope in composer.
  467. .\" default value
  468. .Pq Em e
  469. .It Ic return_to_normal_view
  470. Return to envelope if viewing raw source or attachment.
  471. .\" default value
  472. .Pq Em r
  473. .It Ic open_attachment
  474. Opens selected attachment with
  475. .Cm xdg-open
  476. .\" default value
  477. .Pq Em a
  478. .It Ic open_mailcap
  479. Opens selected attachment according to its mailcap entry.
  480. See
  481. .Xr meli.1 FILES
  482. for the mailcap file locations.
  483. .\" default value
  484. .Pq Em m
  485. .It Ic go_to_url
  486. Go to url of given index
  487. .\" default value
  488. .Pq Em g
  489. .It Ic toggle_url_mode
  490. Toggles url open mode.
  491. When active, it prepends an index next to each url that you can select by typing and open by issuing
  492. .Ic go_to_url
  493. .\" default value
  494. .Pq Em u
  495. .It Ic toggle_expand_headers
  496. Expand extra headers (References and others)
  497. .\" default value
  498. .Pq Em h
  499. .El
  500. .sp
  501. .Em thread-view
  502. .Bl -tag -width 36n
  503. .It Ic reverse_thread_order
  504. Reverse thread order.
  505. .\" default value
  506. .Pq Em r
  507. .It Ic toggle_mailview
  508. Toggle mail view visibility.
  509. .\" default value
  510. .Pq Em p
  511. .It Ic toggle_threadview
  512. Toggle thread view visibility.
  513. .\" default value
  514. .Pq Em t
  515. .It Ic collapse_subtree
  516. Collapse thread branches.
  517. .\" default value
  518. .Pq Em h
  519. .It Ic prev_page
  520. Go to previous page.
  521. .\" default value
  522. .Pq Em PageUp
  523. .It Ic next_page
  524. Go to next page.
  525. .\" default value
  526. .Pq Em PageDown
  527. .El
  528. .sp
  529. .Sh NOTIFICATIONS
  530. .Bl -tag -width 36n
  531. .It Ic enable Ar boolean
  532. enable freedesktop-spec notifications.
  533. this is usually what you want
  534. .\" default value
  535. .Pq Em true
  536. .It Ic script Ar String
  537. (optional) script to pass notifications to, with title as 1st arg and body as 2nd
  538. .\" default value
  539. .Pq Em none
  540. .It Ic xbiff_file_path Ar String
  541. (optional) file that gets its size updated when new mail arrives
  542. .Pq Em none
  543. .\" default value
  544. .It Ic play_sound Ar boolean
  545. (optional) play theme sound in notifications if possible
  546. .Pq Em false
  547. .\" default value
  548. .It Ic sound_file Ar String
  549. (optional) play sound file in notifications if possible
  550. .\" default value
  551. .Pq Em none
  552. .El
  553. .Sh PAGER
  554. .Bl -tag -width 36n
  555. .It Ic pager_context Ar num
  556. (optional) number of context lines when going to next page.
  557. (Unimplemented)
  558. .\" default value
  559. .Pq Em 0
  560. .It Ic headers_sticky Ar boolean
  561. (optional) always show headers when scrolling.
  562. .\" default value
  563. .Pq Em true
  564. .It Ic html_filter Ar String
  565. (optional) pipe html attachments through this filter before display
  566. .\" default value
  567. .Pq Em none
  568. .It Ic filter Ar String
  569. (optional) a command to pipe mail output through for viewing in pager.
  570. .\" default value
  571. .Pq Em none
  572. .It Ic format_flowed Ar bool
  573. (optional) respect format=flowed
  574. .\" default value
  575. .Pq Em true
  576. .It Ic split_long_lines Ar bool
  577. (optional) Split long lines that would overflow on the x axis.
  578. .\" default value
  579. .Pq Em true
  580. .It Ic minimum_width Ar num
  581. (optional) Minimum text width in columns.
  582. .\" default value
  583. .Pq Em 80
  584. .El
  585. .Sh LISTING
  586. .Bl -tag -width 36n
  587. .It Ic context_lines Ar num
  588. (optional) number of context lines when going to next page.
  589. (Unimplemented)
  590. .\" default value
  591. .Pq Em 0
  592. .It Ic datetime_fmt Ar String
  593. (optional) datetime formatting passed verbatim to strftime(3).
  594. .\" default value
  595. .Pq Em \&%Y-\&%m-\&%d \&%T
  596. .It Ic recent_dates Ar Boolean
  597. (optional) Show recent dates as `X {minutes,hours,days} ago`, up to 7 days.
  598. .\" default value
  599. .Pq Em true
  600. .El
  601. .Sh TAGS
  602. .Bl -tag -width 36n
  603. .It Ic colours Ar hash table String[Color]
  604. (optional) set UI colors for tags
  605. .It Ic ignore_tags Ar Array String
  606. (optional) hide tags (not the tagged messages themselves)
  607. .El
  608. .sp
  609. example configuration:
  610. .sp
  611. .Bd -literal
  612. [tags]
  613. # valid inputs: #HHHHHH, #ABC -> #AABBCC, XTERM_NAME, 0-255 byte
  614. colors = { signed="#Ff6600", replied="DeepSkyBlue4", draft="#f00", replied="8" }
  615. [accounts.dummy]
  616. \&...
  617. [accounts.dummy.folders]
  618. # per folder override:
  619. "INBOX" = { tags.ignore_tags=["inbox", ] }
  620. .Ed
  621. .Sh PGP
  622. .Bl -tag -width 36n
  623. .It Ic auto_verify_signatures Ar boolean
  624. auto verify signed e-mail according to RFC3156
  625. .\" default value
  626. .Pq Em true
  627. .It Ic auto_sign Ar boolean
  628. (optional) always sign sent messages
  629. .\" default value
  630. .Pq Em false
  631. .It Ic key Ar String
  632. (optional) key to be used when signing/encrypting (not functional yet)
  633. .\" default value
  634. .Pq Em none
  635. .It Ic gpg_binary Ar String
  636. (optional) gpg binary name or file location to use
  637. .\" default value
  638. .Pq Em "gpg2"
  639. .El
  640. .Sh TERMINAL
  641. .Bl -tag -width 36n
  642. .It Ic theme Ar String
  643. (optional) select between these themes: light / dark
  644. .\" default value
  645. .Pq Em dark
  646. .It Ic ascii_drawing Ar boolean
  647. (optional) if true, box drawing will be done with ascii characters.
  648. .\" default value
  649. .Pq Em false
  650. .It Ic use_color Ar boolean
  651. (optional) if false, no ANSI colors are used
  652. .\" default value
  653. .Pq Em true
  654. .It Ic window_title Ar String
  655. (optional) set window title in xterm compatible terminals (empty string means no window title is set)
  656. .\" default value
  657. .Pq Em "meli"
  658. .It Ic themes Ar hash table String[String[Attribute]]
  659. define UI themes.
  660. See
  661. .Xr meli-themes 5
  662. for details.
  663. .Bd -literal
  664. [terminal]
  665. theme = "themeB"
  666. [terminal.themes.themeA]
  667. "mail.view.body" = {fg = "HotPink3", bg = "LightSalmon1"}
  668. \&...
  669. [terminal.themes.themeB]
  670. "mail.view.body" = {fg = "CadetBlue", bg = "White"}
  671. \&...
  672. [terminal.themes.themeC]
  673. \&...
  674. .Ed
  675. .El
  676. .Sh SEE ALSO
  677. .Xr meli 1 ,
  678. .Xr meli-themes 5
  679. .Sh CONFORMING TO
  680. TOML Standard v.0.5.0 https://github.com/toml-lang/toml/blob/master/versions/en/toml-v0.5.0.md
  681. .Sh AUTHORS
  682. Copyright 2017-2019
  683. .An Manos Pitsidianakis Aq epilys@nessuent.xyz
  684. Released under the GPL, version 3 or greater.
  685. This software carries no warranty of any kind.
  686. (See COPYING for full copyright and warranty notices.)
  687. .Pp
  688. .Aq https://meli.delivery