Generate the help-line and help-page and GUI display them. More...

#include "config.h"
#include <stddef.h>
#include <limits.h>
#include <stdbool.h>
#include <stdio.h>
#include <string.h>
#include <wchar.h>
#include "mutt/mutt.h"
#include "curs_lib.h"
#include "globals.h"
#include "keymap.h"
#include "mutt_window.h"
#include "muttlib.h"
#include "opcodes.h"
#include "pager.h"

Macros
#define	DEFINE_HELP_MESSAGE(opcode, help_string) help_string,

Functions
static const struct Binding *	help_lookup_function (int op, int menu)
	Find a keybinding for an operation. More...

void	mutt_make_help (char buf, size_t buflen, const char txt, int menu, int op)
	Create one entry for the help bar. More...

char *	mutt_compile_help (char buf, size_t buflen, int menu, const struct Mapping items)
	Create the text for the help menu. More...

static int	print_macro (FILE fp, int maxwidth, const char *macro)
	Print a macro string to a file. More...

static int	get_wrapped_width (const char *t, size_t wid)
	Wrap a string at a sensible place. More...

static int	pad (FILE *fp, int col, int i)
	Write some padding to a file. More...

static void	format_line (FILE fp, int ismacro, const char t1, const char t2, const char t3)
	Write a formatted line to a file. More...

static void	dump_menu (FILE *fp, int menu)
	Write all the key bindings to a file. More...

static bool	is_bound (struct Keymap *map, int op)
	Does a function have a keybinding? More...

static void	dump_unbound (FILE fp, const struct Binding funcs, struct Keymap map, struct Keymap aux)
	Write out all the operations with no key bindings. More...

void	mutt_help (int menu)
	Display the help menu. More...

Variables
static const char *	HelpStrings []

Detailed Description

Generate the help-line and help-page and GUI display them.

Authors

Michael R. Elkins

Copyright: This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.

Definition in file help.c.

Macro Definition Documentation

#define DEFINE_HELP_MESSAGE	(	opcode,
		help_string
	)	help_string,

Function Documentation

static const struct Binding* help_lookup_function	(	int	op,
		int	menu
	)

static

Find a keybinding for an operation.

Parameters

op	Operation, e.g. OP_DELETE
menu	Current Menu

Return values

ptr	Key binding
NULL	If none

Definition at line 59 of file help.c.

 {
   const struct Binding *map = NULL;
 
   if (menu != MENU_PAGER)
   {
     /* first look in the generic map for the function */
     for (int i = 0; OpGeneric[i].name; i++)
       if (OpGeneric[i].op == op)
         return &OpGeneric[i];
   }
 
   map = km_get_table(menu);
   if (map)
   {
     for (int i = 0; map[i].name; i++)
       if (map[i].op == op)
         return &map[i];
   }
 
   return NULL;
 }

void mutt_make_help	(	char *	buf,
		size_t	buflen,
		const char *	txt,
		int	menu,
		int	op
	)

Create one entry for the help bar.

Parameters

buf	Buffer for the result
buflen	Length of buffer
txt	Text part, e.g. "delete"
menu	Current Menu
op	Operation, e.g. OP_DELETE

This will return something like: "d:delete"

Definition at line 92 of file help.c.

 {
   char tmp[128];
 
   if (km_expand_key(tmp, sizeof(tmp), km_find_func(menu, op)) ||
       km_expand_key(tmp, sizeof(tmp), km_find_func(MENU_GENERIC, op)))
   {
     snprintf(buf, buflen, "%s:%s", tmp, txt);
   }
   else
   {
     buf[0] = '\0';
   }
 }

char* mutt_compile_help	(	char *	buf,
		size_t	buflen,
		int	menu,
		const struct Mapping *	items
	)

Create the text for the help menu.

Parameters

buf	Buffer for the result
buflen	Length of buffer
menu	Current Menu
items	Map of functions to display in the help bar

Return values

ptr	Buffer containing result

Definition at line 115 of file help.c.

 {
   char *pbuf = buf;
 
   for (int i = 0; items[i].name && buflen > 2; i++)
   {
     if (i)
     {
       *pbuf++ = ' ';
       *pbuf++ = ' ';
       buflen -= 2;
     }
     mutt_make_help(pbuf, buflen, _(items[i].name), menu, items[i].value);
     const size_t len = mutt_str_strlen(pbuf);
     pbuf += len;
     buflen -= len;
   }
   return buf;
 }

static int print_macro	(	FILE *	fp,
		int	maxwidth,
		const char **	macro
	)

static

Print a macro string to a file.

Parameters

[in]	fp	File to write to
[in]	maxwidth	Maximum width in screen columns
[out]	macro	Macro string

Return values

num	Number of screen columns used

The macro pointer is move past the string we've printed

