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 "config/lib.h"
#include "core/lib.h"
#include "gui/lib.h"
#include "key/lib.h"
#include "menu/lib.h"
#include "pager/lib.h"
#include "hdrline.h"
#include "protos.h"

Include dependency graph for help.c:

Go to the source code of this file.

Functions
static const struct MenuFuncOp *	help_lookup_function (int op, enum MenuType menu)
	Find a keybinding for an operation.
static int	print_macro (FILE *fp, int maxwidth, const char **macro)
	Print a macro string to a file.
static int	get_wrapped_width (const char *t, size_t wid)
	Wrap a string at a sensible place.
static int	pad (FILE *fp, int col, int i)
	Write some padding to a file.
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.
static void	dump_menu (FILE *fp, enum MenuType menu, int wraplen)
	Write all the key bindings to a file.
static bool	is_bound (struct KeymapList *km_list, int op)
	Does a function have a keybinding?
static void	dump_unbound (FILE *fp, const struct MenuFuncOp *funcs, struct KeymapList *km_list, struct KeymapList *aux, int wraplen)
	Write out all the operations with no key bindings.
static void	show_flag_if_present (FILE *fp, int wraplen, const struct MbTable *table, int index, char *description)
	Write out a message flag if exists.
static void	dump_message_flags (FILE *fp, int wraplen)
	Write out all the message flags.
void	mutt_help (enum MenuType menu)
	Display the help menu.

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 MenuFuncOp * 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	No key binding found

Definition at line 53 of file help.c.

