Re: [RFA 4/4 doc] Explicit locations

[Eli Zaretskii <eliz at gnu dot org>]

> Date: Wed, 19 Jun 2013 15:45:47 -0700
> From: Keith Seitz <keiths@redhat.com>
> CC: gdb-patches@sourceware.org
> 
> >> +@table @code
> >> +@item -source
> >> +The value specifies the source file name.  This option
> >> +requires the use of either @code{-function} or @code{-line}.
> >
> > I think this should explain how to specify a file name unambiguously
> > (after all, this is what explicit locations are all about, right?).
> > For example, what if only a basename is specified? how to specify the
> > file name when several different files in the source tree have the
> > same basename?
> 
> I've made an attempt at this. It probably needs a little more work, 
> though, and the eyes of an outsider.

It looks fine to me.

> +#define LOCATION_HELP_STRING \
> +"Linespecs are a colon-separated list of location parameters, such as\n\

"Linespecs are colon-separated lists", in plural.

> +Address locations begin with \"*\" and specify an exact address in the.\n\
                                                                         ^
That period should be removed.

> +program.  Example: To specify the fourth byte past the start function\n\
> +\"main\",use \"*main + 4\".\n\
           ^
Space before the comma here.

> -LOCATION may be a line number, function name, or \"*\" and an address.\n\
> -If a line number is specified, break at start of code for that line.\n\
> -If a function is specified, break at start of code for that function.\n\
> -If an address is specified, break at that exact address.\n\
> +LOCATION may be a linespec, address, or explicit location.\n\
> +\n" LOCATION_HELP_STRING "\n\
>   With no LOCATION, uses current execution address of the selected\n\
>   stack frame.  This is useful for breaking on return to a stack frame.\n\
>   \n\

I would move the "With no LOCATION ..." part before
LOCATION_HELP_STRING, since the latter is long.  You can add
"as described below" to the preceding sentence, to make the reference
more explicit.

> +Clear breakpoint at specified location.\n\
> +Argument may be a linespec, explicit, or address location.\n\
> +\n" LOCATION_HELP_STRING "\n\
>   With no argument, clears all breakpoints in the line that the selected 
> frame\n\
>   is executing in.\n\
>   \n\

Likewise here (and elsewhere).

> +Locations may be specified using three different formats,
> +linespec locations, explicit locations, or address locations.

I would put a colon after "Different formats", not a comma.

> +sources.  In these cases, explicit locations point to the source
> +line you meant more accurately and unequivocally.  Also, using
                                      ^^^^^^^^^^^^^
I would use "unambiguously" here.

> +For example, the linespec ``foo:bar'' may refer to a function ``bar''
> +defined in the file named ``foo'' or the label ``bar'' in a function
> +named ``foo''.  @value{GDBN} must search either the file system or

The markup here is incorrect.  Drop the quotes, and use @file for file
names, @code for functions and labels, and @samp for everything else,
like @samp{foo:bar}.

> +@table @code
> +@item -source
> +The value specifies the source file name.  To differentiate between

I would use a more explicit

 @item -source @var{filename}

(and similarly for other options), like you did in the MI sections.
Otherwise, the only place where you hint on the format is the sentence
about "option-value pairs", and without an example this is not enough.
Btw, adding an example would be great.

> +to uniquely identify the desired file, e.g., ``foo/bar/baz.c''.  Otherwise
                                                ^^^^^^^^^^^^^^^^^
Drop the quotes and use @file markup for file names.

>   @smallexample
>    -break-insert [ -t ] [ -h ] [ -f ] [ -d ] [ -a ]
>       [ -c @var{condition} ] [ -i @var{ignore-count} ]
> -    [ -p @var{thread-id} ] [ @var{location} ]
> +    [ -p @var{thread-id} ] @var{location}

Is LOCATION no longer an optional parameter for -break-insert?

OK with those changes.

Thanks!