[rfc] Add help text to start-up text

[rfc] Add help text to start-up text

[Phil Muldoon]

This patch proposes to add a few items to the GDB start-up text to
provide some indication on where the user can find help.

I did not add the wiki and manual URLs to configure et al as I am not
sure that is needed (I guess GDB packagers might have an opinion
here).

Also I am not sure if anything actually parses the initial output of
the GDB start-up text and if adding these lines will affect that.  So
I am seeking comments. 

What do you think?

Cheers

Phil


2013-06-12  Phil Muldoon  <pmuldoon@redhat.com>

	* top.c (print_gdb_version): Add help, apropos description and
	urls to wiki and online documentation.

--

diff --git a/gdb/top.c b/gdb/top.c
index 8ac756f..4c85b51 100644
--- a/gdb/top.c
+++ b/gdb/top.c
@@ -1156,8 +1156,16 @@ Type \"show configuration\" for configuration details.");
     {
       fprintf_filtered (stream,
 			_("\nFor bug reporting instructions, please see:\n"));
-      fprintf_filtered (stream, "%s.", REPORT_BUGS_TO);
+      fprintf_filtered (stream, "%s.\n\n", REPORT_BUGS_TO);
     }
+
+  fprintf_filtered (stream, _("The GDB manual can be found online at:\n\
+<http://www.gnu.org/software/gdb/documentation/>\n"));
+  fprintf_filtered (stream, _("The GDB wiki can be found online at:\n\
+<http://sourceware.org/gdb/wiki/>\n\n"));
+  fprintf_filtered (stream, _("For help, type 'help'.\n"));
+  fprintf_filtered (stream, _("Type 'apropos word' to search for \
+commands related to 'word'.\n"));
 }
 
 /* Print the details of GDB build-time configuration.  */

Re: [rfc] Add help text to start-up text

[Sergio Durigan Junior]

On Wednesday, June 12 2013, Phil Muldoon wrote:

> This patch proposes to add a few items to the GDB start-up text to
> provide some indication on where the user can find help.

Thanks for the patch, Phil!

> Also I am not sure if anything actually parses the initial output of
> the GDB start-up text and if adding these lines will affect that.  So
> I am seeking comments. 

That's a good question, but honestly I believe it would be
counter-productive to do such checks.  I tried to check Eclipse but
couldn't find myself inside the source-code.  Anyway, we'd better wait
for someone with more knowledge in this.

> 2013-06-12  Phil Muldoon  <pmuldoon@redhat.com>
>
> 	* top.c (print_gdb_version): Add help, apropos description and
> 	urls to wiki and online documentation.

You probably could mention your own PR 12735 in the ChangeLog entry :-).

> diff --git a/gdb/top.c b/gdb/top.c
> index 8ac756f..4c85b51 100644
> --- a/gdb/top.c
> +++ b/gdb/top.c
> @@ -1156,8 +1156,16 @@ Type \"show configuration\" for configuration details.");
>      {
>        fprintf_filtered (stream,
>  			_("\nFor bug reporting instructions, please see:\n"));
> -      fprintf_filtered (stream, "%s.", REPORT_BUGS_TO);
> +      fprintf_filtered (stream, "%s.\n\n", REPORT_BUGS_TO);
>      }
> +
> +  fprintf_filtered (stream, _("The GDB manual can be found online at:\n\
> +<http://www.gnu.org/software/gdb/documentation/>\n"));
> +  fprintf_filtered (stream, _("The GDB wiki can be found online at:\n\
> +<http://sourceware.org/gdb/wiki/>\n\n"));

I think the link for the wiki can go in the same line, without the
break.

> +  fprintf_filtered (stream, _("For help, type 'help'.\n"));
> +  fprintf_filtered (stream, _("Type 'apropos word' to search for \
> +commands related to 'word'.\n"));

These two lines could be joined, WDYT?

  For help, type 'help'.  Type 'apropos word' to search for commands related
  to 'word'.


I already think GDB's initialization text is too verbose nowadays, and
it will become even more verbose with this patch.  It's not that I don't
think your patch is useful (much to the contrary), but maybe we could
try to summarize the info a little bit?

Currently GDB displays (in my Fedora 17 x86_64):

  $ gdb
  GNU gdb (GDB) Fedora (7.4.50.20120120-54.fc17)
  Copyright (C) 2012 Free Software Foundation, Inc.
  License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
  This is free software: you are free to change and redistribute it.
  There is NO WARRANTY, to the extent permitted by law.  Type "show copying"
  and "show warranty" for details.
  This GDB was configured as "x86_64-redhat-linux-gnu".
  For bug reporting instructions, please see:
  <http://www.gnu.org/software/gdb/bugs/>.

It could be (this is just a proposal, of course):

  $ gdb
  GNU gdb (GDB) Fedora (7.4.50.20120120-54.fc17)
  License: GPLv3+.  This is free software: you are free to change
  and redistribute it.  Type "show copying" and "show warranty" for details.
  This GDB was configured as "x86_64-redhat-linux-gnu".

And then, with your patch (and my proposed modifications):

  $ gdb
  GNU gdb (GDB) Fedora (7.4.50.20120120-54.fc17)
  License: GPLv3+.  This is free software: you are free to change
  and redistribute it.  Type "show copying" and "show warranty" for details.
  This GDB was configured as "x86_64-redhat-linux-gnu".
  The GDB manual can be found online at:
  <http://www.gnu.org/software/gdb/documentation/>
  The GDB wiki can be found online at: <http://sourceware.org/gdb/wiki/>
  For help, type 'help'.  Type 'apropos word' to search for commands related
  to 'word'.

Anyway, I know this is a topic which can become a hot discussion, but
since you opened the Pandora box...  :-)

Thanks,

-- 
Sergio

Re: [rfc] Add help text to start-up text

[Gary Benson]

Phil Muldoon wrote:
> This patch proposes to add a few items to the GDB start-up text to
> provide some indication on where the user can find help.

Great!

> I did not add the wiki and manual URLs to configure et al as I am
> not sure that is needed (I guess GDB packagers might have an opinion
> here).

I think they're good how they are.  I can see the utility of changing
the bug-reporting URL, but not the others.  It might be useful to lift
them out of the translated string, but that's just idle speculation on
my part :)

> Also I am not sure if anything actually parses the initial output of
> the GDB start-up text and if adding these lines will affect that.  So
> I am seeking comments. 

I really hope things aren't parsing this!

> diff --git a/gdb/top.c b/gdb/top.c
> index 8ac756f..4c85b51 100644
> --- a/gdb/top.c
> +++ b/gdb/top.c
> @@ -1156,8 +1156,16 @@ Type \"show configuration\" for configuration details.");
>      {
>        fprintf_filtered (stream,
>  			_("\nFor bug reporting instructions, please see:\n"));
> -      fprintf_filtered (stream, "%s.", REPORT_BUGS_TO);
> +      fprintf_filtered (stream, "%s.\n\n", REPORT_BUGS_TO);
>      }
> +
> +  fprintf_filtered (stream, _("The GDB manual can be found online at:\n\
> +<http://www.gnu.org/software/gdb/documentation/>\n"));
> +  fprintf_filtered (stream, _("The GDB wiki can be found online at:\n\
> +<http://sourceware.org/gdb/wiki/>\n\n"));
> +  fprintf_filtered (stream, _("For help, type 'help'.\n"));
> +  fprintf_filtered (stream, _("Type 'apropos word' to search for \
> +commands related to 'word'.\n"));
>  }
>  
>  /* Print the details of GDB build-time configuration.  */

The quotes here should be \", to match those above.

Cheers,
Gary

-- 
http://gbenson.net/

Re: [rfc] Add help text to start-up text

[Pedro Alves]

On 06/12/2013 08:50 PM, Phil Muldoon wrote:
> This patch proposes to add a few items to the GDB start-up text to
> provide some indication on where the user can find help.
> 
> I did not add the wiki and manual URLs to configure et al as I am not
> sure that is needed (I guess GDB packagers might have an opinion
> here).
> 
> Also I am not sure if anything actually parses the initial output of
> the GDB start-up text and if adding these lines will affect that.  So
> I am seeking comments. 
> 
> What do you think?

I think at least the help and apropos bits are going to be super useful.
I like that a lot.

> +  fprintf_filtered (stream, _("The GDB manual can be found online at:\n\
> +<http://www.gnu.org/software/gdb/documentation/>\n"));
> +  fprintf_filtered (stream, _("The GDB wiki can be found online at:\n\
> +<http://sourceware.org/gdb/wiki/>\n\n"));

IMO, putting only one url here would be enough, and would make this
more condensed.  I don't think users need to care about the fact that
some documentation is in a wiki.  We should add a link
to the wiki to <http://www.gnu.org/software/gdb/documentation/>.  There's
more than the manual there even.
We could then just say something like:

(I suggest the imperative, like the help/apropos sentences, which turns
out shorter too.)

"Find the GDB manual and other documentation resources online at:\n\
<http://www.gnu.org/software/gdb/documentation/\n"

The url we hardcode in GDB stays there forever (as in, people will
use the first gdb release that includes it for many years), so having
a single point of entry is more flexible.

> +  fprintf_filtered (stream, _("For help, type 'help'.\n"));
> +  fprintf_filtered (stream, _("Type 'apropos word' to search for \
> +commands related to 'word'.\n"));
>  }
>  
>  /* Print the details of GDB build-time configuration.  */

-- 
Pedro Alves

Re: [rfc] Add help text to start-up text

[Phil Muldoon]

On 13/06/13 10:12, Pedro Alves wrote:
> On 06/12/2013 08:50 PM, Phil Muldoon wrote:
>> This patch proposes to add a few items to the GDB start-up text to
>> provide some indication on where the user can find help.

> I think at least the help and apropos bits are going to be super useful.
> I like that a lot.
> 
>> +  fprintf_filtered (stream, _("The GDB manual can be found online at:\n\
>> +<http://www.gnu.org/software/gdb/documentation/>\n"));
>> +  fprintf_filtered (stream, _("The GDB wiki can be found online at:\n\
>> +<http://sourceware.org/gdb/wiki/>\n\n"));

I've updated the patch with yours and other reviewers' suggestions.
The start-up text now reads:


GNU gdb (GDB) 7.6.50.20130612-cvs
Copyright (C) 2013 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.  Type "show copying"
and "show warranty" for details.
This GDB was configured as "x86_64-unknown-linux-gnu".
Type "show configuration" for configuration details.
For bug reporting instructions, please see:
<http://www.gnu.org/software/gdb/bugs/>.
Find the GDB manual and other documentation resources online at:
<http://www.gnu.org/software/gdb/documentation/>.
For help, type "help".
Type "apropos word" to search for commands related to "word".



What do you think?

Cheers

Phil


2013-06-21  Phil Muldoon  <pmuldoon@redhat.com>

	* top.c (print_gdb_version): Add help, apropos description and
	url to online documentation.

--

diff --git a/gdb/top.c b/gdb/top.c
index 8ac756f..529a784 100644
--- a/gdb/top.c
+++ b/gdb/top.c
@@ -1156,8 +1156,14 @@ Type \"show configuration\" for configuration details.");
     {
       fprintf_filtered (stream,
 			_("\nFor bug reporting instructions, please see:\n"));
-      fprintf_filtered (stream, "%s.", REPORT_BUGS_TO);
+      fprintf_filtered (stream, "%s.\n", REPORT_BUGS_TO);
     }
+  fprintf_filtered (stream,
+		    _("Find the GDB manual and other documentation \
+resources online at:\n<http://www.gnu.org/software/gdb/documentation/>.\n"));
+  fprintf_filtered (stream, _("For help, type \"help\".\n"));
+  fprintf_filtered (stream, _("Type \"apropos word\" to search for \
+commands related to \"word\".\n"));
 }
 
 /* Print the details of GDB build-time configuration.  */

Re: [rfc] Add help text to start-up text

[Pedro Alves]

On 06/21/2013 10:53 AM, Phil Muldoon wrote:
> I've updated the patch with yours and other reviewers' suggestions.
> The start-up text now reads:

Looks great to me.  Thanks!

-- 
Pedro Alves

Re: [rfc] Add help text to start-up text

[Phil Muldoon]

On 21/06/13 15:59, Pedro Alves wrote:
> On 06/21/2013 10:53 AM, Phil Muldoon wrote:
>> I've updated the patch with yours and other reviewers' suggestions.
>> The start-up text now reads:
> 
> Looks great to me.  Thanks!

It's been twelve days since the last comment on this patch, so I think
the conversation has pretty much ceased on this topic.  As the last
patch gathered no objections, is it ok to check in?

Cheers

Phil

Re: [rfc] Add help text to start-up text

[Pedro Alves]

On 07/03/2013 01:26 PM, Phil Muldoon wrote:
> On 21/06/13 15:59, Pedro Alves wrote:
>> On 06/21/2013 10:53 AM, Phil Muldoon wrote:
>>> I've updated the patch with yours and other reviewers' suggestions.
>>> The start-up text now reads:
>>
>> Looks great to me.  Thanks!
> 
> It's been twelve days since the last comment on this patch, so I think
> the conversation has pretty much ceased on this topic.  As the last
> patch gathered no objections, is it ok to check in?

OK.

Thanks,
-- 
Pedro Alves

Re: [rfc] Add help text to start-up text

[Phil Muldoon]

On 05/07/13 10:36, Pedro Alves wrote:
> On 07/03/2013 01:26 PM, Phil Muldoon wrote:
>>>> I've updated the patch with yours and other reviewers' suggestions.
>>>> The start-up text now reads:
>>>
>>> Looks great to me.  Thanks!
>>
>> It's been twelve days since the last comment on this patch, so I think
>> the conversation has pretty much ceased on this topic.  As the last
>> patch gathered no objections, is it ok to check in?
> 
> OK.
> 
> Thanks,

So committed.

Cheers,

Phil