NOTE: this patch does NOT make any code changes.
It simply adds comment blocks.
Fully document all the sidebar config options.
Add comment-blocks describing each function -- what it does, the
parameters it takes, the return values. These can be used by
doxygen.
}
}
+/**
+ * buffy_compare_name - qsort callback to sort BUFFYs
+ * @a: First BUFFY to compare
+ * @b: Second BUFFY to compare
+ *
+ * Compare the paths of two BUFFYs taking the locale into account.
+ *
+ * Returns:
+ * -1: a precedes b
+ * 0: a and b are identical
+ * 1: b precedes a
+ */
static int
buffy_compare_name (const void *a, const void *b)
{
return mutt_strcoll (b1->path, b2->path);
}
+/**
+ * buffy_sort - Sort a linked list of BUFFYs
+ * @b: BUFFY at the head of the list to be sorted
+ *
+ * Take a linked list of BUFFYs and sort them by their paths according to the
+ * locale. Once sorted, the prev/next links are restored.
+ *
+ * If the config option "sidebar_sort" isn't set, then the BUFFY is returned
+ * unchanged.
+ *
+ * Returns:
+ * BUFFY at the head of the sorted list
+ */
static BUFFY *
buffy_sort (BUFFY *b)
{
return 0;
}
-/* update message counts for the sidebar */
+/**
+ * buffy_maildir_update - Update messages counts for a maildir mailbox
+ * @mailbox: BUFFY representing a maildir mailbox
+ *
+ * Open a mailbox directories and update our record of how many new, or
+ * flagged, messages there are.
+ */
void
buffy_maildir_update (BUFFY *mailbox)
{
return rc;
}
-/* update message counts for the sidebar */
+/**
+ * buffy_mbox_update - Update messages counts for an mbox mailbox
+ * @mailbox: BUFFY representing an mbox mailbox
+ * @sb: stat(2) infomation about the mailbox file
+ *
+ * Open a mbox file and update our record of how many new, or flagged,
+ * messages there are. If the mailbox hasn't changed since the last call,
+ * the function does nothing.
+ */
void
buffy_mbox_update (BUFFY *mailbox, struct stat *sb)
{
** Command to use when spawning a subshell. By default, the user's login
** shell from \fC/etc/passwd\fP is used.
*/
-
- {"sidebar_delim", DT_STR, R_BOTH, UL &SidebarDelim, UL "|"},
+ { "sidebar_delim", DT_STR, R_BOTH, UL &SidebarDelim, UL "|" },
/*
** .pp
- ** This specifies the delimiter between the sidebar (if visible) and
- ** other screens.
+ ** This specifies the character to be drawn between the sidebar (when
+ ** visible) and the other Mutt panels. ASCII and Unicode line-drawing
+ ** characters are supported.
+ ** .pp
+ ** \fBNote:\fP Only the first character of sidebar_delim is used.
*/
- { "sidebar_delim_chars", DT_STR, R_NONE, UL &SidebarDelimChars, UL "/." },
+ { "sidebar_delim_chars", DT_STR, R_NONE, UL &SidebarDelimChars, UL "/." },
/*
** .pp
** This contains the list of characters which you would like to treat
- ** as folder separators for displaying paths in the sidebar. If
- ** you're not using IMAP folders, you probably prefer setting this to "/"
- ** alone.
+ ** as folder separators for displaying paths in the sidebar.
+ ** .pp
+ ** Local mail is often arranged in directories: `dir1/dir2/mailbox'.
+ ** .ts
+ ** set sidebar_delim_chars='/'
+ ** .te
+ ** IMAP mailboxes are often named: `folder1.folder2.mailbox'.
+ ** .ts
+ ** set sidebar_delim_chars='.'
+ ** .te
+ ** .pp
+ ** \fBSee also:\fP $$sidebar_shortpath, $$sidebar_folderindent, $$sidebar_indentstr.
*/
{ "sidebar_folderindent", DT_BOOL, R_BOTH, OPTSIDEBARFOLDERINDENT, 0 },
/*
** .pp
- ** Should folders be indented in the sidebar.
+ ** Set this to indent mailboxes in the sidebar.
+ ** .pp
+ ** \fBSee also:\fP $$sidebar_shortpath, $$sidebar_indentstr, $$sidebar_delim_chars.
*/
- {"sidebar_format", DT_STR, R_NONE, UL &SidebarFormat, UL "%B%?F? [%F]?%* %?N?%N/?%S"},
+ { "sidebar_format", DT_STR, R_NONE, UL &SidebarFormat, UL "%B%?F? [%F]?%* %?N?%N/?%S" },
/*
** .pp
- ** Format string for the sidebar. The sequences `%N', `%F' and `%S'
- ** will be replaced by the number of new or flagged messages or the total
- ** size of them mailbox. `%B' will be replaced with the name of the mailbox.
- ** The `%!' sequence will be expanded to `!' if there is one flagged message;
- ** to `!!' if there are two flagged messages; and to `n!' for n flagged
- ** messages, n>2.
+ ** This variable allows you to customize the sidebar display. This string is
+ ** similar to $$index_format, but has its own set of \fCprintf(3)\fP-like
+ ** sequences:
+ ** .dl
+ ** .dt %B .dd Name of the mailbox
+ ** .dt %S .dd Size of mailbox (total number of messages)
+ ** .dt %N .dd Number of New messages in the mailbox
+ ** .dt %F .dd Number of Flagged messages in the mailbox
+ ** .dt %! .dd `!' : one flagged message; `!!' : two flagged messages; `n!' :
+ ** n flagged messages (for n > 2).
+ ** .de
*/
- {"sidebar_indentstr", DT_STR, R_BOTH, UL &SidebarIndentStr, UL " "},
+ { "sidebar_indentstr", DT_STR, R_BOTH, UL &SidebarIndentStr, UL " " },
/*
** .pp
- ** This specifies the string that is used to indent items
- ** with sidebar_folderindent= yes
+ ** This specifies the string that is used to indent mailboxes in the sidebar.
+ ** It defaults to two spaces.
+ ** .pp
+ ** \fBSee also:\fP $$sidebar_shortpath, $$sidebar_folderindent, $$sidebar_delim_chars.
*/
- {"sidebar_newmail_only", DT_BOOL, R_BOTH, OPTSIDEBARNEWMAILONLY, 0 },
+ { "sidebar_newmail_only", DT_BOOL, R_BOTH, OPTSIDEBARNEWMAILONLY, 0 },
/*
** .pp
- ** Show only new and flagged mail in the sidebar.
+ ** When set, the sidebar will only display mailboxes containing new, or
+ ** flagged, mail.
+ ** .pp
+ ** \fBSee also:\fP $sidebar_whitelist.
*/
{ "sidebar_next_new_wrap", DT_BOOL, R_BOTH, UL OPTSIDEBARNEXTNEWWRAP, 0 },
/*
** .pp
- ** Setting sidebar_next_new_wrap=yes causes mutt to wrap around the list
- ** of mailboxes when using Next/Previous New Mailbox commands.
+ ** When set, the \fC<sidebar-next-new>\fP command will not stop and the end of
+ ** the list of mailboxes, but wrap around to the beginning. The
+ ** \fC<sidebar-prev-new>\fP command is similarly affected, wrapping around to
+ ** the end of the list.
*/
{ "sidebar_refresh", DT_NUM, R_BOTH, UL &SidebarRefresh, 60 },
/*
** .pp
- ** Do not refresh sidebar in less than $sidebar_refresh seconds,
- ** (0 disables refreshing).
+ ** Set sidebar_refresh to the minimum number of seconds between refreshes.
+ ** This will reduced network traffic.
+ ** .pp
+ ** \fBNote:\fP Set to 0 to disable refreshing.
*/
{ "sidebar_shortpath", DT_BOOL, R_BOTH, OPTSIDEBARSHORTPATH, 0 },
/*
** .pp
- ** Should the sidebar shorten the path showed.
+ ** By default the sidebar will show the mailbox's path, relative to the
+ ** $$folder variable. Setting \fCsidebar_shortpath=yes\fP will shorten the
+ ** names relative to the previous name. Here's an example:
+ ** .dl
+ ** .dt \fBshortpath=no\fP .dd \fBshortpath=yes\fP .dd \fBshortpath=yes, folderindent=yes, indentstr=".."\fP
+ ** .dt \fCfruit\fP .dd \fCfruit\fP .dd \fCfruit\fP
+ ** .dt \fCfruit.apple\fP .dd \fCapple\fP .dd \fC..apple\fP
+ ** .dt \fCfruit.banana\fP .dd \fCbanana\fP .dd \fC..banana\fP
+ ** .dt \fCfruit.cherry\fP .dd \fCcherry\fP .dd \fC..cherry\fP
+ ** .de
+ ** .pp
+ ** \fBSee also:\fP $$sidebar_delim_chars, $$sidebar_folderindent, $$sidebar_indentstr.
*/
{ "sidebar_sort", DT_BOOL, R_BOTH, OPTSIDEBARSORT, 0 },
/*
** .pp
- ** This specifies whether or not to sort the sidebar alphabetically.
+ ** This specifies whether or not to sort the sidebar mailboxes alphabetically.
+ ** .pp
+ ** \fBNote:\fP This config option must come before the mailboxes config.
*/
{ "sidebar_visible", DT_BOOL, R_BOTH, OPTSIDEBAR, 0 },
/*
** .pp
- ** This specifies whether or not to show sidebar (left-side list of folders).
+ ** This specifies whether or not to show sidebar. The sidebar shows a list of
+ ** all your mailboxes.
+ ** .pp
+ ** \fBSee also:\fP $$sidebar_format, $$sidebar_width
*/
{ "sidebar_width", DT_NUM, R_BOTH, UL &SidebarWidth, 0 },
/*
** .pp
- ** The width of the sidebar.
+ ** This controls the width of the sidebar. It is measured in screen columns.
+ ** For example: sidebar_width=20 could display 20 ASCII characters, or 10
+ ** Chinese characters.
*/
-
{ "sig_dashes", DT_BOOL, R_NONE, OPTSIGDASHES, 1 },
/*
** .pp
mhs_free_sequences (&mhs);
}
+/**
+ * mh_buffy_update - Update messages counts for an mh mailbox
+ * @path: Pathname of the mailbox
+ * @msg_count: Out: total number of messages
+ * @msg_unread: Out: number of unread messages
+ * @msg_flagged: Out: number of flagged messages
+ * @sb_last_checked: Out: timestamp the mailbox was last checked (NOW)
+ *
+ * Read through an mh mailbox and count messages. Save the number of new,
+ * flagged messages and a timestamp for now.
+ */
void
mh_buffy_update (const char *path, int *msgcount, int *msg_unread, int *msg_flagged, time_t *sb_last_checked)
{
static BUFFY *BottomBuffy;
static int known_lines;
+/**
+ * struct sidebar_entry - Info about folders in the sidebar
+ *
+ * Used in the mutt_FormatString callback
+ */
struct sidebar_entry {
char box[SHORT_STRING];
unsigned int size;
unsigned int flagged;
};
+
+/**
+ * find_next_new - Find the next folder that contains new mail
+ * @wrap: Wrap around to the beginning if the end is reached
+ *
+ * Search down the list of mail folders for one containing new, or flagged,
+ * mail, or a folder that is in the SidebarWhitelist.
+ *
+ * Returns:
+ * BUFFY*: Success
+ * NULL: Failure
+ */
static BUFFY *
find_next_new (int wrap)
{
return NULL;
}
+/**
+ * find_prev_new - Find the previous folder that contains new mail
+ * @wrap: Wrap around to the beginning if the end is reached
+ *
+ * Search up the list of mail folders for one containing new, or flagged, mail,
+ * or a folder that is in the SidebarWhitelist.
+ *
+ * Returns:
+ * BUFFY*: Success
+ * NULL: Failure
+ */
static BUFFY *
find_prev_new (int wrap)
{
return NULL;
}
-
+/**
+ * calc_boundaries - Keep our TopBuffy/BottomBuffy up-to-date
+ *
+ * Whenever the sidebar's view of the BUFFYs changes, or the screen changes
+ * size, we should check TopBuffy and BottomBuffy still have the correct
+ * values.
+ *
+ * Ideally, this should happen in the core of mutt.
+ */
static void
calc_boundaries (void)
{
}
}
+/**
+ * cb_format_str - Create the string to show in the sidebar
+ * @dest: Buffer in which to save string
+ * @destlen: Buffer length
+ * @col: Starting column, UNUSED
+ * @op: printf-like operator, e.g. 'B'
+ * @src: printf-like format string
+ * @prefix: Field formatting string, UNUSED
+ * @ifstring: If condition is met, display this string
+ * @elsestring: Otherwise, display this string
+ * @data: Pointer to our sidebar_entry
+ * @flags: Format flags, e.g. M_FORMAT_OPTIONAL
+ *
+ * cb_format_str is a callback function for mutt_FormatString. It understands
+ * five operators. '%B' : Mailbox name, '%F' : Number of flagged messages,
+ * '%N' : Number of new messages, '%S' : Size (total number of messages),
+ * '%!' : Icon denoting number of flagged messages.
+ *
+ * Returns: src (unchanged)
+ */
static const char *
cb_format_str (char *dest, size_t destlen, size_t col, char op, const char *src,
const char *prefix, const char *ifstring, const char *elsestring,
return src;
}
+/**
+ * make_sidebar_entry - Turn mailbox data into a sidebar string
+ * @buf: Buffer in which to save string
+ * @buflen: Buffer length
+ * @width: Desired width in screen cells
+ * @box: Mailbox name
+ * @size: Size (total number of messages)
+ * @new: Number of new messages
+ * @flagged: Number of flagged messages
+ *
+ * Take all the relevant mailbox data and the desired screen width and then get
+ * mutt_FormatString to do the actual work. mutt_FormatString will callback to
+ * us using cb_format_str() for the sidebar specific formatting characters.
+ */
static void
make_sidebar_entry (char *buf, unsigned int buflen, int width, char *box,
unsigned int size, unsigned int new, unsigned int flagged)
}
+/**
+ * sb_draw - Completely redraw the sidebar
+ *
+ * Completely refresh the sidebar region. First draw the divider; then, for
+ * each BUFFY, call make_sidebar_entry; finally blank out any remaining space.
+ */
void
sb_draw (void)
{
}
}
+/**
+ * sb_should_refresh - Check if the sidebar is due to be refreshed
+ *
+ * The "sidebar_refresh" config option allows the user to limit the frequency
+ * with which the sidebar is refreshed.
+ *
+ * Returns:
+ * 1 Yes, refresh is due
+ * 0 No, refresh happened recently
+ */
int
sb_should_refresh (void)
{
return 0;
}
+/**
+ * sb_change_mailbox - Change the selected mailbox
+ * @op: Operation code
+ *
+ * Change the selected mailbox, e.g. "Next mailbox", "Previous Mailbox
+ * with new mail". The operations are listed OPS.SIDEBAR which is built
+ * into an enum in keymap_defs.h.
+ *
+ * If the operation is successful, CurBuffy will be set to the new mailbox.
+ * This function only *selects* the mailbox, doesn't *open* it.
+ *
+ * Allowed values are: OP_SIDEBAR_NEXT, OP_SIDEBAR_NEXT_NEW, OP_SIDEBAR_PREV,
+ * OP_SIDEBAR_PREV_NEW, OP_SIDEBAR_SCROLL_DOWN, OP_SIDEBAR_SCROLL_UP.
+ */
void
sb_change_mailbox (int op)
{
CurBuffy = CurBuffy->next;
break;
}
+ /* drop through */
case OP_SIDEBAR_NEXT_NEW:
b = find_next_new (option (OPTSIDEBARNEXTNEWWRAP));
if (!b) {
CurBuffy = CurBuffy->prev;
break;
}
+ /* drop through */
case OP_SIDEBAR_PREV_NEW:
b = find_prev_new (option (OPTSIDEBARNEXTNEWWRAP));
if (!b) {
sb_draw();
}
+/**
+ * sb_set_buffystats - Update the BUFFY's message counts from the CONTEXT
+ * @ctx: A mailbox CONTEXT
+ *
+ * Given a mailbox CONTEXT, find a matching mailbox BUFFY and copy the message
+ * counts into it.
+ */
void
sb_set_buffystats (const CONTEXT *ctx)
{
}
}
+/**
+ * sb_set_open_buffy - Set the CurBuffy based on a mailbox path
+ * @path: Mailbox path
+ *
+ * Search through the list of mailboxes. If a BUFFY has a matching path, set
+ * CurBuffy to it.
+ */
void
sb_set_open_buffy (char *path)
{
+ /* Even if the sidebar is hidden */
+
BUFFY *b = CurBuffy = Incoming;
if (!path || !b)
}
}
+/**
+ * sb_set_update_time - Note the time that the sidebar was updated
+ *
+ * Update the timestamp representing the last sidebar update. If the user
+ * configures "sidebar_refresh", this will help to reduce traffic.
+ */
void
sb_set_update_time (void)
{
+ /* XXX - should this be public? */
+
SidebarLastRefresh = time (NULL);
}
projects / neomutt / commitdiff