From patchwork Sat Jun 1 21:23:29 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Philippe Waroquiers X-Patchwork-Id: 32963 Received: (qmail 79933 invoked by alias); 1 Jun 2019 21:23:51 -0000 Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Unsubscribe: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org Delivered-To: mailing list gdb-patches@sourceware.org Received: (qmail 79860 invoked by uid 89); 1 Jun 2019 21:23:50 -0000 Authentication-Results: sourceware.org; auth=none X-Spam-SWARE-Status: No, score=-22.7 required=5.0 tests=AWL, BAYES_00, GIT_PATCH_0, GIT_PATCH_1, GIT_PATCH_2, GIT_PATCH_3, RCVD_IN_DNSWL_LOW, SPF_PASS autolearn=ham version=3.3.1 spammy=Style, subcommands, ui_file X-HELO: mailsec102.isp.belgacom.be Received: from mailsec102.isp.belgacom.be (HELO mailsec102.isp.belgacom.be) (195.238.20.98) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with ESMTP; Sat, 01 Jun 2019 21:23:47 +0000 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=skynet.be; i=@skynet.be; q=dns/txt; s=securemail; t=1559424227; x=1590960227; h=from:to:cc:subject:date:message-id:in-reply-to: references:mime-version:content-transfer-encoding; bh=PWT1Dd/ESXUl+iXqIVptGVu4W4uBCfx/0jukBrFojYg=; b=e9RdQm0Lq/Urud2adJcNf+AtfTjF1Q/brO4nDam7O/JPBAHRrf8NwF1N iNZztYmTn3vC2S8f/DtAjbHQdHPXdw==; Received: from 161.32-242-81.adsl-dyn.isp.belgacom.be (HELO md.home) ([81.242.32.161]) by relay.skynet.be with ESMTP/TLS/DHE-RSA-AES128-GCM-SHA256; 01 Jun 2019 23:23:40 +0200 From: Philippe Waroquiers To: gdb-patches@sourceware.org Cc: Philippe Waroquiers Subject: [RFAv2 2/4] Improve usability and/or readibility of help and apropos output. Date: Sat, 1 Jun 2019 23:23:29 +0200 Message-Id: <20190601212331.12085-3-philippe.waroquiers@skynet.be> In-Reply-To: <20190601212331.12085-1-philippe.waroquiers@skynet.be> References: <20190601212331.12085-1-philippe.waroquiers@skynet.be> MIME-Version: 1.0 X-IsSubscribed: yes The "help" command can output long list of command names or classes. Use the title style to style the command names or classes to make the output more readable. Similarly, change "apropos" command to also style the command names. It is sometimes unclear why "apropos REGEXP" lists some commands, and then the user has to manually do 'help command' for all commands listed by "apropos" to see more details about the matching commands. => Add an optional flag -v so that "apropos -v REGEXP": * outputs the full documentation of matching commands. * highlights the documentation parts matching REGEXP. --- gdb/ChangeLog | 11 +++++++++ gdb/cli/cli-cmds.c | 22 +++++++++++------ gdb/cli/cli-decode.c | 56 +++++++++++++++++++++++++++++++++----------- gdb/cli/cli-decode.h | 2 +- 4 files changed, 69 insertions(+), 22 deletions(-) diff --git a/gdb/ChangeLog b/gdb/ChangeLog index b155b15c3a..e81db988f9 100644 --- a/gdb/ChangeLog +++ b/gdb/ChangeLog @@ -7131,3 +7131,14 @@ End: Update all callers according to the changes in cli/cli-style.h. * utils.h (fputs_highlighted): New function. * utils.c (fputs_highlighted): Likewise. + +2019-05-31 Philippe Waroquiers + + * cli/cli-decode.h (apropos_cmd): Add verbose argument. + * cli/cli-decode.c (apropos_cmd): Likewise. Use print_doc_of_command + instead of print_help_for_command. + (print_doc_of_command): New function. + (help_list): Add 'apropos -v word' suggestion. + (print_help_for_command): Style the command name using title style. + * cli/cli-cmds.c (apropos_command): Parse optional -v flag. + (_initialize_cli_cmds): Describe -v in apropos_command help. diff --git a/gdb/cli/cli-cmds.c b/gdb/cli/cli-cmds.c index bb2b04ddd8..09f932c2d2 100644 --- a/gdb/cli/cli-cmds.c +++ b/gdb/cli/cli-cmds.c @@ -1376,16 +1376,21 @@ show_user (const char *args, int from_tty) /* Search through names of commands and documentations for a certain regular expression. */ -static void -apropos_command (const char *searchstr, int from_tty) +static void +apropos_command (const char *arg, int from_tty) { - if (searchstr == NULL) + bool verbose = arg && check_for_argument (&arg, "-v", 2); + + if (verbose) + arg = skip_spaces (arg); + + if (arg == NULL || *arg == '\0') error (_("REGEXP string is empty")); - compiled_regex pattern (searchstr, REG_ICASE, + compiled_regex pattern (arg, REG_ICASE, _("Error in regular expression")); - apropos_cmd (gdb_stdout, cmdlist, pattern, ""); + apropos_cmd (gdb_stdout, cmdlist, verbose, pattern, ""); } /* Subroutine of alias_command to simplify it. @@ -1981,8 +1986,11 @@ Run the ``make'' program using the rest of the line as arguments.")); Show definitions of non-python/scheme user defined commands.\n\ Argument is the name of the user defined command.\n\ With no argument, show definitions of all user defined commands."), &showlist); - add_com ("apropos", class_support, apropos_command, - _("Search for commands matching a REGEXP")); + add_com ("apropos", class_support, apropos_command, _("\ +Search for commands matching a REGEXP\n\ +Usage: apropos [-v] REGEXP\n\ +Flag -v indicates to produce a verbose output, showing full documentation\n\ +of the matching commands.")); add_setshow_uinteger_cmd ("max-user-call-depth", no_class, &max_user_call_depth, _("\ diff --git a/gdb/cli/cli-decode.c b/gdb/cli/cli-decode.c index e3076f263c..e59e0c7040 100644 --- a/gdb/cli/cli-decode.c +++ b/gdb/cli/cli-decode.c @@ -23,6 +23,7 @@ #include "ui-out.h" #include "cli/cli-cmds.h" #include "cli/cli-decode.h" +#include "cli/cli-style.h" #include "common/gdb_optional.h" /* Prototypes for local functions. */ @@ -937,14 +938,42 @@ add_com_suppress_notification (const char *name, enum command_class theclass, &cmdlist, suppress_notification); } +/* If VERBOSE, print the full help for command C and highlight the + documentation parts matching HIGHLIGHT, + otherwise print only one-line help for command C. */ + +static void +print_doc_of_command (struct cmd_list_element *c, const char *prefix, + bool verbose, compiled_regex &highlight, + struct ui_file *stream) +{ + /* When printing the full documentation, add a line to separate + this documentation from the previous command help, in the likely + case that apropos finds several commands. */ + if (verbose) + fputs_filtered ("\n", stream); + + fprintf_styled (stream, title_style.style (), + "%s%s", prefix, c->name); + fputs_filtered (" -- ", stream); + if (verbose) + fputs_highlighted (c->doc, highlight, stream); + else + print_doc_line (stream, c->doc); + fputs_filtered ("\n", stream); +} + /* Recursively walk the commandlist structures, and print out the documentation of commands that match our regex in either their name, or their documentation. + If VERBOSE, prints the complete documentation and highlight the + documentation parts matching REGEX, otherwise prints only + the first line. */ -void -apropos_cmd (struct ui_file *stream, +void +apropos_cmd (struct ui_file *stream, struct cmd_list_element *commandlist, - compiled_regex ®ex, const char *prefix) + bool verbose, compiled_regex ®ex, const char *prefix) { struct cmd_list_element *c; int returnvalue; @@ -960,10 +989,7 @@ apropos_cmd (struct ui_file *stream, /* Try to match against the name. */ returnvalue = regex.search (c->name, name_len, 0, name_len, NULL); if (returnvalue >= 0) - { - print_help_for_command (c, prefix, - 0 /* don't recurse */, stream); - } + print_doc_of_command (c, prefix, verbose, regex, stream); } if (c->doc != NULL && returnvalue < 0) { @@ -971,10 +997,7 @@ apropos_cmd (struct ui_file *stream, /* Try to match against documentation. */ if (regex.search (c->doc, doc_len, 0, doc_len, NULL) >= 0) - { - print_help_for_command (c, prefix, - 0 /* don't recurse */, stream); - } + print_doc_of_command (c, prefix, verbose, regex, stream); } /* Check if this command has subcommands and is not an abbreviation. We skip listing subcommands of abbreviations @@ -983,7 +1006,7 @@ apropos_cmd (struct ui_file *stream, { /* Recursively call ourselves on the subcommand list, passing the right prefix in. */ - apropos_cmd (stream,*c->prefixlist,regex,c->prefixname); + apropos_cmd (stream, *c->prefixlist, verbose, regex, c->prefixname); } } } @@ -1126,6 +1149,9 @@ Type \"help all\" for the list of all commands."); fputs_filtered ("documentation.\n", stream); fputs_filtered ("Type \"apropos word\" to search " "for commands related to \"word\".\n", stream); + fputs_filtered ("Type \"apropos -v word\" for full documentation", stream); + wrap_here (""); + fputs_filtered (" of commands related to \"word\".\n", stream); fputs_filtered ("Command name abbreviations are allowed if unambiguous.\n", stream); } @@ -1212,10 +1238,12 @@ static void print_help_for_command (struct cmd_list_element *c, const char *prefix, int recurse, struct ui_file *stream) { - fprintf_filtered (stream, "%s%s -- ", prefix, c->name); + fprintf_styled (stream, title_style.style (), + "%s%s", prefix, c->name); + fputs_filtered (" -- ", stream); print_doc_line (stream, c->doc); fputs_filtered ("\n", stream); - + if (recurse && c->prefixlist != 0 && c->abbrev_flag == 0) diff --git a/gdb/cli/cli-decode.h b/gdb/cli/cli-decode.h index c53683d95c..a9f9cbfb31 100644 --- a/gdb/cli/cli-decode.h +++ b/gdb/cli/cli-decode.h @@ -249,7 +249,7 @@ extern void help_cmd_list (struct cmd_list_element *, enum command_class, extern void help_cmd (const char *, struct ui_file *); extern void apropos_cmd (struct ui_file *, struct cmd_list_element *, - compiled_regex &, const char *); + bool verbose, compiled_regex &, const char *); /* Used to mark commands that don't do anything. If we just leave the function field NULL, the command is interpreted as a help topic, or