Document conventions for describing packet syntax

This comment documents conventions for describing packet syntax in the
Overview section.

Change-Id: I96198592601b24c983da563d143666137e4d0a4e
Co-Authored-By: Jim Blandy <jimb@codesourcery.com>
Co-Authored-By: Mike Wrighton <mike_wrighton@mentor.com>
Co-Authored-By: Nathan Sidwell <nathan@codesourcery.com>
Co-Authored-By: Hafiz Abid Qadeer <abidh@codesourcery.com>
Approved-By: Eli Zaretskii <eliz@gnu.org>

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index b2e9faac82df7dec62bdcd4cace847a0851ba55d..d7b8b3f1b61a6b4c6995d4bdeaa04f6ee03dbf55 100644 (file)
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -42517,6 +42517,22 @@ For any @var{command} not supported by the stub, an empty response
 protocol.  A newer @value{GDBN} can tell if a packet is supported based
 on that response.
 
+In describing packets (commands and responses), each description has a
+template showing the overall syntax, followed by an explanation of the
+packet's meaning.  We include spaces in some of the templates for
+clarity; these are not part of the packet's syntax.  No @value{GDBN}
+packet uses spaces to separate its components.  For example, a
+template like @samp{foo @var{bar} @var{baz}} describes a packet
+beginning with the three ASCII bytes @samp{foo}, followed by a
+@var{bar}, followed directly by a @var{baz}.  @value{GDBN} does not
+transmit a space character between the @samp{foo} and the @var{bar},
+or between the @var{bar} and the @var{baz}.
+
+We place optional portions of a packet in [square brackets];
+for example, a template like @samp{c @r{[}@var{addr}@r{]}} describes a
+packet beginning with the single ASCII character @samp{c}, possibly
+followed by an @var{addr}.
+
 At a minimum, a stub is required to support the @samp{?} command to
 tell @value{GDBN} the reason for halting, @samp{g} and @samp{G}
 commands for register access, and the @samp{m} and @samp{M} commands