help.c File Reference

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/lib.h"
#include "gui/lib.h"
#include "mutt.h"
#include "functions.h"
#include "keymap.h"
#include "mutt_globals.h"
#include "muttlib.h"
#include "opcodes.h"
#include "pager.h"
#include "protos.h"

Include dependency graph for help.c:

Go to the source code of this file.

Functions
static const struct Binding *	help_lookup_function (int op, enum MenuType menu)
	Find a keybinding for an operation. More...
void	mutt_make_help (char *buf, size_t buflen, const char *txt, enum MenuType menu, int op)
	Create one entry for the help bar. More...
char *	mutt_compile_help (char *buf, size_t buflen, enum MenuType 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, int wraplen)
	Write a formatted line to a file. More...
static void	dump_menu (FILE *fp, enum MenuType menu, int wraplen)
	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, int wraplen)
	Write out all the operations with no key bindings. More...
void	mutt_help (enum MenuType menu, int wraplen)
	Display the help menu. More...

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.

Function Documentation

help_lookup_function()

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

static

Find a keybinding for an operation.

Parameters

op	Operation, e.g. OP_DELETE
menu	Current Menu, e.g. MENU_PAGER

Return values

ptr	Key binding
NULL	If none

Definition at line 54 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;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_make_help()

void mutt_make_help	(	char *	buf,
		size_t	buflen,
		const char *	txt,
		enum MenuType	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, e.g. MENU_PAGER
op	Operation, e.g. OP_DELETE

This will return something like: "d:delete"

Definition at line 87 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';
  }
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_compile_help()

char* mutt_compile_help	(	char *	buf,
		size_t	buflen,
		enum MenuType	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, e.g. MENU_PAGER
items	Map of functions to display in the help bar

Return values

ptr	Buffer containing result

Definition at line 110 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_len(pbuf);
    pbuf += len;
    buflen -= len;
  }
  return buf;
}

Here is the call graph for this function:

Here is the caller graph for this function:

print_macro()

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 140 of file help.c.

{
  int n = maxwidth;
  wchar_t wc;
  size_t k;
  size_t len = mutt_str_len(*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;
}

Here is the call graph for this function:

Here is the caller graph for this function:

get_wrapped_width()

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 211 of file help.c.

{
  wchar_t wc;
  size_t k;
  size_t m, n;
  size_t len = mutt_str_len(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;
}

Here is the call graph for this function:

Here is the caller graph for this function:

pad()

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 col - Content was already wider than col

Definition at line 253 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;
}

Here is the caller graph for this function:

format_line()

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

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
wraplen	Width to wrap to

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 282 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 = (wraplen < 40);
  if (split)
  {
    col = 0;
    col_b = 1024;
    fputc('\n', fp);
  }
  else
  {
    const int col_a = (wraplen > 83) ? (wraplen - 32) >> 2 : 12;
    col_b = (wraplen > 49) ? (wraplen - 10) >> 1 : 19;
    col = pad(fp, mutt_strwidth(t1), col_a);
  }

  if (ismacro > 0)
  {
    if (!C_Pager || mutt_str_equal(C_Pager, "builtin"))
      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 = wraplen - col;

      if (ismacro >= 0)
      {
        SKIPWS(t3);
        n = get_wrapped_width(t3, n);
      }

      n = print_macro(fp, n, &t3);

      if (*t3)
      {
        if (mutt_str_equal(C_Pager, "builtin"))
        {
          n += col - wraplen;
          if (C_Markers)
            n++;
        }
        else
        {
          fputc('\n', fp);
          n = 0;
        }
        col = pad(fp, n, col_b);
      }
    }
  }

  fputc('\n', fp);
}

Here is the call graph for this function:

Here is the caller graph for this function:

dump_menu()

static void dump_menu ( FILE *  fp, enum MenuType  menu, int  wraplen  )

static

Write all the key bindings to a file.

Parameters

fp	File to write to
menu	Current Menu, e.g. MENU_PAGER
wraplen	Width to wrap to

Definition at line 372 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, wraplen);
        else
          format_line(fp, -1, buf, "macro", map->macro, wraplen);
      }
      else
      {
        b = help_lookup_function(map->op, menu);
        format_line(fp, 0, buf, b ? b->name : "UNKNOWN",
                    b ? _(OpStrings[b->op][1]) : _("ERROR: please report this bug"), wraplen);
      }
    }
  }
}

Here is the call graph for this function:

Here is the caller graph for this function:

is_bound()

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 408 of file help.c.

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

Here is the caller graph for this function:

dump_unbound()

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

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
wraplen	Width to wrap to

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, "", _(OpStrings[funcs[i].op][1]), wraplen);
  }
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_help()

void mutt_help	(	enum MenuType	menu,
		int	wraplen
	)

Display the help menu.

Parameters

menu	Current Menu
wraplen	Width to wrap to

Definition at line 439 of file help.c.

{
  char buf[128];
  FILE *fp = NULL;

  /* We don't use the buffer pool because of the extended lifetime of t */
  struct Buffer t = mutt_buffer_make(PATH_MAX);
  mutt_buffer_mktemp(&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(mutt_b2s(&t), "w");
    if (!fp)
    {
      mutt_perror(mutt_b2s(&t));
      goto cleanup;
    }

    dump_menu(fp, menu, wraplen);
    if ((menu != MENU_EDITOR) && (menu != MENU_PAGER))
    {
      fprintf(fp, "\n%s\n\n", _("Generic bindings:"));
      dump_menu(fp, MENU_GENERIC, wraplen);
    }

    fprintf(fp, "\n%s\n\n", _("Unbound functions:"));
    if (funcs)
      dump_unbound(fp, funcs, Keymaps[menu], NULL, wraplen);
    if (menu != MENU_PAGER)
      dump_unbound(fp, OpGeneric, Keymaps[MENU_GENERIC], Keymaps[menu], wraplen);

    mutt_file_fclose(&fp);

    snprintf(buf, sizeof(buf), _("Help for %s"), desc);
  } while (mutt_do_pager(buf, mutt_b2s(&t),
                         MUTT_PAGER_RETWINCH | MUTT_PAGER_MARKER | MUTT_PAGER_NSKIP | MUTT_PAGER_NOWRAP,
                         NULL) == OP_REFORMAT_WINCH);

cleanup:
  mutt_buffer_dealloc(&t);
}

Here is the call graph for this function:

Here is the caller graph for this function: