[PATCH] gdb: Make startup message more user friendly

[PATCH] gdb: Make startup message more user friendly

[Guinevere Larsen]

Currently, on startup, GDB prints a lot of licensing information and
then a few hints for new users.  While there is an attempt to separate
the hints from the rest of the text, my user testing showed that it is
not good enough, and most unfamiliar users will just skip the
information.  Especially considering that the documentation link happens
before the separation.

This commit attempts to make the startup message more friendly to new
users by using ascii art separators.  If there is enough space availabe,
an ascii art box is printed containing the hints, otherwise a simple
separator is printed.  The code deems "enough space available" when
there is enough space to print the documentation URL inside the box,
since the other hints will be broken into multiple lines if necessary.
Here are examples of the 2 possible startups, with enough space:

+-----------------------------------------------------------------+
| Find the GDB manual online at:                                  |
| http://www.gnu.org/software/gdb/documentation/                  |
| For help, type "help".                                          |
| Type "apropos <word>" to search for commands related to "word". |
+-----------------------------------------------------------------+

And with limited space:

---------------------------------------------
Find the GDB manual documentation resources o
nline at:
    <http://www.gnu.org/software/gdb/document
ation/>.
For help, type "help".
Type "apropos word" to search for commands re
lated to "word".

Unfortunately, I was not able to think of a way in which the code could
break a line if necessary and also include styled code for URLs and
commands, so, since I believe it is more important to have the box as
available as possible, I opted to not include any styling options.
---
 gdb/main.c |  2 ++
 gdb/top.c  | 86 +++++++++++++++++++++++++++++++++++++++++++++++-------
 gdb/top.h  |  4 +++
 3 files changed, 81 insertions(+), 11 deletions(-)

diff --git a/gdb/main.c b/gdb/main.c
index e1ef537c357..114b918bb39 100644
--- a/gdb/main.c
+++ b/gdb/main.c
@@ -1163,6 +1163,8 @@ captured_main_1 (struct captured_main_args *context)
       /* Print all the junk at the top, with trailing "..." if we are
 	 about to read a symbol file (possibly slowly).  */
       print_gdb_version (gdb_stdout, true);
+      gdb_printf ("\n");
+      print_gdb_hints (gdb_stdout);
       if (symarg)
 	gdb_printf ("..");
       gdb_printf ("\n");
diff --git a/gdb/top.c b/gdb/top.c
index f5b9fdc3034..81ac6476d9b 100644
--- a/gdb/top.c
+++ b/gdb/top.c
@@ -1357,17 +1357,81 @@ There is NO WARRANTY, to the extent permitted by law.",
 		  styled_string (file_name_style.style (),
 				 REPORT_BUGS_TO));
     }
-  gdb_printf (stream,
-	      _("Find the GDB manual and other documentation \
-resources online at:\n    <%ps>."),
-	      styled_string (file_name_style.style (),
-			     "http://www.gnu.org/software/gdb/documentation/"));
-  gdb_printf (stream, "\n\n");
-  gdb_printf (stream, _("For help, type \"%ps\".\n"),
-	      styled_string (command_style.style (), "help"));
-  gdb_printf (stream,
-	      _("Type \"%ps\" to search for commands related to \"word\"."),
-	      styled_string (command_style.style (), "apropos word"));
+}
+
+/* Print MESSAGE to STREAM in lines of maximum size WIDTH, so that it fits
+   in an ascii art box of width WIDTH+4.  Messages may be broken on
+   spaces.  */
+static void
+box_one_message (ui_file *stream, std::string message, int width)
+{
+  while (!message.empty ())
+    {
+      std::string line;
+      if (message.length () > width)
+	{
+	  line = message.substr (0, message.rfind (" ", width));
+	  message = message.substr (line.length ());
+	}
+      else
+	{
+	  line = message;
+	  message = "";
+	}
+
+      if (line.length () < width)
+	line.append (width - line.length (), ' ');
+
+      gdb_printf (stream, "| %s |\n", line.c_str ());
+    }
+}
+
+/* Print some hints about how to use GDB in a very visible manner.  */
+void
+print_gdb_hints (struct ui_file *stream)
+{
+  int width = get_chars_per_line ();
+
+  /* Arbitrarily setting maximum width to 80 characters, so that
+     things are big and visible but not overwhelming.  */
+  if (80 < width)
+    width = 80;
+
+  std::string docs_url = "http://www.gnu.org/software/gdb/documentation/";
+  /* If there isn't enough space to display the longest URL in a boxed
+     style, use the simple styling of a singular visual break.  The longest
+     URL is used because the other messages may be broken into multiple
+     lines, but URLs can't.  */
+  if (width - 3 <= docs_url.length ())
+    {
+      std::string sep (width, '-');
+      gdb_printf (stream, "%s\n", sep.c_str ());
+      gdb_printf (stream,
+		  _("Find the GDB manual documentation resources online at:\
+\n    <%ps>.\n"),
+		  styled_string (file_name_style.style (), docs_url.c_str ()));
+      gdb_printf (stream, _("For help, type \"%ps\".\n"),
+		  styled_string (command_style.style (), "help"));
+      gdb_printf (stream,
+		  _("Type \"%ps\" to search for commands related to \"word\"."),
+		  styled_string (command_style.style (), "apropos word"));
+      return;
+    }
+  else
+    {
+      std::string sep (width-2, '-');
+      /* Account for opening and closing of the box.  */
+      width -= 4;
+
+      gdb_printf (stream, "+%s+\n", sep.c_str ());
+      box_one_message (stream, "Find the GDB manual online at:", width);
+      box_one_message (stream, docs_url.c_str (), width);
+      box_one_message (stream, "For help, type \"help\".", width);
+      box_one_message (stream, "Type \"apropos <word>\" to search for"
+			       " commands related to \"word\".",
+		       width);
+      gdb_printf (stream, "+%s+\n", sep.c_str ());
+    }
 }
 
 /* Print the details of GDB build-time configuration.  */
diff --git a/gdb/top.h b/gdb/top.h
index 41af51acecf..f90515ea740 100644
--- a/gdb/top.h
+++ b/gdb/top.h
@@ -36,6 +36,10 @@ extern auto_boolean interactive_mode;
    mentioned.  */
 extern void print_gdb_version (struct ui_file *stream, bool interactive);
 
+/* Print some hints for an inexperienced user on how to get more
+   information about using GDB.  */
+extern void print_gdb_hints (struct ui_file *stream);
+
 extern void print_gdb_configuration (struct ui_file *);
 
 extern void read_command_file (FILE *);

base-commit: 84c1e5cec0ec7d80d460db2b823d329e9759c642
-- 
2.51.0

Re: [PATCH] gdb: Make startup message more user friendly

[Tom Tromey]

>>>>> "Guinevere" == Guinevere Larsen <guinevere@redhat.com> writes:

Guinevere> This commit attempts to make the startup message more friendly to new
Guinevere> users by using ascii art separators.  If there is enough space availabe,
Guinevere> an ascii art box is printed containing the hints, otherwise a simple
Guinevere> separator is printed.  The code deems "enough space available" when
Guinevere> there is enough space to print the documentation URL inside the box,
Guinevere> since the other hints will be broken into multiple lines if necessary.
Guinevere> Here are examples of the 2 possible startups, with enough space:

If emojis_ok() then it seems like this could use Unicode line drawing
instead.

Guinevere> Unfortunately, I was not able to think of a way in which the code could
Guinevere> break a line if necessary and also include styled code for URLs and
Guinevere> commands, so, since I believe it is more important to have the box as
Guinevere> available as possible, I opted to not include any styling options.

I'm not sure I really understand the problem but I think this would be a
step backward.

There are facilities to manipulate these sequences.  E.g. see what
no_terminal_escape_file or escape_buffering_file do.

One option might be to reimplement this as a ui_file that will only
split at un-styled spaces; and if the screen isn't big enough just omit
the box.  Then print_gdb_hints wouldn't need two branches printing the
same stuff.

thanks,
Tom

Re: [PATCH] gdb: Make startup message more user friendly

[Guinevere Larsen]

On 10/10/25 5:09 PM, Tom Tromey wrote:
>>>>>> "Guinevere" == Guinevere Larsen <guinevere@redhat.com> writes:
> Guinevere> This commit attempts to make the startup message more friendly to new
> Guinevere> users by using ascii art separators.  If there is enough space availabe,
> Guinevere> an ascii art box is printed containing the hints, otherwise a simple
> Guinevere> separator is printed.  The code deems "enough space available" when
> Guinevere> there is enough space to print the documentation URL inside the box,
> Guinevere> since the other hints will be broken into multiple lines if necessary.
> Guinevere> Here are examples of the 2 possible startups, with enough space:
>
> If emojis_ok() then it seems like this could use Unicode line drawing
> instead.
Good idea, I'll look into that
> Guinevere> Unfortunately, I was not able to think of a way in which the code could
> Guinevere> break a line if necessary and also include styled code for URLs and
> Guinevere> commands, so, since I believe it is more important to have the box as
> Guinevere> available as possible, I opted to not include any styling options.
>
> I'm not sure I really understand the problem but I think this would be a
> step backward.
>
> There are facilities to manipulate these sequences.  E.g. see what
> no_terminal_escape_file or escape_buffering_file do.

