Implement -exec-jump

Implement -exec-jump

[Vladimir Prus]

This patch, committed, implements the -exec-jump MI command.
(Documentation follows later)

- Volodya

Index: gdb/ChangeLog
===================================================================
RCS file: /cvs/src/src/gdb/ChangeLog,v
retrieving revision 1.10357
diff -u -p -r1.10357 ChangeLog
--- gdb/ChangeLog	5 Apr 2009 22:37:19 -0000	1.10357
+++ gdb/ChangeLog	8 Apr 2009 05:48:34 -0000
@@ -1,3 +1,11 @@
+2009-04-08  Vladimir Prus  <vladimir@codesourcery.com>
+
+	Implement -exec-jump.
+
+	* mi/mi-cmds.h (mi_cmd_exec_jump): Declare.
+	* mi/mi-main.c (mi_cmd_exec_jump): New.
+	* mi/mi-cmds.c (mi_cmds): Register exec-jump.
+
 2009-04-06  Mark Kettenis  <kettenis@gnu.org>
 
 	* sparc64nbsd-nat.c (sparc64nbsd_supply_pcb): Fix comment.
Index: gdb/mi/mi-cmds.c
===================================================================
RCS file: /cvs/src/src/gdb/mi/mi-cmds.c,v
retrieving revision 1.38
diff -u -p -r1.38 mi-cmds.c
--- gdb/mi/mi-cmds.c	3 Jan 2009 05:57:57 -0000	1.38
+++ gdb/mi/mi-cmds.c	8 Apr 2009 05:48:34 -0000
@@ -61,6 +61,7 @@ struct mi_cmd mi_cmds[] =
   { "exec-arguments", { "set args", 1 }, NULL },
   { "exec-continue", { NULL, 0 }, mi_cmd_exec_continue},
   { "exec-finish", { NULL, 0 }, mi_cmd_exec_finish},
+  { "exec-jump", { NULL, 0 }, mi_cmd_exec_jump},
   { "exec-interrupt", { NULL, 0 }, mi_cmd_exec_interrupt},
   { "exec-next", { NULL, 0 }, mi_cmd_exec_next},
   { "exec-next-instruction", { NULL, 0 }, mi_cmd_exec_next_instruction},
Index: gdb/mi/mi-cmds.h
===================================================================
RCS file: /cvs/src/src/gdb/mi/mi-cmds.h,v
retrieving revision 1.36
diff -u -p -r1.36 mi-cmds.h
--- gdb/mi/mi-cmds.h	3 Jan 2009 05:57:57 -0000	1.36
+++ gdb/mi/mi-cmds.h	8 Apr 2009 05:48:34 -0000
@@ -53,6 +53,7 @@ extern mi_cmd_argv_ftype mi_cmd_env_path
 extern mi_cmd_argv_ftype mi_cmd_env_pwd;
 extern mi_cmd_argv_ftype mi_cmd_exec_continue;
 extern mi_cmd_argv_ftype mi_cmd_exec_finish;
+extern mi_cmd_argv_ftype mi_cmd_exec_jump;
 extern mi_cmd_argv_ftype mi_cmd_exec_next;
 extern mi_cmd_argv_ftype mi_cmd_exec_next_instruction;
 extern mi_cmd_argv_ftype mi_cmd_exec_return;
Index: gdb/mi/mi-main.c
===================================================================
RCS file: /cvs/src/src/gdb/mi/mi-main.c,v
retrieving revision 1.146
diff -u -p -r1.146 mi-main.c
--- gdb/mi/mi-main.c	25 Mar 2009 21:42:35 -0000	1.146
+++ gdb/mi/mi-main.c	8 Apr 2009 05:48:34 -0000
@@ -168,6 +168,13 @@ mi_cmd_exec_return (char *command, char 
   print_stack_frame (get_selected_frame (NULL), 1, LOC_AND_ADDRESS);
 }
 
+void
+mi_cmd_exec_jump (char *args, char **argv, int argc)
+{
+  /* FIXME: Should call a libgdb function, not a cli wrapper.  */
+  return mi_execute_async_cli_command ("jump", argv, argc);
+}
+ 
 static int
 proceed_thread_callback (struct thread_info *thread, void *arg)
 {

Re: Implement -exec-jump

[Eli Zaretskii]

> From: Vladimir Prus <vladimir@codesourcery.com>
> Date: Wed, 8 Apr 2009 09:50:16 +0400
> 
> 
> This patch, committed, implements the -exec-jump MI command.
> (Documentation follows later)

Please don't commit patches without the docs to go with them.  Many
people (and even distributions) use development snapshots or the CVS
directly these days, and I would like to avoid the situation where
they get features without documentation.  I think we all should want
this.

It is okay to _post_ a patch for review saying that the documentation
patch will be _posted_ later, but actually _committing_ the code part
is something very different.

Thanks.

Re: Implement -exec-jump

[Vladimir Prus]

On Wednesday 08 April 2009 10:53:22 Eli Zaretskii wrote:
> > From: Vladimir Prus <vladimir@codesourcery.com>
> > Date: Wed, 8 Apr 2009 09:50:16 +0400
> > 
> > 
> > This patch, committed, implements the -exec-jump MI command.
> > (Documentation follows later)
> 
> Please don't commit patches without the docs to go with them.  Many
> people (and even distributions) use development snapshots or the CVS
> directly these days, and I would like to avoid the situation where
> they get features without documentation.  I think we all should want
> this.

Don't you think that if some person, or distribution, grabs random state
from CVS, he should be capable of judging what he gets? If he is 
incapable of such judgement, it is his problem.

> It is okay to _post_ a patch for review saying that the documentation
> patch will be _posted_ later, but actually _committing_ the code part
> is something very different.

Is this rule documented anywhere? And if it is, it is a very inconvenient 
rule. It is much easier for me to find two chunks of time for code and 
documentation separately, rather than finding large chunk of time to do
them both -- to the point where I might not be able to fix such small
issues at all. Do you think having a window of time where *development version*
has an undocumented feature that is primary targeted at *frontend developers*
is worse than not having that feature at all?

- Volodya

Re: Implement -exec-jump

[Eli Zaretskii]

> From: Vladimir Prus <vladimir@codesourcery.com>
> Date: Wed, 8 Apr 2009 11:08:16 +0400
> Cc: gdb-patches@sources.redhat.com
> 
> > It is okay to _post_ a patch for review saying that the documentation
> > patch will be _posted_ later, but actually _committing_ the code part
> > is something very different.
> 
> Is this rule documented anywhere?

I don't know, and I didn't know every request needs a documented rule.

I at least thought it was an accepted truism that we as a team don't
want undocumented features.

> Do you think having a window of time where *development version*
> has an undocumented feature that is primary targeted at *frontend developers*
> is worse than not having that feature at all?

Yes, that's what I think.

Re: Implement -exec-jump

[Vladimir Prus]

On Wednesday 08 April 2009 11:20:43 Eli Zaretskii wrote:
> > From: Vladimir Prus <vladimir@codesourcery.com>
> > Date: Wed, 8 Apr 2009 11:08:16 +0400
> > Cc: gdb-patches@sources.redhat.com
> > 
> > > It is okay to _post_ a patch for review saying that the documentation
> > > patch will be _posted_ later, but actually _committing_ the code part
> > > is something very different.
> > 
> > Is this rule documented anywhere?
> 
> I don't know, and I didn't know every request needs a documented rule.

I believe that a development process that is based on a list of documented
rules or guidelines is in general more smooth, than one that relies on
ad-hoc requests.

> I at least thought it was an accepted truism that we as a team don't
> want undocumented features.

I though there's "in a published release" somewhere in the above statement.

> > Do you think having a window of time where *development version*
> > has an undocumented feature that is primary targeted at *frontend developers*
> > is worse than not having that feature at all?
> 
> Yes, that's what I think.

I am 100% sure that both the person who filed the issue this patch
has fixed, and every single frontend developer, will disagree. And that's
why it would be best to have documented rules -- so that those rules can
be established once and we would not spend any more time discussing them.
(Even if such established rules increase an already-high overhead of GDB
hacking to the degree where I won't be able to fix such small bugs).

- Volodya

Re: Implement -exec-jump

[Eli Zaretskii]

> From: Vladimir Prus <vladimir@codesourcery.com>
> Date: Wed, 8 Apr 2009 11:36:09 +0400
> Cc: gdb-patches@sources.redhat.com
> 
> On Wednesday 08 April 2009 11:20:43 Eli Zaretskii wrote:
> > > From: Vladimir Prus <vladimir@codesourcery.com>
> > > Date: Wed, 8 Apr 2009 11:08:16 +0400
> > > Cc: gdb-patches@sources.redhat.com
> > > 
> > > > It is okay to _post_ a patch for review saying that the documentation
> > > > patch will be _posted_ later, but actually _committing_ the code part
> > > > is something very different.
> > > 
> > > Is this rule documented anywhere?
> > 
> > I don't know, and I didn't know every request needs a documented rule.
> 
> I believe that a development process that is based on a list of documented
> rules or guidelines is in general more smooth, than one that relies on
> ad-hoc requests.

That's fine with me, but I don't think it means that a request outside
written rules should be automatically rejected just because it isn't
documented.  Our process is just barely documented, so building on
that alone would make our work and cooperation much harder than it
needs to be.

A request to commit changes with docs is not different from a request
to have a test case for each new feature.  I think we should do both.

> > I at least thought it was an accepted truism that we as a team don't
> > want undocumented features.
> 
> I though there's "in a published release" somewhere in the above statement.

That's exactly the point: the release of GDB 7.0 is quite close.
Since we don't have any means to track such issues, you are now
effectively asking me to somehow make sure the appropriate
documentation patch is committed before the release, preferably before
the branch.  I don't have enough free resources to do that, so chances
are we will release GDB 7.0 with this feature undocumented.

I'm talking from experience here, it's not just a theory.  You will
see in the logs that around April 2005 I made several massive changes
to the manual, all of them to document commands and features that were
left undocumented because of lax policies regarding documentation.  I
don't want us to be in such a bad situation ever again, and I don't
have any means of preventing that except by asking that code and
documentation always go together.

> > > Do you think having a window of time where *development version*
> > > has an undocumented feature that is primary targeted at *frontend developers*
> > > is worse than not having that feature at all?
> > 
> > Yes, that's what I think.
> 
> I am 100% sure that both the person who filed the issue this patch
> has fixed, and every single frontend developer, will disagree. And that's
> why it would be best to have documented rules -- so that those rules can
> be established once and we would not spend any more time discussing them.

Well, my rules are spelled out above.  If no one objects, I volunteer
to add them to MAINTAINERS.

> (Even if such established rules increase an already-high overhead of GDB
> hacking to the degree where I won't be able to fix such small bugs).

Frankly, I don't understand why: the particular feature you added now
does not need more than a few lines added to the manual.  Even just
mentioning the command with minimal documentation and a FIXME for
later would be good enough at this point.

In addition, I said many times in the past that if Texinfo and other
technicalities are a burden, contributors can post the documentation
in plain text in their own words, and I will convert them to valid
Texinfo and reword as necessary.  If that makes the burden easier, I'm
here to make good on my promises.

A bit of good will is all I need to make this happen.

Re: Implement -exec-jump

[André Pönitz]

On Wednesday 08 April 2009 09:20:43 Eli Zaretskii wrote:
> > From: Vladimir Prus <vladimir@codesourcery.com>
> [...]
> > Do you think having a window of time where *development version*
> > has an undocumented feature that is primary targeted at *frontend developers*
> > is worse than not having that feature at all?
> 
> Yes, that's what I think.

I disagree. From my point of view ("frontend developer") it is much 
more important that the mi interface works "somehow", preferably
covering 100% of the CLI functionality. At worst, I have to look up 
the exact syntax to use in the sources. No big deal.

[The opposite scenario, i.e. existing documentation, pointing to 
unimplemented features, is much worse, though.]

Regards,
Andre'

Re: Implement -exec-jump

[Eli Zaretskii]

> From: =?utf-8?q?Andr=C3=A9_P=C3=B6nitz?= <andre.poenitz@nokia.com>
> Date: Wed, 8 Apr 2009 10:16:41 +0100
> 
> On Wednesday 08 April 2009 09:20:43 Eli Zaretskii wrote:
> > > From: Vladimir Prus <vladimir@codesourcery.com>
> > [...]
> > > Do you think having a window of time where *development version*
> > > has an undocumented feature that is primary targeted at *frontend developers*
> > > is worse than not having that feature at all?
> > 
> > Yes, that's what I think.
> 
> I disagree.

Well, you are not responsible for the GDB documentation; I am.

If we are going to allow committing undocumented code, I would ask to
install some procedures to make sure it gets documented eventually.
For now, I don't have any practical suggestion for such procedures,
and I cannot be responsible for a job that other maintainers and
contributors are preventing me to do well.  Please be fair and
understand where I'm coming from.

> At worst, I have to look up the exact syntax to use in the
> sources. No big deal.

Then why have the manual in the first place?  Let them use the
sources.

Re: Implement -exec-jump

[André Pönitz]

On Wednesday 08 April 2009 11:26:49 ext Eli Zaretskii wrote:
> > From: =?utf-8?q?Andr=C3=A9_P=C3=B6nitz?= <andre.poenitz@nokia.com>
> > On Wednesday 08 April 2009 09:20:43 Eli Zaretskii wrote:
> > > > From: Vladimir Prus <vladimir@codesourcery.com>
> > > [...]
> > > > Do you think having a window of time where *development version*
> > > > has an undocumented feature that is primary targeted at *frontend developers*
> > > > is worse than not having that feature at all?
> > > 
> > > Yes, that's what I think.
> > 
> > I disagree.
> 
> Well, you are not responsible for the GDB documentation; I am.

I am a potential user of the feature being discussed.

Vladimir was making a statement on what a frontend developer
is likely to prefer: A feature that is undocumented for a limited
in the development tree _or_ the possibility that the feature does
not get implemented at all.

> If we are going to allow committing undocumented code, I would ask to
> install some procedures to make sure it gets documented eventually.
> For now, I don't have any practical suggestion for such procedures,
> and I cannot be responsible for a job that other maintainers and
> contributors are preventing me to do well.  Please be fair and
> understand where I'm coming from.

I think I fully understand your position, and also that it is the 
"natural stance" for a documentation maintainer. It's just that 
I do not agree with it.

I personally pretty much prefer progress on the MI implementation
side, if that means a few days delay on the documentation,
(or even a small risk of having no documentation at all(!)),
so I am _personally_ fine with it.

> > At worst, I have to look up the exact syntax to use in the
> > sources. No big deal.
> 
> Then why have the manual in the first place?  Let them use the
> sources.

That's a interesting proposal. There is so much stuff, basic stuff 
even, undocumented, so Joe Frontend has to read the sources 
anyway.

As an example: The quoting rules for the CLI are completely 
opaque, but, giving the de-facto non-existence of a binary
interface to gdb, crucial for any frontend.  A frontend can
not just go "type a command" - "hey, gdb does not like it, so 
try to put in a quote or two"...

Regards,
Andre'

Re: Implement -exec-jump

[Eli Zaretskii]

> From: =?iso-8859-1?q?Andr=E9_P=F6nitz?= <andre.poenitz@nokia.com>
> Date: Wed, 8 Apr 2009 12:05:41 +0100
> 
> I personally pretty much prefer progress on the MI implementation
> side, if that means a few days delay on the documentation,
> (or even a small risk of having no documentation at all(!)),
> so I am _personally_ fine with it.

If that turns out to be the opinion of the majority of GDB users, I'll
probably resign as the docs maintainer, because putting in all those
efforts when no one needs them is waste of my scarce free time.

> That's a interesting proposal. There is so much stuff, basic stuff 
> even, undocumented, so Joe Frontend has to read the sources 
> anyway.

As long as I am responsible for the documentation here, I urge you to
report any such cases, and I will try to improve the docs as well as I
can.

> As an example: The quoting rules for the CLI are completely 
> opaque, but, giving the de-facto non-existence of a binary
> interface to gdb, crucial for any frontend.  A frontend can
> not just go "type a command" - "hey, gdb does not like it, so 
> try to put in a quote or two"...

Typing "i quot TAB" in the Info reader of the GDB manual brings up the
"quotes in commands" index entry, which leads to a place that has some
documentation of quoting.  I'm not saying that this is what you need,
but please tell what details are missing from what it says there.

Re: Implement -exec-jump

[Tom Tromey]

>>>>> "Eli" == Eli Zaretskii <eliz@gnu.org> writes:

Vladimir> I though there's "in a published release" somewhere in the
Vladimir> above statement.

Eli> That's exactly the point: the release of GDB 7.0 is quite close.
Eli> Since we don't have any means to track such issues, you are now
Eli> effectively asking me to somehow make sure the appropriate
Eli> documentation patch is committed before the release, preferably before
Eli> the branch.

If we want, we can use Bugzilla to track release blockers.
There are a few options for the mechanics of this.

In this particular case, I'd imagine that the documentation patch is
not much longer than the Bugzilla entry though :-)

Tom

Re: Implement -exec-jump

[Tom Tromey]

>>>>> "André" == André Pönitz <andre.poenitz@nokia.com> writes:

André> [The opposite scenario, i.e. existing documentation, pointing to 
André> unimplemented features, is much worse, though.]

I agree that documenting unimplemented features is a bad practice.  If
you know of specific cases like this, please file a bug.  I think we
need a "documentation" component in Bugzilla, I'm surprised that there
isn't one.

Tom

Re: Implement -exec-jump

[Thiago Jung Bauermann]

El mié, 08-04-2009 a las 12:26 +0300, Eli Zaretskii escribió:
> > From: =?utf-8?q?Andr=C3=A9_P=C3=B6nitz?= <andre.poenitz@nokia.com>
> > Date: Wed, 8 Apr 2009 10:16:41 +0100
> > 
> > On Wednesday 08 April 2009 09:20:43 Eli Zaretskii wrote:
> > > > From: Vladimir Prus <vladimir@codesourcery.com>
> > > [...]
> > > > Do you think having a window of time where *development version*
> > > > has an undocumented feature that is primary targeted at *frontend developers*
> > > > is worse than not having that feature at all?
> > > 
> > > Yes, that's what I think.
> > 
> > I disagree.
> 
> Well, you are not responsible for the GDB documentation; I am.
> 
> If we are going to allow committing undocumented code, I would ask to
> install some procedures to make sure it gets documented eventually.

I agree with Eli here. If we don't have a mechanism of ensuring that
documentation will get written before a release, we should enforce that
features always be committed with documentation.

OTOH, if we agree that it's acceptable to have a time window where CVS
HEAD has undocumented features (as long official releases are always
documented), then I think we should discuss those mechanisms, since as
Vladimir and André say, it does help GDB development moving forward.

> For now, I don't have any practical suggestion for such procedures,

Like Tromey said, one way to do it would be to enforce opening a
documentation bug in bugzilla everytime an undocumented feature is
committed, and marking those bugs as release-blocking.

Then we should agree that a GDB release can only be made after all
blocking bugs are closed (boy I *am* smart, am I not?).

Another way to do it would be to add pending items to a GDB release wiki
page. Joel already uses this, in fact. So it's the easiest to implement.
-- 
[]'s
Thiago Jung Bauermann
IBM Linux Technology Center

Re: Implement -exec-jump

[Joel Brobecker]

> Another way to do it would be to add pending items to a GDB release wiki
> page. Joel already uses this, in fact. So it's the easiest to implement.

This mechanism is fine as far as I am concerned.

-- 
Joel

Re: Implement -exec-jump

[Thiago Jung Bauermann]

El mié, 08-04-2009 a las 09:53 +0300, Eli Zaretskii escribió:
> Please don't commit patches without the docs to go with them.  Many
> people (and even distributions) use development snapshots or the CVS
> directly these days

Just a comment on this: I believe people and distributions are adopting
this practice because 6.8 is already so old, and there are many fixes
and features in HEAD since then.

Even though I agreed when we decided to delay the next release for 6
months, I must say I now think it brought more trouble than benefits...

Well, you live and learn, they say. :-)
-- 
[]'s
Thiago Jung Bauermann
IBM Linux Technology Center

Re: Implement -exec-jump

[Eli Zaretskii]

> Date: Wed, 8 Apr 2009 14:57:44 -0700
> From: Joel Brobecker <brobecker@adacore.com>
> Cc: Eli Zaretskii <eliz@gnu.org>, Andr? P?nitz <andre.poenitz@nokia.com>, 	gdb-patches@sources.redhat.com
> 
> > Another way to do it would be to add pending items to a GDB release wiki
> > page. Joel already uses this, in fact. So it's the easiest to implement.
> 
> This mechanism is fine as far as I am concerned.

I'd agree to that as a fallback, but I'd prefer to codify the current
unwritten practice that code patches come with docs patches.

The reason is that deferring documentation to when a release is
impending would almost certainly mean that documentation in general
and my free time in particular will be a roadblock on the way to a
release.  Also, some of the contributors might not be available then,
which means we will have a dilemma: either release undocumented
features or try to document them by someone who knows much less than
the original author of the code.

We had no problems until now with requesting docs (and a test case)
together with the code.  Why should we deviate from that now?

Re: Implement -exec-jump

[Tom Tromey]

>>>>> "Eli" == Eli Zaretskii <eliz@gnu.org> writes:

Eli> We had no problems until now with requesting docs (and a test case)
Eli> together with the code.  Why should we deviate from that now?

I agree.

I think we should strive to keep standards high, where they matter.
Documentation and test cases fall into this category.

I realize this adds a cost to many patches; I feel this pain myself.

Tom

Re: Implement -exec-jump

[Vladimir Prus]

On Wednesday 08 April 2009 09:50:16 Vladimir Prus wrote:
> 
> This patch, committed, implements the -exec-jump MI command.
> (Documentation follows later)

Here's the doc patch. OK?

- Volodya

Index: gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.583
diff -u -p -r1.583 gdb.texinfo
--- gdb.texinfo	22 Apr 2009 06:09:18 -0000	1.583
+++ gdb.texinfo	22 Apr 2009 12:08:23 -0000
@@ -21396,6 +21396,31 @@ fullname="/home/foo/bar/try.c",line="13"
 (gdb)
 @end smallexample
 
+@subheading The @code{-exec-jump} Command
+@findex -exec-jump
+
+@subsubheading Synopsis
+
+@smallexample
+ -exec-jump @var{location}
+@end smallexample
+
+Resumes execution of the inferior program at the location specified by
+parameter. @xref{Specify Location}, for a description of the
+different forms of @var{location}.
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{jump}.
+
+@subsubheading Example
+
+@smallexample
+-exec-jump foo.c:10
+*running,thread-id="all"
+^running
+@end smallexample
+
 
 @subheading The @code{-exec-next} Command
 @findex -exec-next

Re: Implement -exec-jump

[Vladimir Prus]

On Wednesday 08 April 2009 12:56:19 Eli Zaretskii wrote:

> > > > > It is okay to _post_ a patch for review saying that the documentation
> > > > > patch will be _posted_ later, but actually _committing_ the code part
> > > > > is something very different.
> > > > 
> > > > Is this rule documented anywhere?
> > > 
> > > I don't know, and I didn't know every request needs a documented rule.
> > 
> > I believe that a development process that is based on a list of documented
> > rules or guidelines is in general more smooth, than one that relies on
> > ad-hoc requests.
> 
> That's fine with me, but I don't think it means that a request outside
> written rules should be automatically rejected just because it isn't
> documented.  Our process is just barely documented, so building on
> that alone would make our work and cooperation much harder than it
> needs to be.

Sorry, I'm don't follow. It would take you a couple of minutes to document,
somewhere, whatever you've said in this thread, and this will make future
development process more smooth. Am I wrong?

> A request to commit changes with docs is not different from a request
> to have a test case for each new feature.  I think we should do both.

On tests, I similarly don't think that an overly strict approach will
not hurt. Sometimes, having tests checked in later is better approach
overall.

> > > I at least thought it was an accepted truism that we as a team don't
> > > want undocumented features.
> > 
> > I though there's "in a published release" somewhere in the above statement.
> 
> That's exactly the point: the release of GDB 7.0 is quite close.
> Since we don't have any means to track such issues, 

We both have the Wiki page for release (than Joel used in past to poke me)
and we have a bugtracker (which, now, is actually sane).

> you are now
> effectively asking me to somehow make sure the appropriate
> documentation patch is committed before the release, preferably before
> the branch.  I don't have enough free resources to do that, so chances
> are we will release GDB 7.0 with this feature undocumented.

I don't effectively ask anything of above, and it's only the case if you
assume I'll be run by a bus soonish -- and I suspect one undocumented MI
command for every GDB committer that is run by a bus would not be a big
disaster.

> I'm talking from experience here, it's not just a theory.  You will
> see in the logs that around April 2005 I made several massive changes
> to the manual, all of them to document commands and features that were
> left undocumented because of lax policies regarding documentation.  I
> don't want us to be in such a bad situation ever again, and I don't
> have any means of preventing that except by asking that code and
> documentation always go together.

As you can see in the same logs, since my first doc patch went in 
on 2006-02-06, I've checked in a total of 41 patches (1/8 of the total),
including docs for preexisting behaviour. And some of the other doc
patches were committed independently from original code patch. So,
I somehow doubt that in my particular case, making me commit code and doc
patches always together will serve any purpose.

> > > > Do you think having a window of time where *development version*
> > > > has an undocumented feature that is primary targeted at *frontend developers*
> > > > is worse than not having that feature at all?
> > > 
> > > Yes, that's what I think.
> > 
> > I am 100% sure that both the person who filed the issue this patch
> > has fixed, and every single frontend developer, will disagree. And that's
> > why it would be best to have documented rules -- so that those rules can
> > be established once and we would not spend any more time discussing them.
> 
> Well, my rules are spelled out above.  If no one objects, I volunteer
> to add them to MAINTAINERS.
> 
> > (Even if such established rules increase an already-high overhead of GDB
> > hacking to the degree where I won't be able to fix such small bugs).
> 
> Frankly, I don't understand why: the particular feature you added now
> does not need more than a few lines added to the manual.  

Right:
- the lines have to written
- the output in PDF and that other format must be expected for correctness
  (as you remember, a couple of my prior patches looked just fine only in
   BTW)
- you might want to tweak some formatting bit
- changelog has to be written

If you add quite some time for context switching there, you should understand
why I reluctant to do this in the final week of a release cycle of our product.


> Even just
> mentioning the command with minimal documentation and a FIXME for
> later would be good enough at this point.

Do you have a mechanism to track FIXMEs in documentation, so that GDB 7.0
is not released with FIXMEs in documentation?

> In addition, I said many times in the past that if Texinfo and other
> technicalities are a burden, contributors can post the documentation
> in plain text in their own words, and I will convert them to valid
> Texinfo and reword as necessary.  If that makes the burden easier, I'm
> here to make good on my promises.

Frankly, I was never comfortable with the idea of posting "sketch" patches
for you to do the real work. However, if you prefer to see and work on
sketch patch yourself, rather than getting a fully worked-out patch later,
that's your call.

> A bit of good will is all I need to make this happen.

You might want to note that the patch for -exec-jump docs was now posted,
and we're not even that close to branch point.

- Volodya

Re: Implement -exec-jump

[Eli Zaretskii]

> From: Vladimir Prus <vladimir@codesourcery.com>
> Date: Wed, 22 Apr 2009 16:09:19 +0400
> 
> Here's the doc patch. OK?

Yes, but please leave two spaces after the period that ends a sentence

> +Resumes execution of the inferior program at the location specified by
> +parameter. @xref{Specify Location}, for a description of the
            ^^
here.

Thanks.

Re: Implement -exec-jump

[Eli Zaretskii]

> From: Vladimir Prus <vladimir@codesourcery.com>
> Date: Wed, 22 Apr 2009 16:57:49 +0400
> Cc: gdb-patches@sources.redhat.com
> 
> > > I believe that a development process that is based on a list of documented
> > > rules or guidelines is in general more smooth, than one that relies on
> > > ad-hoc requests.
> > 
> > That's fine with me, but I don't think it means that a request outside
> > written rules should be automatically rejected just because it isn't
> > documented.  Our process is just barely documented, so building on
> > that alone would make our work and cooperation much harder than it
> > needs to be.
> 
> Sorry, I'm don't follow. It would take you a couple of minutes to document,
> somewhere, whatever you've said in this thread, and this will make future
> development process more smooth. Am I wrong?

No, you are not wrong.  However, my point was that we don't need (and
in practice, cannot) rely on documented rules alone.

> > A request to commit changes with docs is not different from a request
> > to have a test case for each new feature.  I think we should do both.
> 
> On tests, I similarly don't think that an overly strict approach will
> not hurt. Sometimes, having tests checked in later is better approach
> overall.

I think the majority here thinks otherwise.

> I somehow doubt that in my particular case, making me commit code and doc
> patches always together will serve any purpose.

It eases the burden, that's all.  We are all busy people.

> > Even just
> > mentioning the command with minimal documentation and a FIXME for
> > later would be good enough at this point.
> 
> Do you have a mechanism to track FIXMEs in documentation, so that GDB 7.0
> is not released with FIXMEs in documentation?

FIXME in a comment is not visible in the produced manual.  What I was
trying to say was that some minimal documentation is infinitely better
than no documentation.

> > In addition, I said many times in the past that if Texinfo and other
> > technicalities are a burden, contributors can post the documentation
> > in plain text in their own words, and I will convert them to valid
> > Texinfo and reword as necessary.  If that makes the burden easier, I'm
> > here to make good on my promises.
> 
> Frankly, I was never comfortable with the idea of posting "sketch" patches
> for you to do the real work.

It's an offer; if you are uncomfortable with it, you don't have to
take it.  But if it will help us get documentation in time, the effort
is worthwhile for me.

> You might want to note that the patch for -exec-jump docs was now posted,
> and we're not even that close to branch point.

Thank you.