This is the mail archive of the gdb-patches@sources.redhat.com mailing list for the GDB project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: [RFA]: Turn on Ada support


> From: Paul Hilfinger <hilfingr@gnat.com>
> Date: Tue,  8 Jun 2004 05:07:58 -0400 (EDT)
> 
> Eli, I have also included the relevant extract from our gdb.texinfo file.

Thanks.  A few minor comments are below.

> Not being sure how you'd like this handled, I have kept all our section 
> headers and inserted little bracketed comments to indicate missing portions.

I don't mind, provided that those placebos never see a GDB release: I
don't want to have a manual released with empty sections/nodes.  So if
you plan to finish them up before the next release, it's okay in the
meantime to have them in the form you left them.

> +While in Ada mode, you may use `@t{-}@t{-}' for comments.

Please say ``@t{--}'' here.

> +The other component-by-component array operations (@b{and}, @b{or}, 
> +@b{xor}, @b{not}, and relational tests other than equality)
> +are not implemented. 

Shouldn't we use @code instead of @b here?  These are operators,
i.e. symbols, right?

> +@code{@var{B}::@var{var}} means ``the variable named @var{var} that appears
> +in function or file @var{B}.''  When @var{B} is a file name, you must typically
> +surround it in single quotes.

What else can B be in this context?

> +in strings.   For example,
> +@example
> +   "One line.["0a"]Next line.["0a"]"
> +@end example
> +Contains an ASCII newline character (Ada.Characters.Latin_1.LF) after each
> +period.

You need a @noindent (alone on a separate line) after @end example,
and the text after that should begin with a lower-case letter, since
it's not a new sentence.

Also, we use @smallexample throughout the manual, so please change all
@example's to @smallexample.

> +@item
> +The subtype used as a prefix for the attributes @t{'Pos}, @t{'Min}, and
> +@t{'Max} is optional (and is ignored in any case).  For example, it is legal
> +to write

Please don't use "legal" here (or anywhere else in the manual), as
nothing in GDB usage can ever be against the law ;-).  The word
``valid'' is usually a good replacement.

> +@item
> +Since Ada is case-insensitive, the debugger normally maps identifiers you type 
> +to lower case.  The GNAT compiler uses upper-case characters for 
> +some of its internal identifiers, which are normally of no interest to users.
> +For the rare occasions when you actually have to look at them,
> +enclose them in angle brackets to avoid the lower-case mapping. 

This warrants a @cindex entry: people are bound to look for this
trick when they need it, so let's help them.

> +@node Stopping Before Main Program
> +@subsubsection Stopping at the Very Beginning
> +
> +It is sometimes necessary to debug the program during elaboration, and
> +before reaching the main procedure.
> +As defined in the Ada Reference
> +Manual, the elaboration code is invoked from a procedure called
> +@code{adainit}. To start your program until the beginning of the
> +elaboration, simply use the following two commands:
> +@code{tbreak adainit} and @code{run}.

Same here: let's index this.

> +@table @code
> +@item break exception

Every user command should be indexed with a @kindex.  (In this case,
it's sufficient to have a single "@kindex break exception" rather
than 2 entries, as these are variations of the same command.)

> +the exception name with its package name. In particular, if an entity

Please make sure there are 2 blanks after each dot that ends a
sentence.

> +On Ada implementations that use setjmp and longjmp

Shouldn't this be "In Ada implementations ..."?

> +@node Ada Tasks and Core Files
> +@subsubsection Tasking Support when Debugging Core Files
> +@cindex Ada, tasking, core

This cindex entry is better spelled "@cindex Ada, tasking, and core
files debugging".

> +It is not possible to refer to the original generic entities themselves
> +in GDB (there is no code to refer to), but it
      ^^^
This should be @value{GDBN}.

> +Besides the omissions listed previously (@pxref{Omissions from Ada}),
> +we know of several problems with and limitations of Ada mode in @value{GDBN}, 
> +some of which will be fixed with planned future releases of the debugger 
> +and the GNU Ada compiler.

This should say "as of @value{GDBN} version X.YY".  A year or two from
now, someone will have hard time updating this verbiage given the
changes in Ada support.

> +The type of the @t{'Address} attribute may not be @t{System.Address}.

I think you should use @code instead of @t in this and similar cases.

Thanks again for documenting the Ada support in such detailed form.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]