It's not that I don't know how to recognize the sequences, but rather 
that I didn't know how to handle the %ps for counting spaces.

I guess I would need to apply the style and check the gdb_byte* for the 
spaces? How would I go about that?

>
> One option might be to reimplement this as a ui_file that will only
> split at un-styled spaces; and if the screen isn't big enough just omit
> the box.  Then print_gdb_hints wouldn't need two branches printing the
> same stuff.
I think implementing a ui_file would be overboard. If the style has been 
pre-applied, the function box_one_message can be print_starter_hint, and 
be generic enough to not need the multiple paths.

-- 
Cheers,
Guinevere Larsen
It/she

Re: [PATCH] gdb: Make startup message more user friendly

[Guinevere Larsen]

On 10/10/25 5:09 PM, Tom Tromey wrote:
>>>>>> "Guinevere" == Guinevere Larsen <guinevere@redhat.com> writes:
> Guinevere> This commit attempts to make the startup message more friendly to new
> Guinevere> users by using ascii art separators.  If there is enough space availabe,
> Guinevere> an ascii art box is printed containing the hints, otherwise a simple
> Guinevere> separator is printed.  The code deems "enough space available" when
> Guinevere> there is enough space to print the documentation URL inside the box,
> Guinevere> since the other hints will be broken into multiple lines if necessary.
> Guinevere> Here are examples of the 2 possible startups, with enough space:
>
> If emojis_ok() then it seems like this could use Unicode line drawing
> instead.

I just tested this out and after I managed to get it working, I tested 
by adding "set style emoji off", and turns out this is printed before 
gdbinit is read, meaning a user can't disable it themselves. I 
personally think this is a really good improvement, but I can see this 
being a nuisance for users in terminals that support UTF-8 but the user 
themself doesn't like it.

What do you think? Should I add it anyway?

-- 
Cheers,
Guinevere Larsen
It/she

Re: [PATCH] gdb: Make startup message more user friendly

[Tom Tromey]

Guinevere> I just tested this out and after I managed to get it working, I tested
Guinevere> by adding "set style emoji off", and turns out this is printed before
Guinevere> gdbinit is read, meaning a user can't disable it themselves. I
Guinevere> personally think this is a really good improvement, but I can see this
Guinevere> being a nuisance for users in terminals that support UTF-8 but the
Guinevere> user themself doesn't like it.

It can be changed using the early initialization file so I think it's fine.

Tom

Re: [PATCH] gdb: Make startup message more user friendly

[Guinevere Larsen]

On 10/15/25 1:54 PM, Tom Tromey wrote:
> Guinevere> I just tested this out and after I managed to get it working, I tested
> Guinevere> by adding "set style emoji off", and turns out this is printed before
> Guinevere> gdbinit is read, meaning a user can't disable it themselves. I
> Guinevere> personally think this is a really good improvement, but I can see this
> Guinevere> being a nuisance for users in terminals that support UTF-8 but the
> Guinevere> user themself doesn't like it.
>
> It can be changed using the early initialization file so I think it's fine.
>
> Tom
>
Do you mean -iex? cause I've tried that as well and it didn't work either

-- 
Cheers,
Guinevere Larsen
It/she

Re: [PATCH] gdb: Make startup message more user friendly

[Tom Tromey]

>> It can be changed using the early initialization file so I think it's fine.

Guinevere> Do you mean -iex? cause I've tried that as well and it didn't work either

See the section on early initialization files here:

https://sourceware.org/gdb/current/onlinedocs/gdb.html/Initialization-Files.html

Like ~/.config/gdb/gdbearlyinit.

Tom

Re: [PATCH] gdb: Make startup message more user friendly

[Andrew Burgess]

Guinevere Larsen <guinevere@redhat.com> writes:

> On 10/15/25 1:54 PM, Tom Tromey wrote:
>> Guinevere> I just tested this out and after I managed to get it working, I tested
>> Guinevere> by adding "set style emoji off", and turns out this is printed before
>> Guinevere> gdbinit is read, meaning a user can't disable it themselves. I
>> Guinevere> personally think this is a really good improvement, but I can see this
>> Guinevere> being a nuisance for users in terminals that support UTF-8 but the
>> Guinevere> user themself doesn't like it.
>>
>> It can be changed using the early initialization file so I think it's fine.
>>
>> Tom
>>
> Do you mean -iex? cause I've tried that as well and it didn't work either

It's probably -eiex that's needed.

Thanks,
Andrew