Definition at line 144 of file help.c.

 {
   int n = maxwidth;
   wchar_t wc;
   size_t k;
   size_t len = mutt_str_strlen(*macro);
   mbstate_t mbstate1, mbstate2;
 
   memset(&mbstate1, 0, sizeof(mbstate1));
   memset(&mbstate2, 0, sizeof(mbstate2));
   for (; len && (k = mbrtowc(&wc, *macro, len, &mbstate1)); *macro += k, len -= k)
   {
     if ((k == (size_t)(-1)) || (k == (size_t)(-2)))
     {
       if (k == (size_t)(-1))
         memset(&mbstate1, 0, sizeof(mbstate1));
       k = (k == (size_t)(-1)) ? 1 : len;
       wc = ReplacementChar;
     }
     /* glibc-2.1.3's wcwidth() returns 1 for unprintable chars! */
     const int w = wcwidth(wc);
     if (IsWPrint(wc) && (w >= 0))
     {
       if (w > n)
         break;
       n -= w;
       {
         char buf[MB_LEN_MAX * 2];
         size_t n1, n2;
         if (((n1 = wcrtomb(buf, wc, &mbstate2)) != (size_t)(-1)) &&
             ((n2 = wcrtomb(buf + n1, 0, &mbstate2)) != (size_t)(-1)))
         {
           fputs(buf, fp);
         }
       }
     }
     else if ((wc < 0x20) || (wc == 0x7f))
     {
       if (n < 2)
         break;
       n -= 2;
       if (wc == '\033') // Escape
         fprintf(fp, "\\e");
       else if (wc == '\n')
         fprintf(fp, "\\n");
       else if (wc == '\r')
         fprintf(fp, "\\r");
       else if (wc == '\t')
         fprintf(fp, "\\t");
       else
         fprintf(fp, "^%c", (char) ((wc + '@') & 0x7f));
     }
     else
     {
       if (n < 1)
         break;
       n -= 1;
       fprintf(fp, "?");
     }
   }
   return maxwidth - n;
 }

static int get_wrapped_width	(	const char *	t,
		size_t	wid
	)

static

Wrap a string at a sensible place.

Parameters

t	String to wrap
wid	Maximum width

Return values

num	Break after this many characters

If the string's too long, look for some whitespace to break at.

Definition at line 215 of file help.c.

 {
   wchar_t wc;
   size_t k;
   size_t m, n;
   size_t len = mutt_str_strlen(t);
   const char *s = t;
   mbstate_t mbstate;
 
   memset(&mbstate, 0, sizeof(mbstate));
   for (m = wid, n = 0; len && (k = mbrtowc(&wc, s, len, &mbstate)) && (n <= wid);
        s += k, len -= k)
   {
     if (*s == ' ')
       m = n;
     if ((k == (size_t)(-1)) || (k == (size_t)(-2)))
     {
       if (k == (size_t)(-1))
         memset(&mbstate, 0, sizeof(mbstate));
       k = (k == (size_t)(-1)) ? 1 : len;
       wc = ReplacementChar;
     }
     if (!IsWPrint(wc))
       wc = '?';
     n += wcwidth(wc);
   }
   if (n > wid)
     n = m;
   else
     n = wid;
   return n;
 }

static int pad	(	FILE *	fp,
		int	col,
		int	i
	)

static

Write some padding to a file.

Parameters

fp	File to write to
col	Current screen column
i	Screen column to pad until

Return values

num	`i` - Padding was added
num	`col` - Content was already wider than col

Definition at line 256 of file help.c.

 {
   if (col < i)
   {
     char fmt[32] = { 0 };
     snprintf(fmt, sizeof(fmt), "%%-%ds", i - col);
     fprintf(fp, fmt, "");
     return i;
   }
   fputc(' ', fp);
   return col + 1;
 }

static void format_line	(	FILE *	fp,
		int	ismacro,
		const char *	t1,
		const char *	t2,
		const char *	t3
	)

static

Write a formatted line to a file.

Parameters

fp	File to write to
ismacro	Layout mode, see below
t1	Text part 1
t2	Text part 2
t3	Text part 3

Assemble the three columns of text.

ismacro can be:

1 : Macro with a description
0 : Non-macro
-1 : Macro with no description

