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

  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(+)
  

> 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>
  

Eli,

Thanks for your feedback.

I've addressed the issues you pointed out, and have added some
additional text at the end to better describe the escaping of quote
characters and of backslash itself.

Let me know what you think.

Thanks,
Andrew

---

commit 4d1a140481d8e7262d631cf10756a0d698f75477
Author: Andrew Burgess <aburgess@redhat.com>
Date:   Wed Apr 17 14:47:49 2024 +0100

    gdb/doc: document how filename arguments are formatted
    
    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.
    
    Reviewed-By: Eli Zaretskii <eliz@gnu.org>

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index b2e9faac82d..4ba77b56b8f 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -1752,6 +1752,7 @@
 * Command Syntax::              How to give commands to @value{GDBN}
 * Command Settings::            How to change default behavior of commands
 * Completion::                  Command completion
+* Filename Arguments::		Filenames As Command Arguments
 * Command Options::             Command options
 * Help::                        How to ask @value{GDBN} for help
 @end menu
@@ -2123,6 +2124,68 @@
 @}
 @end smallexample
 
+@node Filename Arguments
+@section Filenames As Command Arguments
+@cindex file names, quoting and escaping
+
+When passing filenames (or directory names) as arguments to a command,
+if the filename argument does not include any whitespace, double
+quotes, or single quotes, then for all commands the filename can be
+written as a simple string, for example:
+
+@smallexample
+(@value{GDBP}) file /path/to/some/file
+@end smallexample
+
+If the filename does include whitespace, double quotes, or single
+quotes, then @value{GDBN} has two approaches for how these filenames
+should be formatted; which format to use depends on which command is
+being used.
+
+Most @value{GDBN} commands don't require, or support, quoting and
+escaping.  These commands treat any text after the command name, that
+is not a command option (@pxref{Command Options}), as the filename,
+even if the filename contains whitespace or quote characters.  In the
+following example the user is adding @w{@file{/path/that contains/two
+spaces/}} to the auto-load safe-path (@pxref{add-auto-load-safe-path}):
+
+@smallexample
+(@value{GDBP}) add-auto-load-safe-path /path/that contains/two spaces/
+@end smallexample
+
+A small number of commands require that filenames containing
+whitespace or quote characters are either quoted, or have the special
+characters escaped with a backslash.  Commands that support this style
+are marked as such in the manual, any command not marked as accepting
+quoting and escaping of its filename argument, does not accept this
+filename argument style.
+
+For example, to load the file @file{/path/with spaces/to/a file} with
+the @code{file} command (@pxref{Files, ,Commands to Specify Files}),
+you can escape the whitespace characters with a backslash:
+
+@smallexample
+(@value{GDBP}) file /path/with\ spaces/to/a\ file
+@end smallexample
+
+Alternatively the entire filename can be wrapped in either single or
+double quotes, in which case no backlsashes are needed, for example:
+
+@smallexample
+(@value{GDBP}) symbol-file "/path/with spaces/to/a file"
+(@value{GDBP}) exec-file '/path/with spaces/to/a file'
+@end smallexample
+
+It is possible to include a quote character within a quoted filename
+by escaping it with a backslash, for example, within a filename
+surrounded by double quotes, a double quote character should be
+escaped with a backslash, but a single quote character should not be
+escaped.  Within a single quoted string a single quote character needs
+to be escaped, but a double quote character does not.
+
+A literal backslash character can also be included by escaping it with
+a backslash.
+
 @node Command Options
 @section Command options
 
@@ -21615,6 +21678,9 @@
 to run.  You can change the value of this variable, for both @value{GDBN}
 and your program, using the @code{path} command.
 
+The @var{filename} argument supports escaping and quoting, see
+@ref{Filename Arguments,,Filenames As Command Arguments}.
+
 @cindex unlinked object files
 @cindex patching object files
 You can load unlinked object @file{.o} files into @value{GDBN} using
@@ -21637,6 +21703,9 @@
 if necessary to locate your program.  Omitting @var{filename} means to
 discard information on the executable file.
 
+The @var{filename} argument supports escaping and quoting, see
+@ref{Filename Arguments,,Filenames As Command Arguments}.
+
 @kindex symbol-file
 @item symbol-file @r{[} @var{filename} @r{[} -o @var{offset} @r{]]}
 Read symbol table information from file @var{filename}.  @env{PATH} is
@@ -21660,6 +21729,9 @@
 @code{symbol-file} does not repeat if you press @key{RET} again after
 executing it once.
 
+The @var{filename} argument supports escaping and quoting, see
+@ref{Filename Arguments,,Filenames As Command Arguments}.
+
 When @value{GDBN} is configured for a particular environment, it
 understands debugging information in whatever format is the standard
 generated for that environment; you may use either a @sc{gnu} compiler, or
@@ -21754,6 +21826,9 @@
 @code{add-symbol-file} command any number of times; the new symbol data
 thus read is kept in addition to the old.
 
+The @var{filename} argument supports escaping and quoting, see
+@ref{Filename Arguments,,Filenames As Command Arguments}.
+
 Changes can be reverted using the command @code{remove-symbol-file}.
 
 @cindex relocatable object files, reading symbols from
@@ -21813,6 +21888,9 @@
 
 @code{remove-symbol-file} does not repeat if you press @key{RET} after using it.
 
+The @var{filename} argument supports escaping and quoting, see
+@ref{Filename Arguments,,Filenames As Command Arguments}.
+
 @kindex add-symbol-file-from-memory
 @cindex @code{syscall DSO}
 @cindex load symbols from memory
  

> From: Andrew Burgess <aburgess@redhat.com>
> Cc: gdb-patches@sourceware.org, lsix@lancelotsix.com
> Date: Sat, 27 Apr 2024 11:01:23 +0100
> 
> 
> Eli,
> 
> Thanks for your feedback.
> 
> I've addressed the issues you pointed out, and have added some
> additional text at the end to better describe the escaping of quote
> characters and of backslash itself.

Thanks.

> +For example, to load the file @file{/path/with spaces/to/a file} with
                                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This should be in @w, because white space is significant.

OK with that nit fixed.

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

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Andrew Burgess <aburgess@redhat.com>
>> Cc: gdb-patches@sourceware.org, lsix@lancelotsix.com
>> Date: Sat, 27 Apr 2024 11:01:23 +0100
>> 
>> 
>> Eli,
>> 
>> Thanks for your feedback.
>> 
>> I've addressed the issues you pointed out, and have added some
>> additional text at the end to better describe the escaping of quote
>> characters and of backslash itself.
>
> Thanks.
>
>> +For example, to load the file @file{/path/with spaces/to/a file} with
>                                  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> This should be in @w, because white space is significant.
>
> OK with that nit fixed.

I added the missing @w and pushed just this patch for now.

Thanks,
Andrew