On Wednesday 12 November 2008 22:09:14 Eli Zaretskii wrote:
> > From: Vladimir Prus <vladimir@codesourcery.com>
> > Date: Wed, 12 Nov 2008 20:20:33 +0300
> > Cc: gdb-patches@sources.redhat.com
> > 
> > > Finally, this chapter seems to be not on design of MI, but more about
> > > advice to frontend implementors.  So I think it should be renamed
> > > accordingly, and some introductory text added to its beginning saying
> > > this is the intent of the chapter.
> > 
> > I don't quite agree. These section describes the main building blocks and 
> > concepts of GDB/MI, and is necessary to understand anything in GDB/MI
> > docs.
> 
> Right, but IMO that isn't "MI design", either.

Ok, what title would you suggest?

> > > It is best not to leave spaces around "---", the results look better
> > > in print.
> > 
> > Do you think you can summarize such style requirements for GDB manual somewhere?
> 
> The canonical place for such style conventions is the Texinfo manual.
> It has this advice (in the "Conventions" node):
> 
>    * Use three hyphens in a row, `---', to produce a long dash--like
>      this (called an "em dash"), used for punctuation in sentences.
> 
> Although it doesn't explicitly say to avoid spaces, it does avoid them
> itself.  I will ask the Texinfo maintainer to be more explicit about
> this.

Thanks.

> > I think they are very similar from frontend point of view -- in that frontend
> > does only minimal processing of those notification, and won't break if they
> > are not emitted.
> 
> That's okay, but it looks to me that after listing 3 items, it is best
> to have 3 @items, not 2.

I'm confused. There are 3 @items in that @itemize block. What change do you
want to me do?

> > > Whenever you first introduce a term, give it the @dfn markup, which
> > > will make stand out in the text.  In this case, since this term is
> > > explained elsewhere in the manual, it is also a good idea to add a
> > > @pxref to that other node.
> > 
> > Actually, we don't have a section for CLI async mode, we have a section
> > for CLI non-stop mode.
> 
> Sorry, I don't follow.  I meant the node "Background Execution".

Ah, I've grepped for "Asynchronous" and found none. I've added pxref to this.

> > > > +that even commands that operate on global state (like global
> > > > +variables, or breakpoints), still access the target in the context of
> > > > +a specific thread
> > > 
> > > What do you mean by "global variables" here?  As written, the text
> > > seems to say that global variables and breakpoints are commands, or
> > > maybe global state, which doesn't sound right to me.  "Breakpoints"
> > > could be replaced with "breakpoint commands", but I don't know what
> > > replacement to suggest for "global variables".
> > 
> > global variables, and breakpoints, are examples of the "global state"
> > that GDB commands can operate on.
> 
> What GDB commands operate on global variables?

Say, 'print' and 'set' can operate on global variables.

> > > >                    so frontend should try perform such operations on a
> > > > +stopped thread.
> > > 
> > > I don't see how this conclusion follows from the fact that commands
> > > access the target in the context of some thread.  Why doing that "on a
> > > stopped thread" will solve whatever problem you are trying to explain
> > > here? and what does "operations ON a stopped thread" mean in this
> > > context, anyway?
> > 
> > ... and with the explanation above, if doing operations in context of running
> > thread may fail even if that operation only accesses global state, the frontend
> > better pick a thread that is stopped.
> 
> Do you mean that a frontend should do the equivalent of "thread N"
> where N is an ID of a thread that is stopped, before issuing commands?
> If so, let's say that explicitly.  "Pick a thread that is stopped" is
> not clear enough, at least it confuses me.

I mean that frontend should select a stopped thread, and pass id of that
thread using the --thread option. I've clarified this.

> > > > +@smallexample
> > > > +(gdb)
> > > 
> > > This should be @value{GDBP}, I think.
> > 
> > OOC, what practical differences or benefits that will have?
> 
> I understand that both GDBN and GDBP exist so that a manual could be
> easily produced for a customized version of GDB that calls itself
> "gdbfoo" and prompts with "(gdb-foo)", say.  Anyway, this goes way
> back before I assumed the responsibility on the GDB docs; perhaps Stan
> or other old-timers could add some insights.

OK.

> > Thanks for feedback. I attach both the revised version of the patch, and the delta
> > relatively to the previous version.
> 
> The new version is fine, except that there are still instances of only
> one space after a period that ends a sentence.

I've just went though MI section with a regexp, fixing this issue. I'm attaching
another revision. I believe the remaining two outstanding issues are name of
the section, and that @item question above I did not understand. 

Thanks a lot for review!

- Volodya