{
  if (menu != MENU_PAGER && (menu != MENU_GENERIC))
  {
    /* 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];
  }
 
  const struct MenuFuncOp *funcs = km_get_table(menu);
  if (funcs)
  {
    for (int i = 0; funcs[i].name; i++)
      if (funcs[i].op == op)
        return &funcs[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 83 of file help.c.

{
  int n = maxwidth;
  wchar_t wc = 0;
  size_t k;
  size_t len = mutt_str_len(*macro);
  mbstate_t mbstate1 = { 0 };
  mbstate_t mbstate2 = { 0 };
 
  for (; len && (k = mbrtowc(&wc, *macro, len, &mbstate1)); *macro += k, len -= k)
  {
    if ((k == ICONV_ILLEGAL_SEQ) || (k == ICONV_BUF_TOO_SMALL))
    {
      if (k == ICONV_ILLEGAL_SEQ)
        memset(&mbstate1, 0, sizeof(mbstate1));
      k = (k == ICONV_ILLEGAL_SEQ) ? 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)) != ICONV_ILLEGAL_SEQ) &&
            ((n2 = wcrtomb(buf + n1, 0, &mbstate2)) != ICONV_ILLEGAL_SEQ))
        {
          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 153 of file help.c.

{
  wchar_t wc = 0;
  size_t k;
  size_t m, n;
  size_t len = mutt_str_len(t);
  const char *s = t;
  mbstate_t mbstate = { 0 };
 
  for (m = wid, n = 0; len && (k = mbrtowc(&wc, s, len, &mbstate)) && (n <= wid);
       s += k, len -= k)
  {
    if (*s == ' ')
      m = n;
    if ((k == ICONV_ILLEGAL_SEQ) || (k == ICONV_BUF_TOO_SMALL))
    {
      if (k == ICONV_ILLEGAL_SEQ)
        memset(&mbstate, 0, sizeof(mbstate));
      k = (k == ICONV_ILLEGAL_SEQ) ? 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 194 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 223 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);
  }
 
  const char *const c_pager = pager_get_pager(NeoMutt->sub);
  if (ismacro > 0)
  {
    if (!c_pager)
      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 (c_pager)
        {
          fputc('\n', fp);
          n = 0;
        }
        else
        {
          n += col - wraplen;
          const bool c_markers = cs_subset_bool(NeoMutt->sub, "markers");
          if (c_markers)
            n++;
        }
        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 315 of file help.c.

{
  struct Keymap *map = NULL;
  char buf[128] = { 0 };
 
  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
      {
        const struct MenuFuncOp *funcs = help_lookup_function(map->op, menu);
        format_line(fp, 0, buf, funcs ? funcs->name : "UNKNOWN",
                    funcs ? _(opcodes_get_description(funcs->op)) :
                            _("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	A key is bound to that operation

Definition at line 351 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 MenuFuncOp *  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 370 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, "", _(opcodes_get_description(funcs[i].op)), wraplen);
  }
}

Here is the call graph for this function:

Here is the caller graph for this function:

show_flag_if_present()

static void show_flag_if_present ( FILE *  fp, int  wraplen, const struct MbTable *  table, int  index, char *  description  )

static

Write out a message flag if exists.

Parameters

fp	File to write to
wraplen	Width to wrap to
table	Table containing the flag characters
index	Index of flag character int the table
description	Description of flag

Definition at line 388 of file help.c.

{
  const char *flag = mbtable_get_nth_wchar(table, index);
  if ((strlen(flag) < 1) || (*flag == ' '))
  {
    return;
  }
 
  format_line(fp, 0, flag, "", description, wraplen);
}

Here is the call graph for this function:

Here is the caller graph for this function:

dump_message_flags()

static void dump_message_flags ( FILE *  fp, int  wraplen  )

static

Write out all the message flags.

Parameters

fp	File to write to
wraplen	Width to wrap to

Definition at line 405 of file help.c.

{
  const struct MbTable *c_flag_chars = cs_subset_mbtable(NeoMutt->sub, "flag_chars");
  const struct MbTable *c_crypt_chars = cs_subset_mbtable(NeoMutt->sub, "crypt_chars");
  const struct MbTable *c_to_chars = cs_subset_mbtable(NeoMutt->sub, "to_chars");
 
  format_line(fp, 0, "$flag_chars:", "", "", wraplen);
  show_flag_if_present(fp, wraplen, c_flag_chars, FLAG_CHAR_TAGGED, _("message is tagged"));
  show_flag_if_present(fp, wraplen, c_flag_chars, FLAG_CHAR_IMPORTANT,
                       _("message is flagged"));
  show_flag_if_present(fp, wraplen, c_flag_chars, FLAG_CHAR_DELETED, _("message is deleted"));
  show_flag_if_present(fp, wraplen, c_flag_chars, FLAG_CHAR_DELETED_ATTACH,
                       _("attachment is deleted"));
  show_flag_if_present(fp, wraplen, c_flag_chars, FLAG_CHAR_REPLIED,
                       _("message has been replied to"));
  show_flag_if_present(fp, wraplen, c_flag_chars, FLAG_CHAR_OLD, _("message has been read"));
  show_flag_if_present(fp, wraplen, c_flag_chars, FLAG_CHAR_NEW, _("message is new"));
  show_flag_if_present(fp, wraplen, c_flag_chars, FLAG_CHAR_OLD_THREAD,
                       _("thread has been read"));
  show_flag_if_present(fp, wraplen, c_flag_chars, FLAG_CHAR_NEW_THREAD,
                       _("thread has at least one new message"));
  show_flag_if_present(fp, wraplen, c_flag_chars, FLAG_CHAR_SEMPTY,
                       _("message has been read (%S expando)"));
  show_flag_if_present(fp, wraplen, c_flag_chars, FLAG_CHAR_ZEMPTY,
                       _("message has been read (%Z expando)"));
 
  format_line(fp, 0, "\n$crypt_chars:", "", "", wraplen);
  show_flag_if_present(fp, wraplen, c_crypt_chars, FLAG_CHAR_CRYPT_GOOD_SIGN,
                       _("message signed with a verified key"));
  show_flag_if_present(fp, wraplen, c_crypt_chars, FLAG_CHAR_CRYPT_ENCRYPTED,
                       _("message is PGP-encrypted"));
  show_flag_if_present(fp, wraplen, c_crypt_chars, FLAG_CHAR_CRYPT_SIGNED,
                       _("message is signed"));
  show_flag_if_present(fp, wraplen, c_crypt_chars, FLAG_CHAR_CRYPT_CONTAINS_KEY,
                       _("message contains a PGP key"));
  show_flag_if_present(fp, wraplen, c_crypt_chars, FLAG_CHAR_CRYPT_NO_CRYPTO,
                       _("message has no cryptography information"));
 
  format_line(fp, 0, "\n$to_chars:", "", "", wraplen);
  show_flag_if_present(fp, wraplen, c_to_chars, FLAG_CHAR_TO_NOT_IN_THE_LIST,
                       _("message is not To: you"));
  show_flag_if_present(fp, wraplen, c_to_chars, FLAG_CHAR_TO_UNIQUE,
                       _("message is To: you and only you"));
  show_flag_if_present(fp, wraplen, c_to_chars, FLAG_CHAR_TO_TO, _("message is To: you"));
  show_flag_if_present(fp, wraplen, c_to_chars, FLAG_CHAR_TO_CC, _("message is Cc: to you"));
  show_flag_if_present(fp, wraplen, c_to_chars, FLAG_CHAR_TO_ORIGINATOR,
                       _("message is From: you"));
  show_flag_if_present(fp, wraplen, c_to_chars, FLAG_CHAR_TO_SUBSCRIBED_LIST,
                       _("message is sent to a subscribed mailing list"));
  show_flag_if_present(fp, wraplen, c_to_chars, FLAG_CHAR_TO_REPLY_TO,
                       _("you are in the Reply-To: list"));
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_help()

void mutt_help

(

enum MenuType

menu

)

Display the help menu.

Parameters

menu	Current Menu

Definition at line 462 of file help.c.

{
  char banner[128] = { 0 };
  FILE *fp = NULL;
 
  /* We don't use the buffer pool because of the extended lifetime of t */
  struct Buffer t = buf_make(PATH_MAX);
  buf_mktemp(&t);
 
  const struct MenuFuncOp *funcs = km_get_table(menu);
  const char *desc = mutt_map_get_name(menu, MenuNames);
  if (!desc)
    desc = _("<UNKNOWN>");
 
  struct PagerData pdata = { 0 };
  struct PagerView pview = { &pdata };
 
  pview.mode = PAGER_MODE_HELP;
  pview.flags = MUTT_PAGER_RETWINCH | MUTT_PAGER_MARKER | MUTT_PAGER_NSKIP |
                MUTT_PAGER_NOWRAP | MUTT_PAGER_STRIPES;
 
  do
  {
    fp = mutt_file_fopen(buf_string(&t), "w");
    if (!fp)
    {
      mutt_perror("%s", buf_string(&t));
      goto cleanup;
    }
 
    const int wraplen = AllDialogsWindow->state.cols;
    dump_menu(fp, menu, wraplen);
    if ((menu != MENU_EDITOR) && (menu != MENU_PAGER) && (menu != MENU_GENERIC))
    {
      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_EDITOR) && (menu != MENU_PAGER) && (menu != MENU_GENERIC))
      dump_unbound(fp, OpGeneric, &Keymaps[MENU_GENERIC], &Keymaps[menu], wraplen);
 
    if (menu == MENU_INDEX)
    {
      fprintf(fp, "\n%s\n\n", _("Message flags:"));
      dump_message_flags(fp, wraplen);
    }
 
    mutt_file_fclose(&fp);
 
    snprintf(banner, sizeof(banner), _("Help for %s"), desc);
    pdata.fname = buf_string(&t);
    pview.banner = banner;
  } while (mutt_do_pager(&pview, NULL) == OP_REFORMAT_WINCH);
 
cleanup:
  buf_dealloc(&t);
}

Here is the call graph for this function:

Here is the caller graph for this function: