[PATCH v2 0/7] Require help text to fit in 80 columns

[PATCH v2 0/7] Require help text to fit in 80 columns

[Tom Tromey]

I noticed that "help info variables" was pretty ugly on my 80-column
terminal.  While fixing this, I was curious to know what other
problems there might be, and I ended up writing a unit test to check
for over-long lines in the help text.  This series is the result.
I've split out a couple of patches where I reworded some text.

Regression tested on x86-64 Fedora 38.

---
Changes in v2:
- Now checks the final line of a help string as well
- Link to v1: https://inbox.sourceware.org/gdb-patches/20240603-doc-string-cols-v1-0-ad67124ba872@adacore.com

---
Tom Tromey (7):
      Call gdbpy_fix_doc_string_indentation for function help
      Wrap help strings at 80 columns
      Clean up opaque-type-resolution help
      Remove the "title" from the remote packet help
      Shorten internal problem help text
      Wrap help options when building help string
      Ensure that help text fits in 80 columns

 gdb/ada-lang.c                        | 10 +++---
 gdb/ax-gdb.c                          |  5 +--
 gdb/cli/cli-cmds.c                    |  9 +++---
 gdb/cli/cli-decode.h                  |  3 ++
 gdb/cli/cli-option.c                  | 60 +++++++++++++++++++++--------------
 gdb/cli/cli-utils.c                   |  8 ++---
 gdb/debuginfod-support.c              | 12 +++----
 gdb/dwarf2/loc.c                      | 14 ++++----
 gdb/elfread.c                         |  4 +--
 gdb/frame-unwind.c                    |  5 +--
 gdb/gdbtypes.c                        |  8 ++---
 gdb/infcmd.c                          |  6 ++--
 gdb/memattr.c                         |  3 +-
 gdb/psymtab.c                         |  3 +-
 gdb/python/py-function.c              |  2 ++
 gdb/record-btrace.c                   | 14 ++++----
 gdb/record-full.c                     |  4 +--
 gdb/record.c                          | 26 +++++++--------
 gdb/regcache-dump.c                   |  6 ++--
 gdb/remote.c                          |  6 ++--
 gdb/stap-probe.c                      |  5 +--
 gdb/symfile.c                         |  9 +++---
 gdb/symmisc.c                         |  3 +-
 gdb/symtab.c                          |  4 +--
 gdb/typeprint.c                       |  4 +--
 gdb/unittests/command-def-selftests.c | 10 +++++-
 gdb/utils.c                           | 16 +++++-----
 gdb/xtensa-tdep.c                     |  2 +-
 28 files changed, 147 insertions(+), 114 deletions(-)
---
base-commit: 58a628530ee68fe705b443947643037319e7d44e
change-id: 20240603-doc-string-cols-0fd31bbe72e2

Best regards,
-- 
Tom Tromey <tromey@adacore.com>

[PATCH v2 1/7] Call gdbpy_fix_doc_string_indentation for function help

[Tom Tromey]

If you invoke "help function _caller_is", you'll see that the help
text is indented strangely.  The fix for this is to add a call to
gdbpy_fix_doc_string_indentation in the appropriate spot, as is
already done for Python commands and parameters.
---
 gdb/python/py-function.c | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/gdb/python/py-function.c b/gdb/python/py-function.c
index 2bbfb9d3a6d..952f03bb77c 100644
--- a/gdb/python/py-function.c
+++ b/gdb/python/py-function.c
@@ -120,6 +120,8 @@ fnpy_init (PyObject *self, PyObject *args, PyObject *kwds)
 	      docstring = python_string_to_host_string (ds_obj.get ());
 	      if (docstring == NULL)
 		return -1;
+	      docstring
+		= gdbpy_fix_doc_string_indentation (std::move (docstring));
 	    }
 	}
     }

-- 
2.44.0

[PATCH v2 2/7] Wrap help strings at 80 columns

[Tom Tromey]

This patch ensures that all ordinary help strings are wrapped at 80
columns.  For the most part this consists of changing code like this
(note the embedded \n and the trailing backslash without a newline):

-Manage the space-separated list of debuginfod server URLs that GDB will query \
-when missing debuginfo, executables or source files.\nThe default value is \
-copied from the DEBUGINFOD_URLS environment variable."),

... to end each line with \n\, like:

+Manage the space-separated list of debuginfod server URLs that GDB will\n\
+query when missing debuginfo, executables or source files.\n\
+The default value is copied from the DEBUGINFOD_URLS environment variable."),
---
 gdb/ada-lang.c           | 10 +++++-----
 gdb/ax-gdb.c             |  5 +++--
 gdb/cli/cli-cmds.c       |  9 +++++----
 gdb/cli/cli-utils.c      |  8 ++++----
 gdb/debuginfod-support.c | 12 ++++++------
 gdb/dwarf2/loc.c         | 14 +++++++-------
 gdb/elfread.c            |  4 ++--
 gdb/frame-unwind.c       |  5 +++--
 gdb/infcmd.c             |  6 ++++--
 gdb/memattr.c            |  3 +--
 gdb/psymtab.c            |  3 ++-
 gdb/record-btrace.c      | 14 +++++++-------
 gdb/record-full.c        |  4 ++--
 gdb/record.c             | 26 +++++++++++++-------------
 gdb/regcache-dump.c      |  6 +++---
 gdb/stap-probe.c         |  5 +++--
 gdb/symfile.c            |  9 +++++----
 gdb/symmisc.c            |  3 ++-
 gdb/symtab.c             |  4 ++--
 gdb/typeprint.c          |  4 ++--
 gdb/xtensa-tdep.c        |  2 +-
 21 files changed, 82 insertions(+), 74 deletions(-)

diff --git a/gdb/ada-lang.c b/gdb/ada-lang.c
index 01978e08380..118cf5fb83b 100644
--- a/gdb/ada-lang.c
+++ b/gdb/ada-lang.c
@@ -13948,11 +13948,11 @@ this option to \"off\" unless necessary."),
 
   add_setshow_boolean_cmd ("print-signatures", class_vars,
 			   &print_signatures, _("\
-Enable or disable the output of formal and return types for functions in the \
-overloads selection menu."), _("\
-Show whether the output of formal and return types for functions in the \
-overloads selection menu is activated."),
-			   NULL, NULL, NULL, &set_ada_list, &show_ada_list);
+Control the display of functions in overloads selection menu."), _("\
+Show how functions in overloads selection menu will be displayed."),
+			   _("\
+When enabled, formal and return types are shown."),
+			   NULL, NULL, &set_ada_list, &show_ada_list);
 
   ada_source_charset = gnat_source_charsets[0];
   add_setshow_enum_cmd ("source-charset", class_files,
diff --git a/gdb/ax-gdb.c b/gdb/ax-gdb.c
index ab5e80029e2..f33ad2ddf7e 100644
--- a/gdb/ax-gdb.c
+++ b/gdb/ax-gdb.c
@@ -2655,7 +2655,8 @@ If not, generate remote agent bytecode for current frame pc address."),
 	   &maintenancelist);
 
   add_cmd ("agent-printf", class_maintenance, maint_agent_printf_command,
-	   _("Translate an expression into remote "
-	     "agent bytecode for evaluation and display the bytecodes."),
+	   _("\
+Translate an expression into remote agent bytecode display the bytecodes.\n\
+The expression is translated for evaluation, not tracing."),
 	   &maintenancelist);
 }
diff --git a/gdb/cli/cli-cmds.c b/gdb/cli/cli-cmds.c
index 3af794cebaf..72d8e2a6f63 100644
--- a/gdb/cli/cli-cmds.c
+++ b/gdb/cli/cli-cmds.c
@@ -2654,9 +2654,9 @@ to be printed or after trailing whitespace."));
 Set mode for script filename extension recognition."), _("\
 Show mode for script filename extension recognition."), _("\
 off  == no filename extension recognition (all sourced files are GDB scripts)\n\
-soft == evaluate script according to filename extension, fallback to GDB script"
-  "\n\
-strict == evaluate script according to filename extension, error if not supported"
+soft == evaluate script according to filename extension, fallback to GDB script\n\
+strict == evaluate script according to filename extension,\n\
+          error if not supported"
   ),
 			NULL,
 			show_script_ext_mode,
@@ -2751,9 +2751,10 @@ as 0 or -1 depending on the setting."),
 			 gdb_setting_internal_fn, NULL);
 
   add_internal_function ("_gdb_maint_setting_str", _("\
-$_gdb_maint_setting_str - returns the value of a GDB maintenance setting as a string.\n\
+$_gdb_maint_setting_str - returns the value of a GDB maintenance setting.\n\
 Usage: $_gdb_maint_setting_str (setting)\n\
 \n\
+Like \"$_gdb_maint_setting\", but the return value is always a string.\n\
 auto-boolean values are \"off\", \"on\", \"auto\".\n\
 boolean values are \"off\", \"on\".\n\
 Some integer settings accept an unlimited value, returned\n\
diff --git a/gdb/cli/cli-utils.c b/gdb/cli/cli-utils.c
index 45b30842e00..152fee96f8c 100644
--- a/gdb/cli/cli-utils.c
+++ b/gdb/cli/cli-utils.c
@@ -197,10 +197,10 @@ info_print_args_help (const char *prefix,
 		      bool document_n_flag)
 {
   return xstrprintf (_("\
-%sIf NAMEREGEXP is provided, only prints the %s whose name\n\
-matches NAMEREGEXP.\n\
-If -t TYPEREGEXP is provided, only prints the %s whose type\n\
-matches TYPEREGEXP.  Note that the matching is done with the type\n\
+%sIf NAMEREGEXP is provided, only prints the %s\n\
+whose name matches NAMEREGEXP.\n\
+If -t TYPEREGEXP is provided, only prints the %s\n\
+whose type matches TYPEREGEXP.  Note that the matching is done with the type\n\
 printed by the 'whatis' command.\n\
 By default, the command might produce headers and/or messages indicating\n\
 why no %s can be printed.\n\
diff --git a/gdb/debuginfod-support.c b/gdb/debuginfod-support.c
index 841b6f2078c..8029c87264d 100644
--- a/gdb/debuginfod-support.c
+++ b/gdb/debuginfod-support.c
@@ -624,9 +624,9 @@ When set to \"ask\", prompt whether to enable or disable debuginfod." ),
   add_setshow_string_noescape_cmd ("urls", class_run, _("\
 Set the list of debuginfod server URLs."), _("\
 Show the list of debuginfod server URLs."), _("\
-Manage the space-separated list of debuginfod server URLs that GDB will query \
-when missing debuginfo, executables or source files.\nThe default value is \
-copied from the DEBUGINFOD_URLS environment variable."),
+Manage the space-separated list of debuginfod server URLs that GDB will\n\
+query when missing debuginfo, executables or source files.\n\
+The default value is copied from the DEBUGINFOD_URLS environment variable."),
 				   set_debuginfod_urls,
 				   get_debuginfod_urls,
 				   show_debuginfod_urls,
@@ -657,9 +657,9 @@ query.\nTo disable, set to zero.  Verbose output is displayed by default."),
   add_setshow_boolean_cmd ("download-sections", class_maintenance, _("\
 Set whether debuginfod may download individual ELF/DWARF sections."), _("\
 Show whether debuginfod may download individual ELF/DWARF sections."), _("\
-When enabled, debuginfod may attempt to download individual ELF/DWARF \
-sections from debug info files.\nIf disabled, only whole debug info files \
-may be downloaded."),
+When enabled, debuginfod may attempt to download individual ELF/DWARF\n\
+sections from debug info files.\n\
+If disabled, only whole debug info files may be downloaded."),
 			   maint_set_debuginfod_download_sections,
 			   maint_get_debuginfod_download_sections,
 			   nullptr,
diff --git a/gdb/dwarf2/loc.c b/gdb/dwarf2/loc.c
index 5fea6683575..6fc19b12c3b 100644
--- a/gdb/dwarf2/loc.c
+++ b/gdb/dwarf2/loc.c
@@ -4125,13 +4125,13 @@ _initialize_dwarf2loc ()
 {
   add_setshow_zuinteger_cmd ("entry-values", class_maintenance,
 			     &entry_values_debug,
-			     _("Set entry values and tail call frames "
-			       "debugging."),
-			     _("Show entry values and tail call frames "
-			       "debugging."),
-			     _("When non-zero, the process of determining "
-			       "parameter values from function entry point "
-			       "and tail call frames will be printed."),
+			     _("\
+Set entry values and tail call frames debugging."),
+			     _("\
+Show entry values and tail call frames debugging."),
+			     _("\
+When non-zero, the process of determining parameter values from\n\
+function entry point and tail call frames will be printed."),
 			     NULL,
 			     show_entry_values_debug,
 			     &setdebuglist, &showdebuglist);
diff --git a/gdb/elfread.c b/gdb/elfread.c
index 7a6a8cadced..0e82aba4499 100644
--- a/gdb/elfread.c
+++ b/gdb/elfread.c
@@ -1416,8 +1416,8 @@ Set whether CTF is always read."),
 			   _("\
 Show whether CTF is always read."),
 			   _("\
-When off, CTF is only read if DWARF is not present.  When on, CTF is read\
- regardless of whether DWARF is present."),
+When off, CTF is only read if DWARF is not present.  When on, CTF is read\n\
+regardless of whether DWARF is present."),
 			   nullptr /* set_func */, nullptr /* show_func */,
 			   &setlist, &showlist);
 }
diff --git a/gdb/frame-unwind.c b/gdb/frame-unwind.c
index e5f108d3257..8324e291cc5 100644
--- a/gdb/frame-unwind.c
+++ b/gdb/frame-unwind.c
@@ -376,7 +376,8 @@ _initialize_frame_unwind ()
   add_cmd ("frame-unwinders",
 	   class_maintenance,
 	   maintenance_info_frame_unwinders,
-	   _("List the frame unwinders currently in effect, "
-	     "starting with the highest priority."),
+	   _("\
+List the frame unwinders currently in effect.\n\
+Unwinders are listed starting with the highest priority."),
 	   &maintenanceinfolist);
 }
diff --git a/gdb/infcmd.c b/gdb/infcmd.c
index 71514d5ba66..e7b648791bd 100644
--- a/gdb/infcmd.c
+++ b/gdb/infcmd.c
@@ -3279,8 +3279,10 @@ frame."));
   add_com_alias ("u", until_cmd, class_run, 1);
 
   c = add_com ("advance", class_run, advance_command, _("\
-Continue the program up to the given location (same form as args for break \
-command).\n\
+Continue the program up to the given location.\n\
+Usage: advance LOCSPEC\n\
+The argument is a location specification, i.e., the same forms\n\
+accepted by the 'break' command.\n\
 Execution will also stop upon exit from the current stack frame."));
   set_cmd_completer (c, location_completer);
 
diff --git a/gdb/memattr.c b/gdb/memattr.c
index 735068e5a46..669a5486ddf 100644
--- a/gdb/memattr.c
+++ b/gdb/memattr.c
@@ -595,8 +595,7 @@ void
 _initialize_mem ()
 {
   add_com ("mem", class_vars, mem_command, _("\
-Define attributes for memory region or reset memory region handling to "
-"target-based.\n\
+Define or reset attributes for memory regions.\n\
 Usage: mem auto\n\
        mem LOW HIGH [MODE WIDTH CACHE],\n\
 where MODE  may be rw (read/write), ro (read-only) or wo (write-only),\n\
diff --git a/gdb/psymtab.c b/gdb/psymtab.c
index 7d6648c4666..42b1151e9ca 100644
--- a/gdb/psymtab.c
+++ b/gdb/psymtab.c
@@ -1559,7 +1559,8 @@ Usage: mt print psymbols [-objfile OBJFILE] [-pc ADDRESS] [--] [OUTFILE]\n\
        mt print psymbols [-objfile OBJFILE] [-source SOURCE] [--] [OUTFILE]\n\
 Entries in the partial symbol table are dumped to file OUTFILE,\n\
 or the terminal if OUTFILE is unspecified.\n\
-If ADDRESS is provided, dump only the symbols for the file with code at that address.\n\
+If ADDRESS is provided, dump only the symbols for the file\n\
+with code at that address.\n\
 If SOURCE is provided, dump only that file's symbols.\n\
 If OBJFILE is provided, dump only that object file's symbols."),
 	   &maintenanceprintlist);
diff --git a/gdb/record-btrace.c b/gdb/record-btrace.c
index 9fec6112755..a96febe4b99 100644
--- a/gdb/record-btrace.c
+++ b/gdb/record-btrace.c
@@ -3134,10 +3134,10 @@ Set what memory accesses are allowed during replay."), _("\
 Show what memory accesses are allowed during replay."),
 			   _("Default is READ-ONLY.\n\n\
 The btrace record target does not trace data.\n\
-The memory therefore corresponds to the live target and not \
+The memory therefore corresponds to the live target and not\n\
 to the current replay position.\n\n\
 When READ-ONLY, allow accesses to read-only memory during replay.\n\
-When READ-WRITE, allow accesses to read-only and read-write memory during \
+When READ-WRITE, allow accesses to read-only and read-write memory during\n\
 replay."),
 			   NULL, cmd_show_replay_memory_access,
 			   &set_record_btrace_cmdlist,
@@ -3181,10 +3181,10 @@ Show the cpu to be used for trace decode."),
 			    &record_btrace_conf.bts.size,
 			    _("Set the record/replay bts buffer size."),
 			    _("Show the record/replay bts buffer size."), _("\
-When starting recording request a trace buffer of this size.  \
-The actual buffer size may differ from the requested size.  \
+When starting recording request a trace buffer of this size.\n\
+The actual buffer size may differ from the requested size.\n\
 Use \"info record\" to see the actual buffer size.\n\n\
-Bigger buffers allow longer recording but also take more time to process \
+Bigger buffers allow longer recording but also take more time to process\n\
 the recorded execution trace.\n\n\
 The trace buffer size may not be changed while recording."), NULL,
 			    show_record_bts_buffer_size_value,
@@ -3203,9 +3203,9 @@ The trace buffer size may not be changed while recording."), NULL,
 			    &record_btrace_conf.pt.size,
 			    _("Set the record/replay pt buffer size."),
 			    _("Show the record/replay pt buffer size."), _("\
-Bigger buffers allow longer recording but also take more time to process \
+Bigger buffers allow longer recording but also take more time to process\n\
 the recorded execution.\n\
-The actual buffer size may differ from the requested size.  Use \"info record\" \
+The actual buffer size may differ from the requested size.  Use \"info record\"\n\
 to see the actual buffer size."), NULL, show_record_pt_buffer_size_value,
 			    &set_record_btrace_pt_cmdlist,
 			    &show_record_btrace_pt_cmdlist);
diff --git a/gdb/record-full.c b/gdb/record-full.c
index eb62d186fa5..622eb2fc069 100644
--- a/gdb/record-full.c
+++ b/gdb/record-full.c
@@ -2977,8 +2977,8 @@ When ON, query if PREC cannot record memory change of next instruction."),
 	   _("\
 Print a recorded instruction.\n\
 If no argument is provided, print the last instruction recorded.\n\
-If a negative argument is given, prints how the nth previous \
+If a negative argument is given, prints how the nth previous\n\
 instruction will be undone.\n\
-If a positive argument is given, prints \
+If a positive argument is given, prints\n\
 how the nth following instruction will be redone."), &maintenanceprintlist);
 }
diff --git a/gdb/record.c b/gdb/record.c
index b25445713fd..b8ef7287365 100644
--- a/gdb/record.c
+++ b/gdb/record.c
@@ -859,38 +859,38 @@ With a /m or /s modifier, source lines are included (if available).\n\
 With a /r modifier, raw instructions in hex are included.\n\
 With a /f modifier, function names are omitted.\n\
 With a /p modifier, current position markers are omitted.\n\
-With no argument, disassembles ten more instructions after the previous \
+With no argument, disassembles ten more instructions after the previous\n\
 disassembly.\n\
-\"record instruction-history -\" disassembles ten instructions before a \
+\"record instruction-history -\" disassembles ten instructions before a\n\
 previous disassembly.\n\
-One argument specifies an instruction number as shown by 'info record', and \
+One argument specifies an instruction number as shown by 'info record', and\n\
 ten instructions are disassembled after that instruction.\n\
-Two arguments with comma between them specify starting and ending instruction \
+Two arguments with comma between them specify starting and ending instruction\n\
 numbers to disassemble.\n\
-If the second argument is preceded by '+' or '-', it specifies the distance \
+If the second argument is preceded by '+' or '-', it specifies the distance\n\
 from the first argument.\n\
-The number of instructions to disassemble can be defined with \"set record \
-instruction-history-size\"."),
+The number of instructions to disassemble can be defined with\n\
+\"set record instruction-history-size\"."),
 	   &record_cmdlist);
 
   add_cmd ("function-call-history", class_obscure, cmd_record_call_history, _("\
 Prints the execution history at function granularity.\n\
-It prints one line for each sequence of instructions that belong to the same \
+It prints one line for each sequence of instructions that belong to the same\n\
 function.\n\
 Without modifiers, it prints the function name.\n\
 With a /l modifier, the source file and line number range is included.\n\
 With a /i modifier, the instruction number range is included.\n\
 With a /c modifier, the output is indented based on the call stack depth.\n\
 With no argument, prints ten more lines after the previous ten-line print.\n\
-\"record function-call-history -\" prints ten lines before a previous ten-line \
+\"record function-call-history -\" prints ten lines before a previous ten-line\n\
 print.\n\
-One argument specifies a function number as shown by 'info record', and \
+One argument specifies a function number as shown by 'info record', and\n\
 ten lines are printed after that function.\n\
 Two arguments with comma between them specify a range of functions to print.\n\
-If the second argument is preceded by '+' or '-', it specifies the distance \
+If the second argument is preceded by '+' or '-', it specifies the distance\n\
 from the first argument.\n\
-The number of functions to print can be defined with \"set record \
-function-call-history-size\"."),
+The number of functions to print can be defined with\n\
+\"set record function-call-history-size\"."),
 	   &record_cmdlist);
 
   /* Sync command control variables.  */
diff --git a/gdb/regcache-dump.c b/gdb/regcache-dump.c
index bc665dc08a6..1badfe2c9f8 100644
--- a/gdb/regcache-dump.c
+++ b/gdb/regcache-dump.c
@@ -325,8 +325,8 @@ _initialize_regcache_dump ()
 	   &maintenanceprintlist);
   add_cmd ("remote-registers", class_maintenance,
 	   maintenance_print_remote_registers, _("\
-Print the internal register configuration including remote register number "
-"and g/G packets offset.\n\
-Takes an optional file parameter."),
+Print the internal register configuration.\n\
+Usage: maintenance print remote-registers [FILE]\n\
+The remote register number and g/G packets offset are included."),
 	   &maintenanceprintlist);
 }
diff --git a/gdb/stap-probe.c b/gdb/stap-probe.c
index 9558351f93d..b056145f401 100644
--- a/gdb/stap-probe.c
+++ b/gdb/stap-probe.c
@@ -1760,8 +1760,9 @@ _initialize_stap_probe ()
 			     &stap_expression_debug,
 			     _("Set SystemTap expression debugging."),
 			     _("Show SystemTap expression debugging."),
-			     _("When non-zero, the internal representation "
-			       "of SystemTap expressions will be printed."),
+			     _("\
+When non-zero, the internal representation of SystemTap expressions\n\
+will be printed."),
 			     NULL,
 			     show_stapexpressiondebug,
 			     &setdebuglist, &showdebuglist);
diff --git a/gdb/symfile.c b/gdb/symfile.c
index 6d0cba4211c..13e656dbe70 100644
--- a/gdb/symfile.c
+++ b/gdb/symfile.c
@@ -3857,8 +3857,8 @@ to execute.\n" READNOW_READNEVER_HELP), &cmdlist);
 
   c = add_cmd ("add-symbol-file", class_files, add_symbol_file_command, _("\
 Load symbols from FILE, assuming FILE has been dynamically loaded.\n\
-Usage: add-symbol-file FILE [-readnow | -readnever] [-o OFF] [ADDR] \
-[-s SECT-NAME SECT-ADDR]...\n\
+Usage: add-symbol-file FILE [-readnow|-readnever] [-o OFF] [ADDR]\n\
+                       [-s SECT-NAME SECT-ADDR]...\n\
 ADDR is the starting address of the file's text.\n\
 Each '-s' argument provides a section name and address, and\n\
 should be specified if the data and bss segments are not contiguous\n\
@@ -3956,8 +3956,9 @@ full  == print messages for the executable,\n\
 			   &separate_debug_file_debug, _("\
 Set printing of separate debug info file search debug."), _("\
 Show printing of separate debug info file search debug."), _("\
-When on, GDB prints the searched locations while looking for separate debug \
-info files."), NULL, NULL, &setdebuglist, &showdebuglist);
+When on, GDB prints the searched locations while looking for separate\n\
+debug info files."),
+			   NULL, NULL, &setdebuglist, &showdebuglist);
 
 #if GDB_SELF_TEST
   selftests::register_test
diff --git a/gdb/symmisc.c b/gdb/symmisc.c
index 2956ad92fce..74b5e6c850a 100644
--- a/gdb/symmisc.c
+++ b/gdb/symmisc.c
@@ -1052,7 +1052,8 @@ Usage: mt print symbols [-pc ADDRESS] [--] [OUTFILE]\n\
        mt print symbols [-objfile OBJFILE] [-source SOURCE] [--] [OUTFILE]\n\
 Entries in the full symbol table are dumped to file OUTFILE,\n\
 or the terminal if OUTFILE is unspecified.\n\
-If ADDRESS is provided, dump only the symbols for the file with code at that address.\n\
+If ADDRESS is provided, dump only the symbols for the file\n\
+with code at that address.\n\
 If SOURCE is provided, dump only that file's symbols.\n\
 If OBJFILE is provided, dump only that object file's symbols."),
 	   &maintenanceprintlist);
diff --git a/gdb/symtab.c b/gdb/symtab.c
index 0464b6d1479..11ae1337956 100644
--- a/gdb/symtab.c
+++ b/gdb/symtab.c
@@ -7224,8 +7224,8 @@ If zero then the symbol cache is disabled."),
 			   _("Set if the PROLOGUE-END flag is ignored."),
 			   _("Show if the PROLOGUE-END flag is ignored."),
 			   _("\
-The PROLOGUE-END flag from the line-table entries is used to place \
-breakpoints past the prologue of functions.  Disabling its use forces \
+The PROLOGUE-END flag from the line-table entries is used to place\n\
+breakpoints past the prologue of functions.  Disabling its use forces\n\
 the use of prologue scanners."),
 			   nullptr, nullptr,
 			   &maintenance_set_cmdlist,
diff --git a/gdb/typeprint.c b/gdb/typeprint.c
index 2e1c5ea81e7..4bb457fe3e0 100644
--- a/gdb/typeprint.c
+++ b/gdb/typeprint.c
@@ -875,8 +875,8 @@ Show printing of typedefs defined in classes."), NULL,
   add_setshow_zuinteger_unlimited_cmd ("nested-type-limit", no_class,
 				       &print_nested_type_limit,
 				       _("\
-Set the number of recursive nested type definitions to print \
-(\"unlimited\" or -1 to show all)."), _("\
+Set the number of recursive nested type definitions to print.\n\
+Use \"unlimited\" or -1 to show all."), _("\
 Show the number of recursive nested type definitions to print."), NULL,
 				       set_print_type_nested_types,
 				       show_print_type_nested_types,
diff --git a/gdb/xtensa-tdep.c b/gdb/xtensa-tdep.c
index 840768b65c7..d7a56ccc33c 100644
--- a/gdb/xtensa-tdep.c
+++ b/gdb/xtensa-tdep.c
@@ -3266,7 +3266,7 @@ _initialize_xtensa_tdep ()
 			     &xtensa_debug_level,
 			    _("Set Xtensa debugging."),
 			    _("Show Xtensa debugging."), _("\
-When non-zero, Xtensa-specific debugging is enabled. \
+When non-zero, Xtensa-specific debugging is enabled.\n\
 Can be 1, 2, 3, or 4 indicating the level of debugging."),
 			     NULL,
 			     NULL,

-- 
2.44.0

[PATCH v2 3/7] Clean up opaque-type-resolution help

[Tom Tromey]

The opaque-type-resolution help says "if set before loading symbols",
but I don't think this is accurate.  As far as I know, this resolution
can be done at any time.

This patch cleans up the help, also shortening it to less than 80
characters.
---
 gdb/gdbtypes.c | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/gdb/gdbtypes.c b/gdb/gdbtypes.c
index f39fe3de6a4..9d3d1148158 100644
--- a/gdb/gdbtypes.c
+++ b/gdb/gdbtypes.c
@@ -6150,10 +6150,10 @@ _initialize_gdbtypes ()
   /* Add user knob for controlling resolution of opaque types.  */
   add_setshow_boolean_cmd ("opaque-type-resolution", class_support,
 			   &opaque_type_resolution,
-			   _("Set resolution of opaque struct/class/union"
-			     " types (if set before loading symbols)."),
-			   _("Show resolution of opaque struct/class/union"
-			     " types (if set before loading symbols)."),
+			   _("\
+Set resolution of opaque struct/class/union types."),
+			   _("\
+Show resolution of opaque struct/class/union types."),
 			   NULL, NULL,
 			   show_opaque_type_resolution,
 			   &setlist, &showlist);

-- 
2.44.0

[PATCH v2 4/7] Remove the "title" from the remote packet help

[Tom Tromey]

The help for remote packet controls includes the "title".  However
this is is just the parameter name, and not really useful to see
repeated in the help text.
---
 gdb/remote.c | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/gdb/remote.c b/gdb/remote.c
index 311430b12a1..bb3ab4dc577 100644
--- a/gdb/remote.c
+++ b/gdb/remote.c
@@ -2463,11 +2463,9 @@ add_packet_config_cmd (const unsigned int which_packet, const char *name,
   packet_config *config = &remote_protocol_packets[which_packet];
 
   gdb::unique_xmalloc_ptr<char> set_doc
-    = xstrprintf ("Set use of remote protocol `%s' (%s) packet.",
-		  name, title);
+    = xstrprintf ("Set use of remote protocol `%s' packet.", name);
   gdb::unique_xmalloc_ptr<char> show_doc
-    = xstrprintf ("Show current use of remote protocol `%s' (%s) packet.",
-		  name, title);
+    = xstrprintf ("Show current use of remote protocol `%s' packet.", name);
   /* set/show TITLE-packet {auto,on,off} */
   gdb::unique_xmalloc_ptr<char> cmd_name = xstrprintf ("%s-packet", title);
   set_show_commands cmds

-- 
2.44.0

[PATCH v2 5/7] Shorten internal problem help text

[Tom Tromey]

The help text for various "internal problem" settings is longer than
80 columns.  This patch tightens this up a bit.  Note that these
commands are all "maint" commands so, IMO, it is sufficient if they
are clear to a gdb developer.
---
 gdb/utils.c | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/gdb/utils.c b/gdb/utils.c
index 17498e04312..e4536e2d107 100644
--- a/gdb/utils.c
+++ b/gdb/utils.c
@@ -596,11 +596,11 @@ add_internal_problem_command (struct internal_problem *problem)
   if (problem->user_settable_should_dump_core)
     {
       std::string set_core_doc
-	= string_printf (_("Set whether GDB should create a core file of "
-			   "GDB when %s is detected."), problem->name);
+	= string_printf (_("Set whether GDB should core dump "
+			   "when %s is detected."), problem->name);
       std::string show_core_doc
-	= string_printf (_("Show whether GDB will create a core file of "
-			   "GDB when %s is detected."), problem->name);
+	= string_printf (_("Show whether GDB should core dump "
+			   "when %s is detected."), problem->name);
       add_setshow_enum_cmd ("corefile", class_maintenance,
 			    internal_problem_modes,
 			    &problem->should_dump_core,
@@ -616,11 +616,11 @@ add_internal_problem_command (struct internal_problem *problem)
   if (problem->user_settable_should_print_backtrace)
     {
       std::string set_bt_doc
-	= string_printf (_("Set whether GDB should print a backtrace of "
-			   "GDB when %s is detected."), problem->name);
+	= string_printf (_("Set whether GDB should backtrace "
+			   "when %s is detected."), problem->name);
       std::string show_bt_doc
-	= string_printf (_("Show whether GDB will print a backtrace of "
-			   "GDB when %s is detected."), problem->name);
+	= string_printf (_("Show whether GDB should backtrace "
+			   "when %s is detected."), problem->name);
       add_setshow_boolean_cmd ("backtrace", class_maintenance,
 			       &problem->should_print_backtrace,
 			       set_bt_doc.c_str (),

-- 
2.44.0

[PATCH v2 6/7] Wrap help options when building help string

[Tom Tromey]

When building a help string, it's possible that the resulting options
will go over 80 columns.  This patch changes this code to add line
wrapping where needed.

This can most be seen by looking "help bt" and in particular the
"-frame-info" help text.
---
 gdb/cli/cli-decode.h |  3 +++
 gdb/cli/cli-option.c | 60 ++++++++++++++++++++++++++++++++--------------------
 2 files changed, 40 insertions(+), 23 deletions(-)

diff --git a/gdb/cli/cli-decode.h b/gdb/cli/cli-decode.h
index 7365c3f0157..7e25374fc80 100644
--- a/gdb/cli/cli-decode.h
+++ b/gdb/cli/cli-decode.h
@@ -29,6 +29,9 @@
 #include "gdbsupport/intrusive_list.h"
 #include "gdbsupport/buildargv.h"
 
+/* The allowed length of a line in a documentation string.  */
+constexpr int cli_help_line_length = 80;
+
 /* Not a set/show command.  Note that some commands which begin with
    "set" or "show" might be in this category, if their syntax does
    not fall into one of the following categories.  */
diff --git a/gdb/cli/cli-option.c b/gdb/cli/cli-option.c
index 05539285c80..520810276a4 100644
--- a/gdb/cli/cli-option.c
+++ b/gdb/cli/cli-option.c
@@ -659,50 +659,68 @@ process_options (const char **args,
     }
 }
 
-/* Helper for build_help.  Return a fragment of a help string showing
-   OPT's possible values.  Returns NULL if OPT doesn't take an
-   argument.  */
+/* Helper for build_help.  Append a fragment of a help string showing
+   OPT's possible values.  LEN_AT_START is the length of HELP at the
+   start of the current line.  This is used when wrapping is
+   needed.  */
 
-static const char *
-get_val_type_str (const option_def &opt, std::string &buffer)
+static void
+append_val_type_str (std::string &help, const option_def &opt,
+		     size_t len_at_start)
 {
   if (!opt.have_argument)
-    return nullptr;
+    return;
 
   switch (opt.type)
     {
     case var_boolean:
-      return "[on|off]";
+      help += " [on|off]";
+      break;
     case var_uinteger:
     case var_integer:
     case var_pinteger:
       {
-	buffer = "NUMBER";
+	help += " NUMBER";
 	if (opt.extra_literals != nullptr)
 	  for (const literal_def *l = opt.extra_literals;
 	       l->literal != nullptr;
 	       l++)
 	    {
-	      buffer += '|';
-	      buffer += l->literal;
+	      help += '|';
+	      help += l->literal;
 	    }
-	return buffer.c_str ();
       }
+      break;
     case var_enum:
       {
-	buffer = "";
+	help += ' ';
+	/* If wrapping is needed, subsequent lines will be indented
+	   this amount.  */
+	size_t indent = help.length () - len_at_start;
 	for (size_t i = 0; opt.enums[i] != nullptr; i++)
 	  {
 	    if (i != 0)
-	      buffer += "|";
-	    buffer += opt.enums[i];
+	      {
+		size_t new_len = help.length () + 1 + strlen (opt.enums[i]);
+
+		if (new_len - len_at_start >= cli_help_line_length)
+		  {
+		    help += "\n";
+		    len_at_start = help.length ();
+
+		    help.append (indent, ' ');
+		  }
+		help += "|";
+	      }
+	    help += opt.enums[i];
 	  }
-	return buffer.c_str ();
       }
+      break;
     case var_string:
-      return "STRING";
+      help += " STRING";
+      break;
     default:
-      return nullptr;
+      break;
     }
 }
 
@@ -740,15 +758,11 @@ build_help_option (gdb::array_view<const option_def> options,
       if (o.set_doc == nullptr)
 	continue;
 
+      size_t initial_len = help.length ();
       help += "  -";
       help += o.name;
 
-      const char *val_type_str = get_val_type_str (o, buffer);
-      if (val_type_str != nullptr)
-	{
-	  help += ' ';
-	  help += val_type_str;
-	}
+      append_val_type_str (help, o, initial_len);
       help += "\n";
       append_indented_doc (o.set_doc, help);
       if (o.help_doc != nullptr)

-- 
2.44.0

[PATCH v2 7/7] Ensure that help text fits in 80 columns

[Tom Tromey]

This patch adds a new unit test that ensures that all help text wraps
at 80 columns.
---
 gdb/unittests/command-def-selftests.c | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/gdb/unittests/command-def-selftests.c b/gdb/unittests/command-def-selftests.c
index 6a9b194e680..cf51f0d275a 100644
--- a/gdb/unittests/command-def-selftests.c
+++ b/gdb/unittests/command-def-selftests.c
@@ -78,9 +78,10 @@ check_doc (struct cmd_list_element *commandlist, const char *prefix)
 	  (prefix, c->name,
 	   "has superfluous trailing whitespace");
 
+      const char *prev_start = c->doc;
       for (const char *nl = strchr (c->doc, '\n');
 	   nl != nullptr;
-	   nl = strchr (nl + 1, '\n'))
+	   nl = strchr (prev_start, '\n'))
 	{
 	  if (nl == c->doc)
 	    broken_doc_invariant (prefix, c->name, "has a leading newline");
@@ -91,8 +92,15 @@ check_doc (struct cmd_list_element *commandlist, const char *prefix)
 		broken_doc_invariant (prefix, c->name,
 				      "has whitespace before a newline");
 	    }
+
+	  if (nl - prev_start > cli_help_line_length)
+	    broken_doc_invariant (prefix, c->name, "has over-long line");
+	  prev_start = nl + 1;
 	}
 
+      if (strlen (prev_start) > cli_help_line_length)
+	broken_doc_invariant (prefix, c->name, "has over-long line");
+
       /* Check if this command has subcommands and is not an
 	 abbreviation.  We skip checking subcommands of abbreviations
 	 in order to avoid duplicates in the output.  */

-- 
2.44.0

Re: [PATCH v2 3/7] Clean up opaque-type-resolution help

[Eli Zaretskii]

> From: Tom Tromey <tromey@adacore.com>
> Date: Mon, 10 Jun 2024 13:50:24 -0600
> 
> The opaque-type-resolution help says "if set before loading symbols",
> but I don't think this is accurate.  As far as I know, this resolution
> can be done at any time.
> 
> This patch cleans up the help, also shortening it to less than 80
> characters.
> ---
>  gdb/gdbtypes.c | 8 ++++----
>  1 file changed, 4 insertions(+), 4 deletions(-)

Thanks, this is okay.

Approved-By: Eli Zaretskii <eliz@gnu.org>

Re: [PATCH v2 5/7] Shorten internal problem help text

[Eli Zaretskii]

> From: Tom Tromey <tromey@adacore.com>
> Date: Mon, 10 Jun 2024 13:50:26 -0600
> 
> The help text for various "internal problem" settings is longer than
> 80 columns.  This patch tightens this up a bit.  Note that these
> commands are all "maint" commands so, IMO, it is sufficient if they
> are clear to a gdb developer.
> ---
>  gdb/utils.c | 16 ++++++++--------
>  1 file changed, 8 insertions(+), 8 deletions(-)

Thanks.

>        std::string set_core_doc
> -	= string_printf (_("Set whether GDB should create a core file of "
> -			   "GDB when %s is detected."), problem->name);
> +	= string_printf (_("Set whether GDB should core dump "

I guess "should dump core" is better than "should core dump"?  Or
maybe you meant "should core-dump"?

> -	= string_printf (_("Show whether GDB will create a core file of "
> -			   "GDB when %s is detected."), problem->name);
> +	= string_printf (_("Show whether GDB should core dump "
> +			   "when %s is detected."), problem->name);

Likewise.

> -	= string_printf (_("Set whether GDB should print a backtrace of "
> -			   "GDB when %s is detected."), problem->name);
> +	= string_printf (_("Set whether GDB should backtrace "
> +			   "when %s is detected."), problem->name);
>        std::string show_bt_doc
> -	= string_printf (_("Show whether GDB will print a backtrace of "
> -			   "GDB when %s is detected."), problem->name);
> +	= string_printf (_("Show whether GDB should backtrace "
> +			   "when %s is detected."), problem->name);

How about "should produce backtrace"?

Reviewed-By: Eli Zaretskii <eliz@gnu.org>

Re: [PATCH v2 4/7] Remove the "title" from the remote packet help

[Eli Zaretskii]

> From: Tom Tromey <tromey@adacore.com>
> Date: Mon, 10 Jun 2024 13:50:25 -0600
> 
> The help for remote packet controls includes the "title".  However
> this is is just the parameter name, and not really useful to see
> repeated in the help text.
> ---
>  gdb/remote.c | 6 ++----
>  1 file changed, 2 insertions(+), 4 deletions(-)

Thanks, this is okay.

Approved-By: Eli Zaretskii <eliz@gnu.org>

Re: [PATCH v2 2/7] Wrap help strings at 80 columns

[Eli Zaretskii]

> From: Tom Tromey <tromey@adacore.com>
> Date: Mon, 10 Jun 2024 13:50:23 -0600
> 
> This patch ensures that all ordinary help strings are wrapped at 80
> columns.  For the most part this consists of changing code like this
> (note the embedded \n and the trailing backslash without a newline):
> 
> -Manage the space-separated list of debuginfod server URLs that GDB will query \
> -when missing debuginfo, executables or source files.\nThe default value is \
> -copied from the DEBUGINFOD_URLS environment variable."),
> 
> ... to end each line with \n\, like:
> 
> +Manage the space-separated list of debuginfod server URLs that GDB will\n\
> +query when missing debuginfo, executables or source files.\n\
> +The default value is copied from the DEBUGINFOD_URLS environment variable."),
> ---
>  gdb/ada-lang.c           | 10 +++++-----
>  gdb/ax-gdb.c             |  5 +++--
>  gdb/cli/cli-cmds.c       |  9 +++++----
>  gdb/cli/cli-utils.c      |  8 ++++----
>  gdb/debuginfod-support.c | 12 ++++++------
>  gdb/dwarf2/loc.c         | 14 +++++++-------
>  gdb/elfread.c            |  4 ++--
>  gdb/frame-unwind.c       |  5 +++--
>  gdb/infcmd.c             |  6 ++++--
>  gdb/memattr.c            |  3 +--
>  gdb/psymtab.c            |  3 ++-
>  gdb/record-btrace.c      | 14 +++++++-------
>  gdb/record-full.c        |  4 ++--
>  gdb/record.c             | 26 +++++++++++++-------------
>  gdb/regcache-dump.c      |  6 +++---
>  gdb/stap-probe.c         |  5 +++--
>  gdb/symfile.c            |  9 +++++----
>  gdb/symmisc.c            |  3 ++-
>  gdb/symtab.c             |  4 ++--
>  gdb/typeprint.c          |  4 ++--
>  gdb/xtensa-tdep.c        |  2 +-
>  21 files changed, 82 insertions(+), 74 deletions(-)

Thanks.

>    add_cmd ("agent-printf", class_maintenance, maint_agent_printf_command,
> -	   _("Translate an expression into remote "
> -	     "agent bytecode for evaluation and display the bytecodes."),
> +	   _("\
> +Translate an expression into remote agent bytecode display the bytecodes.\n\
                                                     ^
I guess a comma is missing there?

PK with the above nit fixed.

Approved-By: Eli Zaretskii <eliz@gnu.org>

RE: [PATCH v2 2/7] Wrap help strings at 80 columns

[Metzger, Markus T]

>>    add_cmd ("agent-printf", class_maintenance,
>maint_agent_printf_command,
>> -	   _("Translate an expression into remote "
>> -	     "agent bytecode for evaluation and display the bytecodes."),
>> +	   _("\
>> +Translate an expression into remote agent bytecode display the
>bytecodes.\n\
>                                                     ^
>I guess a comma is missing there?

Looks more like ' for evaluation and ' is missing.

Markus.
Intel Deutschland GmbH
Registered Address: Am Campeon 10, 85579 Neubiberg, Germany
Tel: +49 89 99 8853-0, www.intel.de
Managing Directors: Sean Fennelly, Jeffrey Schneiderman, Tiffany Doon Silva
Chairperson of the Supervisory Board: Nicole Lau
Registered Office: Munich
Commercial Register: Amtsgericht Muenchen HRB 186928