From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <aburgess@sourceware.org>
Received: by sourceware.org (Postfix, from userid 1726)
 id C043A3857C4A; Fri,  7 Jan 2022 17:50:31 +0000 (GMT)
DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org C043A3857C4A
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: quoted-printable
From: Andrew Burgess <aburgess@sourceware.org>
To: gdb-cvs@sourceware.org
Subject: [binutils-gdb] gdb/doc: shorten some source lines,
 and prevent some line breaks
X-Act-Checkin: binutils-gdb
X-Git-Author: Andrew Burgess <aburgess@redhat.com>
X-Git-Refname: refs/heads/master
X-Git-Oldrev: 8af9b8009b8b8a5ad39d014ef9aab51a8117a520
X-Git-Newrev: d50964864b7caf0dbde0915c0c8ada3aea48ef7a
Message-Id: <20220107175031.C043A3857C4A@sourceware.org>
Date: Fri,  7 Jan 2022 17:50:31 +0000 (GMT)
X-BeenThere: gdb-cvs@sourceware.org
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: Gdb-cvs mailing list <gdb-cvs.sourceware.org>
List-Unsubscribe: <https://sourceware.org/mailman/options/gdb-cvs>,
 <mailto:gdb-cvs-request@sourceware.org?subject=unsubscribe>
List-Archive: <https://sourceware.org/pipermail/gdb-cvs/>
List-Help: <mailto:gdb-cvs-request@sourceware.org?subject=help>
List-Subscribe: <https://sourceware.org/mailman/listinfo/gdb-cvs>,
 <mailto:gdb-cvs-request@sourceware.org?subject=subscribe>
X-List-Received-Date: Fri, 07 Jan 2022 17:50:31 -0000

https://sourceware.org/git/gitweb.cgi?p=3Dbinutils-gdb.git;h=3Dd50964864b7c=
af0dbde0915c0c8ada3aea48ef7a

commit d50964864b7caf0dbde0915c0c8ada3aea48ef7a
Author: Andrew Burgess <aburgess@redhat.com>
Date:   Wed Dec 22 16:47:29 2021 +0000

    gdb/doc: shorten some source lines, and prevent some line breaks
   =20
    Building on the previous commit, this makes use of a trailing @ to
    split long @deffn lines in the guile.texi source file.  This splitting
    doesn't change how the document is laid out by texinfo.
   =20
    I have also wrapped keyword and argument name pairs in @w{...} to
    prevent line breaks appearing between the two.  I've currently only
    done this for the longer @deffn lines, where a line break is
    possible.  This makes the @deffn lines much nicer to read in the
    generated pdf.

Diff:
---
 gdb/doc/guile.texi | 30 +++++++++++++++++-------------
 1 file changed, 17 insertions(+), 13 deletions(-)

diff --git a/gdb/doc/guile.texi b/gdb/doc/guile.texi
index c7e367a9ca8..3c517230929 100644
--- a/gdb/doc/guile.texi
+++ b/gdb/doc/guile.texi
@@ -239,8 +239,8 @@ int
=20
 The @code{(gdb)} module provides these basic Guile functions.
