help.c File Reference

Generate the help-page and GUI display it. 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 "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...
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 KeymapList *km_list, int op)
	Does a function have a keybinding? More...
static void	dump_unbound (FILE *fp, const struct Binding *funcs, struct KeymapList *km_list, struct KeymapList *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-page and GUI display it.

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 53 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:

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 85 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 156 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 198 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 227 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 317 of file help.c.

{
  struct Keymap *map = NULL;
  const struct Binding *b = NULL;
  char buf[128];

  STAILQ_FOREACH(map, &Keymaps[menu], entries)
  {
    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 KeymapList *  km_list, int  op  )

static

Does a function have a keybinding?

Parameters

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

Return values

true	If a key is bound to that operation

Definition at line 352 of file help.c.

{
  struct Keymap *map = NULL;
  STAILQ_FOREACH(map, km_list, entries)
  {
    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 KeymapList *  km_list, struct KeymapList *  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
km_list	First key map to consider
aux	Second key map to consider
wraplen	Width to wrap to

Definition at line 371 of file help.c.

{
  for (int i = 0; funcs[i].name; i++)
  {
    if (!is_bound(km_list, 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 386 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: