This is the mail archive of the
gdb-patches@sources.redhat.com
mailing list for the GDB project.
Re: [RFA]: Turn on Ada support
- From: "Eli Zaretskii" <eliz at gnu dot org>
- To: Paul Hilfinger <hilfingr at gnat dot com>
- Cc: gdb-patches at sources dot redhat dot com
- Date: Wed, 09 Jun 2004 01:12:07 +0200
- Subject: Re: [RFA]: Turn on Ada support
- References: <20040608090758.C59CAF2940@nile.gnat.com>
- Reply-to: Eli Zaretskii <eliz at gnu dot org>
> 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.