=20
-@c TODO: line length=20
-@deffn {Scheme Procedure} execute command @r{[}#:from-tty boolean@r{]} @r{=
[}#:to-string boolean@r{]}
+@deffn {Scheme Procedure} execute command @w{@r{[}#:from-tty boolean@r{]}}=
 @
+    @w{@r{[}#:to-string boolean@r{]}}
 Evaluate @var{command}, a string, as a @value{GDBN} CLI command.
 If a @value{GDBN} exception happens while @var{command} runs, it is
 translated as described in
@@ -853,8 +853,9 @@ Return a Scheme bytevector with the raw contents of @co=
de{<gdb:value>}
 @var{value}.  No transformation, endian or otherwise, is performed.
 @end deffn
=20
-@c TODO: line length
-@deffn {Scheme Procedure} value->string value @r{[}#:encoding encoding@r{]=
} @r{[}#:errors errors@r{]} @r{[}#:length length@r{]}
+@deffn {Scheme Procedure} value->string value @
+    @w{@r{[}#:encoding encoding@r{]}} @w{@r{[}#:errors errors@r{]}} @
+    @w{@r{[}#:length length@r{]}}
 If @var{value>} represents a string, then this method
 converts the contents to a Guile string.  Otherwise, this method will
 throw an exception.
@@ -895,8 +896,8 @@ fetched and converted to the given length.
 The length must be a Scheme integer and not a @code{<gdb:value>} integer.
 @end deffn
=20
-@c TODO: line length
-@deffn {Scheme Procedure} value->lazy-string value @r{[}#:encoding encodin=
g@r{]} @r{[}#:length length@r{]}
+@deffn {Scheme Procedure} value->lazy-string value @
+    @w{@r{[}#:encoding encoding@r{]}} @w{@r{[}#:length length@r{]}}
 If this @code{<gdb:value>} represents a string, then this method
 converts @var{value} to a @code{<gdb:lazy-string} (@pxref{Lazy Strings
 In Guile}).  Otherwise, this method will throw an exception.
@@ -2736,8 +2737,8 @@ its value, then @var{frame} must be given.  If @var{f=
rame} is not
 given, or if @var{frame} is invalid, then an exception is thrown.
 @end deffn
=20
-@c TODO: line length
-@deffn {Scheme Procedure} lookup-symbol name @r{[}#:block block@r{]} @r{[}=
#:domain domain@r{]}
+@deffn {Scheme Procedure} lookup-symbol name @w{@r{[}#:block block@r{]}} @
+    @w{@r{[}#:domain domain@r{]}}
 This function searches for a symbol by name.  The search scope can be
 restricted to the parameters defined in the optional domain and block
 arguments.
@@ -2971,8 +2972,9 @@ outside of Guile.
 The following breakpoint-related procedures are provided by the
 @code{(gdb)} module:
=20
-@c TODO: line length
-@deffn {Scheme Procedure} make-breakpoint location @r{[}#:type type@r{]} @=
r{[}#:wp-class wp-class@r{]} @r{[}#:internal internal@r{]} @r{[}#:temporary=
 temporary@r{]}
+@deffn {Scheme Procedure} make-breakpoint location @w{@r{[}#:type type@r{]=
}} @
+    @w{@r{[}#:wp-class wp-class@r{]}} @w{@r{[}#:internal internal@r{]}} @
+    @w{@r{[}#:temporary temporary@r{]}}
 Create a new breakpoint at @var{location}, a string naming the
 location of the breakpoint, or an expression that defines a watchpoint.
 The contents can be any location recognized by the @code{break} command,
@@ -3476,8 +3478,9 @@ The disassembler can be invoked from Scheme code.
 Furthermore, the disassembler can take a Guile port as input,
 allowing one to disassemble from any source, and not just target memory.
=20
-@c TODO: line length
-@deffn {Scheme Procedure} arch-disassemble arch start-pc @r{[}#:port port@=
r{]} @r{[}#:offset offset@r{]} @r{[}#:size size@r{]} @r{[}#:count count@r{]}
+@deffn {Scheme Procedure} arch-disassemble arch start-pc @
+    @w{@r{[}#:port port@r{]}} @w{@r{[}#:offset offset@r{]}} @
+    @w{@r{[}#:size size@r{]}} @w{@r{[}#:count count@r{]}}
 Return a list of disassembled instructions starting from the memory
 address @var{start-pc}.
=20
@@ -3568,7 +3571,8 @@ This allows Guile code to read/write target memory us=
ing Guile's port and
 bytevector functionality.  The main routine is @code{open-memory} which
 returns a port object.  One can then read/write memory using that object.
=20
-@deffn {Scheme Procedure} open-memory @r{[}#:mode mode{]} @r{[}#:start add=
ress{]} @r{[}#:size size{]}
+@deffn {Scheme Procedure} open-memory @w{@r{[}#:mode mode@r{]}} @
+    @w{@r{[}#:start address@r{]}} @w{@r{[}#:size size@r{]}}
 Return a port object that can be used for reading and writing memory.
 The port will be open according to @var{mode}, which is the standard
 mode argument to Guile port open routines, except that the @samp{"a"}