[PATCH] gdb: gdb.1 - order options alphabetically in manual page

[PATCH] gdb: gdb.1 - order options alphabetically in manual page

[Jari Aalto]

Motivation:

    Order of the options would follow the convention used in other GNU
    programs lik Cf. cp(1), mv(1), etc.

Forwarded from:

    http://sourceware.org/bugzilla/show_bug.cgi?id=10505

I have assigned papers to FSF (Emacs). Please let me know if more is
needed.

Jari

[ChangeLog]

2009-09-09  Jari Aalto  <jari.aalto@cante.net>

	* gdb.1: Order options alphabetically.

[PATCH]

From 539edd1a9af966d16f3391edece93702a86c7155 Mon Sep 17 00:00:00 2001
From: Jari Aalto <jari.aalto@cante.net>
Date: Sat, 8 Aug 2009 10:18:20 +0300
Subject: [PATCH] gdb.1: Order options alphabetically

Signed-off-by: Jari Aalto <jari.aalto@cante.net>
---
 gdb/gdb.1 |  148 +++++++++++++++++++++++++------------------------------------
 1 files changed, 60 insertions(+), 88 deletions(-)

diff --git a/gdb/gdb.1 b/gdb/gdb.1
index 809578f..18550b4 100644
--- a/gdb/gdb.1
+++ b/gdb/gdb.1
@@ -205,90 +205,11 @@ in sequential order.  The order makes a difference when the
 `\|\c
 .B \-x\c
 \&\|' option is used.
-
-.TP
-.B \-help
-.TP
-.B \-h
-List all options, with brief explanations.
-
-.TP
-.BI "\-symbols=" "file"\c
-.TP
-.BI "\-s " "file"\c
-\&
-Read symbol table from file \c
-.I file\c
-\&.
-
-.TP
-.B \-write
-Enable writing into executable and core files.
-
-.TP
-.BI "\-exec=" "file"\c
-.TP
-.BI "\-e " "file"\c
-\&
-Use file \c
-.I file\c
-\& as the executable file to execute when
-appropriate, and for examining pure data in conjunction with a core
-dump.
-
-.TP
-.BI "\-se=" "file"\c
-\&
-Read symbol table from file \c
-.I file\c
-\& and use it as the executable
-file.
-
-.TP
-.BI "\-core=" "file"\c
-.TP
-.BI "\-c " "file"\c
-\&
-Use file \c
-.I file\c
-\& as a core dump to examine.
-
-.TP
-.BI "\-command=" "file"\c
-.TP
-.BI "\-x " "file"\c
-\&
-Execute GDB commands from file \c
-.I file\c
-\&.  
-
-.TP
-.BI "\-directory=" "directory"\c
 .TP
-.BI "\-d " "directory"\c
+.BI "\-b " "bps"\c
 \&
-Add \c
-.I directory\c
-\& to the path to search for source files.
-.PP
-
-.TP
-.B \-nx
-.TP
-.B \-n
-Do not execute commands from any `\|\c
-.B .gdbinit\c
-\&\|' initialization files.
-Normally, the commands in these files are executed after all the
-command options and arguments have been processed.
-
-
-.TP
-.B \-quiet
-.TP
-.B \-q
-``Quiet''.  Do not print the introductory and copyright messages.  These
-messages are also suppressed in batch mode.
+Set the line speed (baud rate or bits per second) of any serial
+interface used by GDB for remote debugging.
 
 .TP
 .B \-batch
@@ -316,6 +237,12 @@ Program\ exited\ normally.
 terminates) is not issued when running in batch mode.
 
 .TP
+.B \-c FILE, \-core=FILE
+Use file \c
+.I file\c
+\& as a core dump to examine.
+
+.TP
 .BI "\-cd=" "directory"\c
 \&
 Run GDB using \c
@@ -324,9 +251,21 @@ Run GDB using \c
 instead of the current directory.
 
 .TP
-.B \-fullname
+.B \-d DIRECTORY, \-directory=DIRECTORY
+Add \c
+.I directory\c
+\& to the path to search for source files.
+
+.TP
+.B \-e FILE, -exec=FILE
+Use file \c
+.I file\c
+\& as the executable file to execute when
+appropriate, and for examining pure data in conjunction with a core
+dump.
+
 .TP
-.B \-f
+.B \-f, \-fullname
 Emacs sets this option when it runs GDB as a subprocess.  It tells GDB
 to output the full file name and line number in a standard,
 recognizable fashion each time a stack frame is displayed (which
@@ -341,10 +280,34 @@ Emacs-to-GDB interface program uses the two `\|\c
 a signal to display the source code for the frame.
 
 .TP
-.BI "\-b " "bps"\c
-\&
-Set the line speed (baud rate or bits per second) of any serial
-interface used by GDB for remote debugging.
+.B \-h, \-help
+List all options, with brief explanations.
+
+.TP
+.B \-n, \-nx
+Do not execute commands from any `\|\c
+.B .gdbinit\c
+\&\|' initialization files.
+Normally, the commands in these files are executed after all the
+command options and arguments have been processed.
+
+.TP
+.B -s FILE, \-symbols=FILE
+Read symbol table from file \c
+.I file\c
+\&.
+
+.TP
+.BI "\-se=" "file"\c
+Read symbol table from file \c
+.I file\c
+\& and use it as the executable
+file.
+
+.TP
+.B \q, \-quiet
+``Quiet''.  Do not print the introductory and copyright messages.  These
+messages are also suppressed in batch mode.
 
 .TP
 .BI "\-tty=" "device"\c
@@ -354,6 +317,15 @@ Run using \c
 \& for your program's standard input and output.
 .PP
 
+.TP
+.B \-write
+Enable writing into executable and core files.
+
+.TP
+.B \-x FILE, \-command=FILE
+Execute GDB commands from file \c
+.I file\c
+\&.
 .SH "SEE ALSO"
 .RB "`\|" gdb "\|'"
 entry in
-- 
1.6.3.3

Re: [PATCH] gdb: gdb.1 - order options alphabetically in manual page

[Joel Brobecker]

> Motivation:
> 
>     Order of the options would follow the convention used in other GNU
>     programs lik Cf. cp(1), mv(1), etc.

I am not aware of any conflicting requirement regarding the order
that the GDB command-line switches have to follow in the man pages,
so your suggestion makes sense.

> I have assigned papers to FSF (Emacs). Please let me know if more is
> needed.

Unfortunately, I do not think that we can use your emacs assignment
for GDB code. The problem is that I have no idea if it is OK to accept
changes of this nature. Normally, the guidelines for accepting patches
without an assignment on file is that it should be 10 lines or less.
So your patch does not qualify. But on the other hand, it is the obvious
implementation of the idea of ordering the switches by alphabetical
order.

Does anyone know? Should I enquire?

-- 
Joel

Re: [PATCH] gdb: gdb.1 - order options alphabetically in manual page

[Daniel Jacobowitz]

On Wed, Sep 09, 2009 at 06:08:21PM -0700, Joel Brobecker wrote:
> Unfortunately, I do not think that we can use your emacs assignment
> for GDB code. The problem is that I have no idea if it is OK to accept
> changes of this nature. Normally, the guidelines for accepting patches
> without an assignment on file is that it should be 10 lines or less.
> So your patch does not qualify. But on the other hand, it is the obvious
> implementation of the idea of ordering the switches by alphabetical
> order.
> 
> Does anyone know? Should I enquire?

I'd say this was a non-copyrightable change, and thus acceptable.

http://www.gnu.org/prep/maintain/html_node/Legally-Significant.html#Legally-Significant

-- 
Daniel Jacobowitz
CodeSourcery

Re: [PATCH] gdb: gdb.1 - order options alphabetically in manual page

[Joel Brobecker]

> I'd say this was a non-copyrightable change, and thus acceptable.
> http://www.gnu.org/prep/maintain/html_node/Legally-Significant.html#Legally-Significant

I still wasn't sure from the section you are quoting that it was
acceptable. Are you saying that the idea of ordering the description
in alphabetical order is not copyrightable, and since there is only
one way to change the documentation to implement that idea, it is
obvious, and thus not copyrightable? Robert Dewar thinks that we should
require a proper assignment to accept this change...

-- 
Joel

Re: [PATCH] gdb: gdb.1 - order options alphabetically in manual page

[Eli Zaretskii]

> Date: Thu, 10 Sep 2009 15:52:02 -0700
> From: Joel Brobecker <brobecker@adacore.com>
> 
> > I'd say this was a non-copyrightable change, and thus acceptable.
> > http://www.gnu.org/prep/maintain/html_node/Legally-Significant.html#Legally-Significant
> 
> I still wasn't sure from the section you are quoting that it was
> acceptable. Are you saying that the idea of ordering the description
> in alphabetical order is not copyrightable, and since there is only
> one way to change the documentation to implement that idea, it is
> obvious, and thus not copyrightable? Robert Dewar thinks that we should
> require a proper assignment to accept this change...

I agree with Daniel that reordering existing text does not need a
copyright assignment.  But if we are not sure, we can ask RMS.

Re: [PATCH] gdb: gdb.1 - order options alphabetically in manual page

[Joel Brobecker]

> I agree with Daniel that reordering existing text does not need a
> copyright assignment.  But if we are not sure, we can ask RMS.

Do we have to go all the way to RMS? Or is there someone at the FSF
that handles this type of question?

-- 
Joel

Re: [PATCH] gdb: gdb.1 - order options alphabetically in manual page

[Eli Zaretskii]

> Date: Fri, 11 Sep 2009 16:17:47 -0700
> From: Joel Brobecker <brobecker@adacore.com>
> Cc: gdb-patches@sources.redhat.com
> 
> > I agree with Daniel that reordering existing text does not need a
> > copyright assignment.  But if we are not sure, we can ask RMS.
> 
> Do we have to go all the way to RMS? Or is there someone at the FSF
> that handles this type of question?

There is someone at the FSF, but I don't remember who that is, and I
find talking to RMS easier anyway.

Re: [PATCH] gdb: gdb.1 - order options alphabetically in manual page

[Joel Brobecker]

> There is someone at the FSF, but I don't remember who that is, and I
> find talking to RMS easier anyway.

OK. I've sent RMS an email aobut this.

-- 
Joel

Re: [PATCH] gdb: gdb.1 - order options alphabetically in manual page

[Daniel Jacobowitz]

On Sat, Sep 12, 2009 at 11:35:04AM -0700, Joel Brobecker wrote:
> > There is someone at the FSF, but I don't remember who that is, and I
> > find talking to RMS easier anyway.
> 
> OK. I've sent RMS an email aobut this.

Did you ever hear back about this question?

-- 
Daniel Jacobowitz
CodeSourcery

Re: [PATCH] gdb: gdb.1 - order options alphabetically in manual page

[Joel Brobecker]

> > OK. I've sent RMS an email aobut this.
> 
> Did you ever hear back about this question?

Yes I did. You were right, I believe, as order in this case is not
copyrightable.  However, the change introduced other changes which
were actually not OK, so I pointed them out.  We never heard back
from the author since :-(.

-- 
Joel

Re: [PATCH] gdb: gdb.1 - order options alphabetically in manual page

[Joel Brobecker]

> 2009-09-09  Jari Aalto  <jari.aalto@cante.net>
> 
> 	* gdb.1: Order options alphabetically.

One of the assignment officers at the FSF got back to me and said
that reordering was OK without a copyright assignement, but you also
seem to have made some changes on your own. For instance, you turned:

    -.TP
    -.BI "\-symbols=" "file"\c
    -.TP
    -.BI "\-s " "file"\c

Into:

    +.TP
    +.B -s FILE, \-symbols=FILE

As it turns out, I'm really wondering whether this is a correct change,
since the switch argument is no longer in italics. It seems to be the
convention that such arguments be in italics. Eli, what do you think?
What do others think?

In any case, I think that it's better to wait for the paperwork
to come through to accept your contribution (but please be ready
to restore the use of .BI instead of .B as explained above).

-- 
Joel

Re: [PATCH] gdb: gdb.1 - order options alphabetically in manual page

[Eli Zaretskii]

> Date: Wed, 16 Sep 2009 08:49:34 -0700
> From: Joel Brobecker <brobecker@adacore.com>
> Cc: gdb-patches@sources.redhat.com
> 
>     -.TP
>     -.BI "\-symbols=" "file"\c
>     -.TP
>     -.BI "\-s " "file"\c
> 
> Into:
> 
>     +.TP
>     +.B -s FILE, \-symbols=FILE
> 
> As it turns out, I'm really wondering whether this is a correct change,
> since the switch argument is no longer in italics. It seems to be the
> convention that such arguments be in italics. Eli, what do you think?

I think this part of the change is incorrect and should not be
installed.  The switch argument _should_ be in italics, since they are
a functional equivalent of Texinfo's @var, which TeX typesets in
italics or cursive.