From: Kevin McCarthy Date: Sat, 4 Jun 2016 18:32:07 +0000 (-0700) Subject: Clean up the sidebar manual. X-Git-Tag: neomutt-20160822~134 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=15a39c34e2c4aee33bdb54967ac3a6b075a9c529;p=neomutt Clean up the sidebar manual. Remove the introduction section. It's a nice effort, but reads more like a tutorial than something that belongs in section 2. Will probably put in on the website instead. Remove references to a "patch", neomutt, and the history. Remove the sample muttrc from the manual. Fix validation errors for the documentation. --- diff --git a/doc/manual.xml.head b/doc/manual.xml.head index da7a659c9..912ebe25f 100644 --- a/doc/manual.xml.head +++ b/doc/manual.xml.head @@ -406,620 +406,12 @@ attach to a message, select multiple files to attach and many more. - Sidebar - - The Sidebar shows a list of all your mailboxes. The list can be - turned on and off, it can be themed and the list style can be - configured. - - - This part of the manual is suitable for beginners. - If you already know Mutt you could skip ahead to the main - Sidebar guide. - If you just want to get started, you could use the sample - Sidebar muttrc. - - - This version of Sidebar is based on Terry Chan's - 2015-11-11 release. - It contains many - new features, - lots of - bugfixes - and a generous helping of - new documentation which you are already reading. - - - To check if Mutt supports Sidebar, look for the string - +USE_SIDEBAR in the mutt version. - - -mutt -v - - - Let's turn on the Sidebar: - - set sidebar_visible - - You will see something like this. - A list of mailboxes on the left. - A list of emails, from the selected mailbox, on the right. - - -Fruit [1] 3/8| 1 + Jan 24 Rhys Lee (192) Yew -Animals [1] 2/6| 2 + Feb 11 Grace Hall (167) Ilama -Cars 4| 3 Feb 23 Aimee Scott (450) Nectarine -Seas 1/7| 4 ! Feb 28 Summer Jackson (264) Lemon - | 5 Mar 07 Callum Harrison (464) Raspberry - | 6 N + Mar 24 Samuel Harris (353) Tangerine - | 7 N + Sep 05 Sofia Graham (335) Cherry - | 8 N Sep 16 Ewan Brown (105) Ugli - | - | - - - This user has four mailboxes: Fruit, - Cars, Animals and - Seas. - - - The current, open, mailbox is Fruit. We can - also see information about the other mailboxes. For example: - The Animals mailbox contains, 1 flagged email, 2 - new emails out of a total of 6 emails. - - - Navigation - - The Sidebar adds some new functions - to Mutt. - - - The user pressed the c key to - <change-folder> to the - Animals mailbox. The Sidebar automatically - updated the indicator to match. - - -Fruit [1] 3/8| 1 Jan 03 Tia Gibson (362) Caiman -Animals [1] 2/6| 2 + Jan 22 Rhys Lee ( 48) Dolphin -Cars 4| 3 ! Aug 16 Ewan Brown (333) Hummingbird -Seas 1/7| 4 Sep 25 Grace Hall ( 27) Capybara - | 5 N + Nov 12 Evelyn Rogers (453) Tapir - | 6 N + Nov 16 Callum Harrison (498) Hedgehog - | - | - | - | - - - Let's map some functions: - - -bind index,pager \CP sidebar-prev # Ctrl-Shift-P - Previous Mailbox -bind index,pager \CN sidebar-next # Ctrl-Shift-N - Next Mailbox -bind index,pager \CO sidebar-open # Ctrl-Shift-O - Open Highlighted Mailbox - - - Press Ctrl-Shift-N (Next mailbox) twice will - move the Sidebar highlight to - down to the Seas mailbox. - - -Fruit [1] 3/8| 1 Jan 03 Tia Gibson (362) Caiman -Animals [1] 2/6| 2 + Jan 22 Rhys Lee ( 48) Dolphin -Cars 4| 3 ! Aug 16 Ewan Brown (333) Hummingbird -Seas 1/7| 4 Sep 25 Grace Hall ( 27) Capybara - | 5 N + Nov 12 Evelyn Rogers (453) Tapir - | 6 N + Nov 16 Callum Harrison (498) Hedgehog - | - | - | - | - - - Functions <sidebar-next> and - <sidebar-prev> move the Sidebar - highlight. - They do not change the open - mailbox. - - - Press Ctrl-Shift-O - (<sidebar-open>) - to open the highlighted mailbox. - - -Fruit [1] 3/8| 1 ! Mar 07 Finley Jones (139) Molucca Sea -Animals [1] 2/6| 2 + Mar 24 Summer Jackson ( 25) Arafura Sea -Cars 4| 3 + Feb 28 Imogen Baker (193) Pechora Sea -Seas 1/7| 4 N + Feb 23 Isla Hussain (348) Balearic Sea - | - | - | - | - | - | - - - - Features - - The Sidebar shows a list of mailboxes in a panel. - - - Everything about the Sidebar can be configured. - - - <link linkend="intro-sidebar-basics">State of the Sidebar</link> - Visibility - Width - - - <link linkend="intro-sidebar-limit">Which mailboxes are displayed</link> - Display all - Limit to mailboxes with new mail - Whitelist mailboxes to display always - - - <link linkend="sidebar-sort">The order in which mailboxes are displayed</link> - - Unsorted (order of mailboxes commands) - Sorted alphabetically - Sorted by number of new mails - - - <link linkend="intro-sidebar-colors">Color</link> - Sidebar indicators and divider - Mailboxes depending on their type - Mailboxes depending on their contents - - - <link linkend="sidebar-functions">Key bindings</link> - Hide/Unhide the Sidebar - Select previous/next mailbox - Select previous/next mailbox with new mail - Page up/down through a list of mailboxes - - - Misc - Formatting string for mailbox - Wraparound searching - Flexible mailbox abbreviations - Support for Unicode mailbox names (utf-8) - - - - Display - - Everything about the Sidebar can be configured. - - - For a quick reference: - Sidebar variables to set - Sidebar colors to apply - Sidebar sort methods - - - Sidebar Basics - - The most important variable is $sidebar_visible. - You can set this in your muttrc, or bind a key to the - function <sidebar-toggle-visible>. - - -set sidebar_visible # Make the Sidebar visible by default -bind index,pager B sidebar-toggle-visible # Use 'B' to switch the Sidebar on and off - - - Next, decide how wide you want the Sidebar to be. 25 - characters might be enough for the mailbox name and some numbers. - Remember, you can hide/show the Sidebar at the press of button. - - - Finally, you might want to change the divider character. - By default, Sidebar draws an ASCII line between it and the Index panel - If your terminal supports it, you can use a Unicode line-drawing character. - - -set sidebar_width = 25 # Plenty of space -set sidebar_divider_char = '│' # Pretty line-drawing character - - - - Sidebar Format String - - $sidebar_format allows you to customize the Sidebar display. - For an introduction, read format strings - including the section about conditionals. - - - The default value is %B%?F? [%F]?%* %?N?%N/?%S - - - Which breaks down as: - %B - Mailbox name - %?F? [%F]? - If flagged emails [%F], otherwise nothing - %* - Pad with spaces - %?N?%N/? - If new emails %N/, otherwise nothing - %S - Total number of emails - - - sidebar_format - - - - Format - Notes - Description - - - - - %B - - Name of the mailbox - - - %S - * - Size of mailbox (total number of messages) - - - %N - * - Number of New messages in the mailbox - - - %F - * - Number of Flagged messages in the mailbox - - - %! - - - !: one flagged message; - !!: two flagged messages; - n!: n flagged messages (for n > 2). - Otherwise prints nothing. - - - - %d - * ‡ - Number of deleted messages - - - %L - * ‡ - Number of messages after limiting - - - %t - * ‡ - Number of tagged messages - - - %>X - - Right justify the rest of the string and pad with X - - - %|X - - Pad to the end of the line with - X - - - %*X - - Soft-fill with character Xas pad - - - -
- - * = Can be optionally printed if nonzero - - - ‡ = Only applicable to the current folder - - - Here are some examples. - They show the number of (F)lagged, (N)ew and (S)ize. - - - sidebar_format - - - - Format - Example - - - - - %B%?F? [%F]?%* %?N?%N/?%S - mailbox [F] N/S - - - %B%* %F:%N:%S - mailbox F:N:S - - - %B %?N?(%N)?%* %S - mailbox (N) S - - - %B%* ?F?%F/?%N - mailbox F/S - - - -
- - - Abbreviating Mailbox Names - - $sidebar_delim_chars tells Sidebar - how to split up mailbox paths. For local directories - use /; for IMAP folders use . - - - Example 1 - - This example works well if your mailboxes have unique names - after the last separator. - - - Add some mailboxes of diffent depths. - - -set folder="~/mail" -mailboxes =fruit/apple =fruit/banana =fruit/cherry -mailboxes =water/sea/sicily =water/sea/archipelago =water/sea/sibuyan -mailboxes =water/ocean/atlantic =water/ocean/pacific =water/ocean/arctic - - - Shorten the names: - - -set sidebar_short_path # Shorten mailbox names -set sidebar_delim_chars="/" # Delete everything up to the last / character - - - The screenshot below shows what the Sidebar would look like - before and after shortening. - - -|fruit/apple |apple -|fruit/banana |banana -|fruit/cherry |cherry -|water/sea/sicily |sicily -|water/sea/archipelago |archipelago -|water/sea/sibuyan |sibuyan -|water/ocean/atlantic |atlantic -|water/ocean/pacific |pacific -|water/ocean/arctic |arctic - - - - Example 2 - - This example works well if you have lots of mailboxes which are arranged - in a tree. - - - Add some mailboxes of diffent depths. - - -set folder="~/mail" -mailboxes =fruit -mailboxes =fruit/apple =fruit/banana =fruit/cherry -mailboxes =water -mailboxes =water/sea -mailboxes =water/sea/sicily =water/sea/archipelago =water/sea/sibuyan -mailboxes =water/ocean -mailboxes =water/ocean/atlantic =water/ocean/pacific =water/ocean/arctic - - - Shorten the names: - - -set sidebar_short_path # Shorten mailbox names -set sidebar_delim_chars="/" # Delete everything up to the last / character -set sidebar_folder_indent # Indent folders whose names we've shortened -set sidebar_indent_string=" " # Indent with two spaces - - - The screenshot below shows what the Sidebar would look like - before and after shortening. - - -|fruit |fruit -|fruit/apple | apple -|fruit/banana | banana -|fruit/cherry | cherry -|water |water -|water/sea | sea -|water/sea/sicily | sicily -|water/sea/archipelago | archipelago -|water/sea/sibuyan | sibuyan -|water/ocean | ocean -|water/ocean/atlantic | atlantic -|water/ocean/pacific | pacific -|water/ocean/arctic | arctic - - - Sometimes, it will be necessary to add mailboxes, that you - don't use, to fill in part of the tree. This will trade - vertical space for horizonal space (but it looks good). - - - - - Limiting the Number of Mailboxes - - If you have a lot of mailboxes, sometimes it can be useful to hide - the ones you aren't using. $sidebar_new_mail_only - tells Sidebar to only show mailboxes that contain new, or flagged, email. - - - If you want some mailboxes to be always visible, then use the - sidebar_whitelist command. It takes a list of - mailboxes as parameters. - - -set sidebar_new_mail_only # Only mailboxes with new/flagged email -sidebar_whitelist fruit fruit/apple # Always display these two mailboxes - - - - - Colors - - Here is a sample color scheme: - - -color sidebar_indicator default color17 # Dark blue background -color sidebar_highlight white color238 # Grey background -color sidebar_spoolfile yellow default # Yellow -color sidebar_new green default # Green -color sidebar_flagged red default # Red -color sidebar_divider color8 default # Dark grey - - - There is a priority order when coloring Sidebar mailboxes. - e.g. If a mailbox has new mail it will have the - sidebar_new color, even if it also contains - flagged mails. - - - Sidebar Color Priority - - - - Priority - Color - Description - - - - - Highest - sidebar_indicator - Mailbox is open - - - - sidebar_highlight - Mailbox is highlighed - - - - sidebar_spoolfile - Mailbox is the spoolfile (receives incoming mail) - - - - sidebar_new - Mailbox contains new mail - - - - sidebar_flagged - Mailbox contains flagged mail - - - Lowest - (None) - Mailbox does not match above - - - -
- - - Bug-fixes - - If you haven't used Sidebar before, you can ignore this section. - - - These bugs have been fixed since the previous Sidebar release: 2015-11-11. - - - Fix bug when starting in compose mode - Fix bug with empty sidebar_divider_char string - Fix bug with header wrapping - Correctly handle utf8 character sequences - Fix a bug in mh_buffy_update - Fix refresh -- time overflowed short - Protect against empty format strings - Limit Sidebar width to COLS - Handle unmailboxes * safely - Refresh Sidebar after timeout - - - - Config Changes - - If you haven't used Sidebar before, you can ignore this section. - - - Some of the Sidebar config has been changed to make its meaning clearer. - These changes have been made since the previous Sidebar release: 2015-11-11. - - - Config Changes - - - - Old Name - New Name - - - - - $sidebar_delim - $sidebar_divider_char - - - $sidebar_folderindent - $sidebar_folder_indent - - - $sidebar_indentstr - $sidebar_indent_string - - - $sidebar_newmail_only - $sidebar_new_mail_only - - - $sidebar_refresh - $sidebar_refresh_time - - - $sidebar_shortpath - $sidebar_short_path - - - $sidebar_sort - $sidebar_sort_method - - - <sidebar-scroll-down> - <sidebar-page-down> - - - <sidebar-scroll-up> - <sidebar-page-up> - - - -
- + Sidebar + + The Sidebar shows a list of all your mailboxes. The list can be + turned on and off, it can be themed and the list style can be + configured. + @@ -8710,466 +8102,290 @@ please have a look at the mixmaster documentation. - Sidebar Patch - Overview of mailboxes - - - Patch - - - To check if Mutt supports Sidebar, look for - +USE_SIDEBAR in the mutt version. - See: . - - - - Dependencies: - mutt-1.5.24 - - - This patch is part of the NeoMutt Project. - - - - Introduction - - - The Sidebar shows a list of all your mailboxes. The list can be - turned on and off, it can be themed and the list style can be - configured. - - - - This part of the manual is a reference guide. - If you want a simple introduction with examples see the - Sidebar Howto. - If you just want to get started, you could use the sample - Sidebar muttrc. - - - - This version of Sidebar is based on Terry Chan's - 2015-11-11 release. - It contains many - new features, - lots of - bugfixes. - - - - - Variables - - - Sidebar Variables - - - - Name - Type - Default - - - - - sidebar_delim_chars - string - /. - - - sidebar_divider_char - string - | - - - sidebar_folder_indent - boolean - no - - - sidebar_format - string - %B%?F? [%F]?%* %?N?%N/?%S - - - sidebar_indent_string - string -    (two spaces) - - - sidebar_new_mail_only - boolean - no - - - sidebar_next_new_wrap - boolean - no - - - sidebar_refresh_time - number - 60 - - - sidebar_short_path - boolean - no - - - sidebar_sort_method - enum - SORT_ORDER - - - sidebar_visible - boolean - no - - - sidebar_whitelist - list - (empty) - - - sidebar_width - number - 20 - - - -
- - - - Functions - - - Sidebar adds the following functions to Mutt. - By default, none of them are bound to keys. - - - - Sidebar Functions - - - - Menus - Function - Description - - - - - index,pager - <sidebar-next> - Move the highlight to next mailbox - - - index,pager - <sidebar-next-new> - Move the highlight to next mailbox with new mail - - - index,pager - <sidebar-open> - Open highlighted mailbox - - - index,pager - <sidebar-page-down> - Scroll the Sidebar down 1 page - - - index,pager - <sidebar-page-up> - Scroll the Sidebar up 1 page - - - index,pager - <sidebar-prev> - Move the highlight to previous mailbox - - - index,pager - <sidebar-prev-new> - Move the highlight to previous mailbox with new mail - - - index,pager - <sidebar-toggle-visible> - Make the Sidebar (in)visible - - - -
- - - - Commands - - sidebar_whitelist - - mailbox - - - mailbox - - - - - - Colors - - - Sidebar Colors - - - - Name - Default Color - Description - - - - - sidebar_divider - default - The dividing line between the Sidebar and the Index/Pager panels - - - sidebar_flagged - default - Mailboxes containing flagged mail - - - sidebar_highlight - underline - Cursor to select a mailbox - - - sidebar_indicator - mutt indicator - The mailbox open in the Index panel - - - sidebar_new - default - Mailboxes containing new mail - - - sidebar_spoolfile - default - Mailbox that receives incoming mail - - - -
- - If the sidebar_indicator color isn't set, then the default Mutt - indicator color will be used (the color used in the index panel). - - - - Sort - - - Sidebar Sort - - - - Sort - Description - - - - - alpha - Alphabetically by path - - - count - Total number of messages - - - flagged - Number of flagged messages - - - name - Alphabetically by path - - - new - Number of new messages - - - path - Alphabetically by path - - - unsorted - Do not resort the paths - - - -
- - - - Muttrc - -# This is a complete list of sidebar-related configuration. - -# -------------------------------------------------------------------------- -# VARIABLES - shown with their default values -# -------------------------------------------------------------------------- - -# Should the Sidebar be shown? -set sidebar_visible = no - -# How wide should the Sidebar be in screen columns? -# Note: Some characters, e.g. Chinese, take up two columns each. -set sidebar_width = 20 - -# Should the mailbox paths be abbreviated? -set sidebar_short_path = no - -# When abbreviating mailbox path names, use any of these characters as path -# separators. Only the part after the last separators will be shown. -# For file folders '/' is good. For IMAP folders, often '.' is useful. -set sidebar_delim_chars = '/.' - -# If the mailbox path is abbreviated, should it be indented? -set sidebar_folder_indent = no - -# Indent mailbox paths with this string. -set sidebar_indent_string = ' ' - -# Make the Sidebar only display mailboxes that contain new, or flagged, -# mail. -set sidebar_new_mail_only = no - -# Any mailboxes that are whitelisted will always be visible, even if the -# sidebar_new_mail_only option is enabled. -sidebar_whitelist '/home/user/mailbox1' -sidebar_whitelist '/home/user/mailbox2' - -# When searching for mailboxes containing new mail, should the search wrap -# around when it reaches the end of the list? -set sidebar_next_new_wrap = no - -# The character to use as the divider between the Sidebar and the other Mutt -# panels. -# Note: Only the first character of this string is used. -set sidebar_divider_char = '|' - -# Display the Sidebar mailboxes using this format string. -set sidebar_format = '%B%?F? [%F]?%* %?N?%N/?%S' - -# Sidebar will not refresh its list of mailboxes any more frequently than -# this number of seconds. This will help reduce disk/network traffic. -set sidebar_refresh_time = 60 - -# Sort the mailboxes in the Sidebar using this method: -# count - total number of messages -# flagged - number of flagged messages -# new - number of new messages -# path - mailbox path -# unsorted - do not sort the mailboxes -set sidebar_sort_method = 'unsorted' - -# -------------------------------------------------------------------------- -# FUNCTIONS - shown with an example mapping -# -------------------------------------------------------------------------- - -# Move the highlight to the previous mailbox -bind index,pager \Cp sidebar-prev - -# Move the highlight to the next mailbox -bind index,pager \Cn sidebar-next - -# Open the highlighted mailbox -bind index,pager \Co sidebar-open - -# Move the highlight to the previous page -# This is useful if you have a LOT of mailboxes. -bind index,pager <F3> sidebar-page-up - -# Move the highlight to the next page -# This is useful if you have a LOT of mailboxes. -bind index,pager <F4> sidebar-page-down - -# Move the highlight to the previous mailbox containing new, or flagged, -# mail. -bind index,pager <F5> sidebar-prev-new - -# Move the highlight to the next mailbox containing new, or flagged, mail. -bind index,pager <F6> sidebar-next-new - -# Toggle the visibility of the Sidebar. -bind index,pager B sidebar-toggle-visible - -# -------------------------------------------------------------------------- -# COLORS - some unpleasant examples are given -# -------------------------------------------------------------------------- -# Note: All color operations are of the form: -# color OBJECT FOREGROUND BACKGROUND - -# Color of the current, open, mailbox -# Note: This is a general Mutt option which colors all selected items. -color indicator cyan black - -# Color of the highlighted, but not open, mailbox. -color sidebar_highlight black color8 - -# Color of the divider separating the Sidebar from Mutt panels -color sidebar_divider color8 black - -# Color to give mailboxes containing flagged mail -color sidebar_flagged red black - -# Color to give mailboxes containing new mail -color sidebar_new green black - -# -------------------------------------------------------------------------- - -# vim: syntax=muttrc - - - - - See Also - - - Regular Expressions - Patterns - Color command - notmuch patch - - - - - Known Bugs - Unsorted isn't - - - - Credits - - Justin Hibbits jrh29@po.cwru.edu - Thomer M. Gil mutt@thomer.com - David Sterba dsterba@suse.cz - Evgeni Golov evgeni@debian.org - Fabian Groffen grobian@gentoo.org - Jason DeTiberus jdetiber@redhat.com - Stefan Assmann sassmann@kpanic.de - Steve Kemp steve@steve.org.uk - Terry Chan tchan@lunar-linux.org - Tyler Earnest tylere@rne.st - Richard Russon rich@flatcap.org - - + Sidebar + Overview of mailboxes + + + Introduction + + + The Sidebar shows a list of all your mailboxes. The list can be + turned on and off, it can be themed and the list style can be + configured. + + + + + Variables + + + Sidebar Variables + + + + Name + Type + Default + + + + + sidebar_delim_chars + string + /. + + + sidebar_divider_char + string + | + + + sidebar_folder_indent + boolean + no + + + sidebar_format + string + %B%?F? [%F]?%* %?N?%N/?%S + + + sidebar_indent_string + string +    (two spaces) + + + sidebar_new_mail_only + boolean + no + + + sidebar_next_new_wrap + boolean + no + + + sidebar_refresh_time + number + 60 + + + sidebar_short_path + boolean + no + + + sidebar_sort_method + enum + SORT_ORDER + + + sidebar_visible + boolean + no + + + sidebar_whitelist + list + (empty) + + + sidebar_width + number + 20 + + + +
+ + + + Functions + + + Sidebar adds the following functions to Mutt. + By default, none of them are bound to keys. + + + + Sidebar Functions + + + + Menus + Function + Description + + + + + index,pager + <sidebar-next> + Move the highlight to next mailbox + + + index,pager + <sidebar-next-new> + Move the highlight to next mailbox with new mail + + + index,pager + <sidebar-open> + Open highlighted mailbox + + + index,pager + <sidebar-page-down> + Scroll the Sidebar down 1 page + + + index,pager + <sidebar-page-up> + Scroll the Sidebar up 1 page + + + index,pager + <sidebar-prev> + Move the highlight to previous mailbox + + + index,pager + <sidebar-prev-new> + Move the highlight to previous mailbox with new mail + + + index,pager + <sidebar-toggle-visible> + Make the Sidebar (in)visible + + + +
+ + + + Commands + + sidebar_whitelist + + mailbox + + + mailbox + + + + + + Colors + + + Sidebar Colors + + + + Name + Default Color + Description + + + + + sidebar_divider + default + The dividing line between the Sidebar and the Index/Pager panels + + + sidebar_flagged + default + Mailboxes containing flagged mail + + + sidebar_highlight + underline + Cursor to select a mailbox + + + sidebar_indicator + mutt indicator + The mailbox open in the Index panel + + + sidebar_new + default + Mailboxes containing new mail + + + sidebar_spoolfile + default + Mailbox that receives incoming mail + + + +
+ + + If the sidebar_indicator color isn't set, then the default Mutt + indicator color will be used (the color used in the index panel). + + + + + Sort + + + Sidebar Sort + + + + Sort + Description + + + + + alpha + Alphabetically by path + + + count + Total number of messages + + + flagged + Number of flagged messages + + + name + Alphabetically by path + + + new + Number of new messages + + + path + Alphabetically by path + + + unsorted + Do not resort the paths + + + +
+ + + + + See Also + + + Regular Expressions + Patterns + Color command + + @@ -10328,7 +9544,7 @@ The following are the commands understood by Mutt: -sidebar_whitelist +sidebar_whitelist item diff --git a/init.h b/init.h index b101582ee..66df8d204 100644 --- a/init.h +++ b/init.h @@ -2685,6 +2685,7 @@ struct option_t MuttVars[] = { ** .ts ** set sidebar_delim_chars='/' ** .te + ** .pp ** IMAP mailboxes are often named: `folder1.folder2.mailbox'. ** .ts ** set sidebar_delim_chars='.'