Definition at line 284 of file help.c.

 {
   int col;
   int col_b;
 
   fputs(t1, fp);
 
   /* don't try to press string into one line with less than 40 characters. */
   bool split = (MuttIndexWindow->cols < 40);
   if (split)
   {
     col = 0;
     col_b = 1024;
     fputc('\n', fp);
   }
   else
   {
     const int col_a =
         (MuttIndexWindow->cols > 83) ? (MuttIndexWindow->cols - 32) >> 2 : 12;
     col_b = (MuttIndexWindow->cols > 49) ? (MuttIndexWindow->cols - 10) >> 1 : 19;
     col = pad(fp, mutt_strwidth(t1), col_a);
   }
 
   if (ismacro > 0)
   {
     if (mutt_str_strcmp(C_Pager, "builtin") == 0)
       fputs("_\010", fp); // Ctrl-H (backspace)
     fputs("M ", fp);
     col += 2;
 
     if (!split)
     {
       col += print_macro(fp, col_b - col - 4, &t2);
       if (mutt_strwidth(t2) > col_b - col)
         t2 = "...";
     }
   }
 
   col += print_macro(fp, col_b - col - 1, &t2);
   if (split)
     fputc('\n', fp);
   else
     col = pad(fp, col, col_b);
 
   if (split)
   {
     print_macro(fp, 1024, &t3);
     fputc('\n', fp);
   }
   else
   {
     while (*t3)
     {
       int n = MuttIndexWindow->cols - col;
 
       if (ismacro >= 0)
       {
         SKIPWS(t3);
         n = get_wrapped_width(t3, n);
       }
 
       n = print_macro(fp, n, &t3);
 
       if (*t3)
       {
         if (mutt_str_strcmp(C_Pager, "builtin") != 0)
         {
           fputc('\n', fp);
           n = 0;
         }
         else
         {
           n += col - MuttIndexWindow->cols;
           if (C_Markers)
             n++;
         }
         col = pad(fp, n, col_b);
       }
     }
   }
 
   fputc('\n', fp);
 }

static void dump_menu	(	FILE *	fp,
		int	menu
	)

static

Write all the key bindings to a file.

Parameters

fp	File to write to
menu	Current Menu

Definition at line 373 of file help.c.

 {
   struct Keymap *map = NULL;
   const struct Binding *b = NULL;
   char buf[128];
 
   /* browse through the keymap table */
   for (map = Keymaps[menu]; map; map = map->next)
   {
     if (map->op != OP_NULL)
     {
       km_expand_key(buf, sizeof(buf), map);
 
       if (map->op == OP_MACRO)
       {
         if (map->desc)
           format_line(fp, 1, buf, map->macro, map->desc);
         else
           format_line(fp, -1, buf, "macro", map->macro);
       }
       else
       {
         b = help_lookup_function(map->op, menu);
         format_line(fp, 0, buf, b ? b->name : "UNKNOWN",
                     b ? _(HelpStrings[b->op]) : _("ERROR: please report this bug"));
       }
     }
   }
 }

static bool is_bound	(	struct Keymap *	map,
		int	op
	)

static

Does a function have a keybinding?

Parameters

map	Keymap to examine
op	Operation, e.g. OP_DELETE

Return values

true	If a key is bound to that operation

Definition at line 409 of file help.c.

 {
   for (; map; map = map->next)
     if (map->op == op)
       return true;
   return false;
 }

static void dump_unbound	(	FILE *	fp,
		const struct Binding *	funcs,
		struct Keymap *	map,
		struct Keymap *	aux
	)

static

Write out all the operations with no key bindings.

Parameters

fp	File to write to
funcs	All the bindings for the current menu
map	First key map to consider
aux	Second key map to consider

Definition at line 424 of file help.c.

 {
   for (int i = 0; funcs[i].name; i++)
   {
     if (!is_bound(map, funcs[i].op) && (!aux || !is_bound(aux, funcs[i].op)))
       format_line(fp, 0, funcs[i].name, "", _(HelpStrings[funcs[i].op]));
   }
 }

void mutt_help ( int menu )

Display the help menu.

Parameters

menu	Current Menu

Definition at line 438 of file help.c.

 {
   char t[PATH_MAX];
   char buf[128];
   FILE *fp = NULL;
 
   mutt_mktemp(t, sizeof(t));
 
   const struct Binding *funcs = km_get_table(menu);
   const char *desc = mutt_map_get_name(menu, Menus);
   if (!desc)
     desc = _("<UNKNOWN>");
 
   do
   {
     fp = mutt_file_fopen(t, "w");
     if (!fp)
     {
       mutt_perror(t);
       return;
     }
 
     dump_menu(fp, menu);
     if ((menu != MENU_EDITOR) && (menu != MENU_PAGER))
     {
       fprintf(fp, "\n%s\n\n", _("Generic bindings:"));
       dump_menu(fp, MENU_GENERIC);
     }
 
     fprintf(fp, "\n%s\n\n", _("Unbound functions:"));
     if (funcs)
       dump_unbound(fp, funcs, Keymaps[menu], NULL);
     if (menu != MENU_PAGER)
       dump_unbound(fp, OpGeneric, Keymaps[MENU_GENERIC], Keymaps[menu]);
 
     mutt_file_fclose(&fp);
 
     snprintf(buf, sizeof(buf), _("Help for %s"), desc);
   } while (mutt_do_pager(buf, t, MUTT_PAGER_RETWINCH | MUTT_PAGER_MARKER | MUTT_PAGER_NSKIP | MUTT_PAGER_NOWRAP,
                          NULL) == OP_REFORMAT_WINCH);
 }

Variable Documentation

const char* HelpStrings[]

static

Initial value:

= {
#define DEFINE_HELP_MESSAGE(opcode, help_string) 
      NULL,
}

Definition at line 45 of file help.c.

Macros

Functions

Variables

Detailed Description

Macro Definition Documentation

Function Documentation

Variable Documentation