Re: [PATCHv2 1/8] gdb/doc: document how filename arguments are formatted

[Eli Zaretskii <eliz@gnu.org>]

> From: Andrew Burgess <aburgess@redhat.com>
> Cc: Andrew Burgess <aburgess@redhat.com>,
> 	Lancelot SIX <lsix@lancelotsix.com>,
> 	Eli Zaretskii <eliz@gnu.org>
> Date: Sat, 20 Apr 2024 10:10:01 +0100
> 
> In the following commits I intend to improve GDB's filename
> completion.  However, how filenames should be completed is a little
> complex because GDB is not consistent with how it expects filename
> arguments to be formatted.
> 
> This commit documents the current state of GDB when it comes to
> formatting filename arguments.
> 
> Currently GDB will not correctly complete filenames inline with this
> documentation; GDB will either fail to complete, or complete
> incorrectly (i.e. the result of completion will not then be accepted
> by GDB).  However, later commits in this series will fix completion.
> ---
>  gdb/doc/gdb.texinfo | 66 +++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 66 insertions(+)

Thanks, a few comments below.

> +@node Filename Arguments
> +@section Filenames As Command Arguments

Perhaps add some index entry here?  Like this, for example:

  @cindex file names, quoting and escaping
  
> +If the filename does include whitespace, double quotes, or single
> +quotes then @value{GDBN} has two approaches for how these filenames
         ^
A comma missing there.

> +should be formatted, which format to use depends on which command is
> +being used.        ^

I'd replace that comma with a semi-colon.

> +Alternatively the entire filename can be wrapped in quotes, in which
> +case no backlsashes are needed, for example:
> +
> +@smallexample
> +(@value{GDBP}) file "/path/with spaces/to/a file"
> +@end smallexample

is quoting "like this" the only supported style of quoting, or do we
also support quoting 'like this'?  If the latter, we should say so in
the manual.  I would also suggest to describe how to quote file names
with embedded quote characters, instead of leaving this to the
reader's imagination and creativity.

Reviewed-By: Eli Zaretskii <eliz@gnu.org>