[PATCH 0/2] gdb/doc: some improvements to the guile docs

[PATCH 0/2] gdb/doc: some improvements to the guile docs

[Andrew Burgess]

A few minor improvements to the guile extension language docs.  This
should improve the index entries, and how proceducre declaration lines
are generated.

---

Andrew Burgess (2):
  gdb/doc: Remove (...) around guile procedure names in @deffn lines
  gdb/doc: shorten some source lines, and prevent some line breaks

 gdb/doc/guile.texi | 45 ++++++++++++++++++++++++++++-----------------
 1 file changed, 28 insertions(+), 17 deletions(-)

-- 
2.25.4

[PATCH 1/2] gdb/doc: Remove (...) around guile procedure names in @deffn lines

[Andrew Burgess]

Most guile procedures in the guile.texi file are defined like:

  @deffn {Scheme Procedure} name arg1 arg2 arg3

But there are two places where we do this:

  @deffn {Scheme Procedure} (name arg1 arg2 arg3)

Notice the added (...).  Though this does represent how a procedure
call is written in scheme, it's not the normal style throughout the
manual.  I also checked the 'info guile' info page to see how they
wrote there declarations, and they use the first style too.

The second style also has the drawback that index entries are added as
'(name', and so they are grouped in the '(' section of the index,
which is not very user friendly.

In this commit I've changed the definitions of make-command and
make-parameter to use the first style.

The procedure declaration lines can get pretty long with all of the
arguments, and this was true for both of the procedures I am changing
in this commit.  I have made use of a trailing '@' to split the deffn
lines, and keep them under 80 characters in the texi source.  This
makes no difference to how the final document looks.

Finally, our current style for keyword arguments, appears to be:

  [#:keyword-name argument-name]

I don't really understand the reason for this, 'info guile' just seems
to use:

  [#:keyword-name]

which seems just as good to me.  But I don't propose to change
that just now.  What I do notice though, is that sometimes, texinfo
will place a line break between the keyword-name and the
argument-name, for example, the pdf of make-command is:

  make-command name [#:invoke invoke] [#:command-class
    command-class] [#:completer-class completer] [#:prefix? prefix] [#:doc
    doc-string]

Notice the line break after '#:command-class' and after '#:doc',
neither of which are ideal.  And so, for the two commands I am
changing in this commit, I have made use of @w{...} to prevent line
breaks between the keyword-name and the argument-name.  Now the pdf
looks like this:

  make-command name [#:invoke invoke]
    [#:command-class command-class] [#:completer-class completer]
    [#:prefix? prefix] [#:doc doc-string]

Which seems much better.  I'll probably update the other deffn lines
at some point.
---
 gdb/doc/guile.texi | 15 +++++++++++----
 1 file changed, 11 insertions(+), 4 deletions(-)

diff --git a/gdb/doc/guile.texi b/gdb/doc/guile.texi
index a2448dd62cb..c10bbe78a9e 100644
--- a/gdb/doc/guile.texi
+++ b/gdb/doc/guile.texi
@@ -1727,8 +1727,10 @@
 There is no support for multi-line commands, that is commands that
 consist of multiple lines and are terminated with @code{end}.
 
-@c TODO: line length
-@deffn {Scheme Procedure} (make-command name @r{[}#:invoke invoke{]} @r{[}#:command-class command-class@r{]} @r{[}#:completer-class completer{]} @r{[}#:prefix? prefix@r{]} @r{[}#:doc doc-string{]})
+@deffn {Scheme Procedure} make-command name @w{@r{[}#:invoke invoke{]}} @
+    @w{@r{[}#:command-class command-class@r{]}} @
+    @w{@r{[}#:completer-class completer{]}} @
+    @w{@r{[}#:prefix? prefix@r{]}} @w{@r{[}#:doc doc-string{]}}
 
 The argument @var{name} is the name of the command.  If @var{name} consists of
 multiple words, then the initial words are looked for as prefix
@@ -2017,8 +2019,13 @@
 Parameters are exposed to the user via the @code{set} and
 @code{show} commands.  @xref{Help}.
 
-@c TODO line length
-@deffn {Scheme Procedure} (make-parameter name @r{[}#:command-class command-class@r{]} @r{[}#:parameter-type parameter-type{]} @r{[}#:enum-list enum-list@r{]} @r{[}#:set-func set-func{]} @r{[}#:show-func show-func{]} @r{[}#:doc doc{]} @r{[}#:set-doc set-doc{]} @r{[}#:show-doc show-doc{]} @r{[}#:initial-value initial-value{]})
+@deffn {Scheme Procedure} make-parameter name @
+    @w{@r{[}#:command-class command-class@r{]}} @
+    @w{@r{[}#:parameter-type parameter-type{]}} @
+    @w{@r{[}#:enum-list enum-list@r{]}} @w{@r{[}#:set-func set-func{]}} @
+    @w{@r{[}#:show-func show-func{]}} @w{@r{[}#:doc doc{]}} @
+    @w{@r{[}#:set-doc set-doc{]}} @w{@r{[}#:show-doc show-doc{]}} @
+    @w{@r{[}#:initial-value initial-value{]}}
 
 The argument @var{name} is the name of the new parameter.  If @var{name}
 consists of multiple words, then the initial words are looked for as prefix
-- 
2.25.4

[PATCH 2/2] gdb/doc: shorten some source lines, and prevent some line breaks

[Andrew Burgess]

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.

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.
---
 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 c10bbe78a9e..967c4263ccb 100644
--- a/gdb/doc/guile.texi
+++ b/gdb/doc/guile.texi
@@ -239,8 +239,8 @@
 
 The @code{(gdb)} module provides these basic Guile functions.
 
-@c TODO: line length 
-@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 @@
 @var{value}.  No transformation, endian or otherwise, is performed.
 @end deffn
 
-@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 @@
 The length must be a Scheme integer and not a @code{<gdb:value>} integer.
 @end deffn
 
-@c TODO: line length
-@deffn {Scheme Procedure} value->lazy-string value @r{[}#:encoding encoding@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 @@
 given, or if @var{frame} is invalid, then an exception is thrown.
 @end deffn
 
-@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 @@
 The following breakpoint-related procedures are provided by the
 @code{(gdb)} module:
 
-@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 @@
 Furthermore, the disassembler can take a Guile port as input,
 allowing one to disassemble from any source, and not just target memory.
 
-@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}.
 
@@ -3568,7 +3571,8 @@
 bytevector functionality.  The main routine is @code{open-memory} which
 returns a port object.  One can then read/write memory using that object.
 
-@deffn {Scheme Procedure} open-memory @r{[}#:mode mode{]} @r{[}#:start address{]} @r{[}#:size size{]}
+@deffn {Scheme Procedure} open-memory @w{@r{[}#:mode mode{]}} @
+    @w{@r{[}#:start address{]}} @w{@r{[}#:size size{]}}
 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"}
-- 
2.25.4

[PATCHv2 0/2] gdb/doc: some improvements to the guile docs

[Andrew Burgess]

Changes since v1:

  - Fixed some missing @r commands in both patches.  Not sure why this
    wasn't causing problems for the pdf generation, but was noticable
    once I tried to build the info files.

---

Andrew Burgess (2):
  gdb/doc: Remove (...) around guile procedure names in @deffn lines
  gdb/doc: shorten some source lines, and prevent some line breaks

 gdb/doc/guile.texi | 45 ++++++++++++++++++++++++++++-----------------
 1 file changed, 28 insertions(+), 17 deletions(-)

-- 
2.25.4

[PATCHv2 1/2] gdb/doc: Remove (...) around guile procedure names in @deffn lines

[Andrew Burgess]

Most guile procedures in the guile.texi file are defined like:

  @deffn {Scheme Procedure} name arg1 arg2 arg3

But there are two places where we do this:

  @deffn {Scheme Procedure} (name arg1 arg2 arg3)

Notice the added (...).  Though this does represent how a procedure
call is written in scheme, it's not the normal style throughout the
manual.  I also checked the 'info guile' info page to see how they
wrote there declarations, and they use the first style too.

The second style also has the drawback that index entries are added as
'(name', and so they are grouped in the '(' section of the index,
which is not very user friendly.

In this commit I've changed the definitions of make-command and
make-parameter to use the first style.

The procedure declaration lines can get pretty long with all of the
arguments, and this was true for both of the procedures I am changing
in this commit.  I have made use of a trailing '@' to split the deffn
lines, and keep them under 80 characters in the texi source.  This
makes no difference to how the final document looks.

Finally, our current style for keyword arguments, appears to be:

  [#:keyword-name argument-name]

I don't really understand the reason for this, 'info guile' just seems
to use:

  [#:keyword-name]

which seems just as good to me.  But I don't propose to change
that just now.  What I do notice though, is that sometimes, texinfo
will place a line break between the keyword-name and the
argument-name, for example, the pdf of make-command is:

  make-command name [#:invoke invoke] [#:command-class
    command-class] [#:completer-class completer] [#:prefix? prefix] [#:doc
    doc-string]

Notice the line break after '#:command-class' and after '#:doc',
neither of which are ideal.  And so, for the two commands I am
changing in this commit, I have made use of @w{...} to prevent line
breaks between the keyword-name and the argument-name.  Now the pdf
looks like this:

  make-command name [#:invoke invoke]
    [#:command-class command-class] [#:completer-class completer]
    [#:prefix? prefix] [#:doc doc-string]

Which seems much better.  I'll probably update the other deffn lines
at some point.
---
 gdb/doc/guile.texi | 15 +++++++++++----
 1 file changed, 11 insertions(+), 4 deletions(-)

diff --git a/gdb/doc/guile.texi b/gdb/doc/guile.texi
index 52348aab8f7..c7e367a9ca8 100644
--- a/gdb/doc/guile.texi
+++ b/gdb/doc/guile.texi
@@ -1727,8 +1727,10 @@
 There is no support for multi-line commands, that is commands that
 consist of multiple lines and are terminated with @code{end}.
 
-@c TODO: line length
-@deffn {Scheme Procedure} (make-command name @r{[}#:invoke invoke{]} @r{[}#:command-class command-class@r{]} @r{[}#:completer-class completer{]} @r{[}#:prefix? prefix@r{]} @r{[}#:doc doc-string{]})
+@deffn {Scheme Procedure} make-command name @w{@r{[}#:invoke invoke@r{]}} @
+    @w{@r{[}#:command-class command-class@r{]}} @
+    @w{@r{[}#:completer-class completer@r{]}} @
+    @w{@r{[}#:prefix? prefix@r{]}} @w{@r{[}#:doc doc-string@r{]}}
 
 The argument @var{name} is the name of the command.  If @var{name} consists of
 multiple words, then the initial words are looked for as prefix
@@ -2017,8 +2019,13 @@
 Parameters are exposed to the user via the @code{set} and
 @code{show} commands.  @xref{Help}.
 
-@c TODO line length
-@deffn {Scheme Procedure} (make-parameter name @r{[}#:command-class command-class@r{]} @r{[}#:parameter-type parameter-type{]} @r{[}#:enum-list enum-list@r{]} @r{[}#:set-func set-func{]} @r{[}#:show-func show-func{]} @r{[}#:doc doc{]} @r{[}#:set-doc set-doc{]} @r{[}#:show-doc show-doc{]} @r{[}#:initial-value initial-value{]})
+@deffn {Scheme Procedure} make-parameter name @
+    @w{@r{[}#:command-class command-class@r{]}} @
+    @w{@r{[}#:parameter-type parameter-type@r{]}} @
+    @w{@r{[}#:enum-list enum-list@r{]}} @w{@r{[}#:set-func set-func@r{]}} @
+    @w{@r{[}#:show-func show-func@r{]}} @w{@r{[}#:doc doc@r{]}} @
+    @w{@r{[}#:set-doc set-doc@r{]}} @w{@r{[}#:show-doc show-doc@r{]}} @
+    @w{@r{[}#:initial-value initial-value@r{]}}
 
 The argument @var{name} is the name of the new parameter.  If @var{name}
 consists of multiple words, then the initial words are looked for as prefix
-- 
2.25.4

[PATCHv2 2/2] gdb/doc: shorten some source lines, and prevent some line breaks

[Andrew Burgess]

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.

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.
---
 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 @@
 
 The @code{(gdb)} module provides these basic Guile functions.
 
-@c TODO: line length 
-@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 @@
 @var{value}.  No transformation, endian or otherwise, is performed.
 @end deffn
 
-@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 @@
 The length must be a Scheme integer and not a @code{<gdb:value>} integer.
 @end deffn
 
-@c TODO: line length
-@deffn {Scheme Procedure} value->lazy-string value @r{[}#:encoding encoding@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 @@
 given, or if @var{frame} is invalid, then an exception is thrown.
 @end deffn
 
-@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 @@
 The following breakpoint-related procedures are provided by the
 @code{(gdb)} module:
 
-@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 @@
 Furthermore, the disassembler can take a Guile port as input,
 allowing one to disassemble from any source, and not just target memory.
 
-@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}.
 
@@ -3568,7 +3571,8 @@
 bytevector functionality.  The main routine is @code{open-memory} which
 returns a port object.  One can then read/write memory using that object.
 
-@deffn {Scheme Procedure} open-memory @r{[}#:mode mode{]} @r{[}#:start address{]} @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"}
-- 
2.25.4

Re: [PATCHv2 1/2] gdb/doc: Remove (...) around guile procedure names in @deffn lines

[Eli Zaretskii]

> Date: Fri,  7 Jan 2022 14:45:25 +0000
> From: Andrew Burgess via Gdb-patches <gdb-patches@sourceware.org>
> Cc: Andrew Burgess <aburgess@redhat.com>
> 
> Most guile procedures in the guile.texi file are defined like:
> 
>   @deffn {Scheme Procedure} name arg1 arg2 arg3
> 
> But there are two places where we do this:
> 
>   @deffn {Scheme Procedure} (name arg1 arg2 arg3)
> 
> Notice the added (...).  Though this does represent how a procedure
> call is written in scheme, it's not the normal style throughout the
> manual.  I also checked the 'info guile' info page to see how they
> wrote there declarations, and they use the first style too.
> 
> The second style also has the drawback that index entries are added as
> '(name', and so they are grouped in the '(' section of the index,
> which is not very user friendly.
> 
> In this commit I've changed the definitions of make-command and
> make-parameter to use the first style.
> 
> The procedure declaration lines can get pretty long with all of the
> arguments, and this was true for both of the procedures I am changing
> in this commit.  I have made use of a trailing '@' to split the deffn
> lines, and keep them under 80 characters in the texi source.  This
> makes no difference to how the final document looks.
> 
> Finally, our current style for keyword arguments, appears to be:
> 
>   [#:keyword-name argument-name]
> 
> I don't really understand the reason for this, 'info guile' just seems
> to use:
> 
>   [#:keyword-name]
> 
> which seems just as good to me.  But I don't propose to change
> that just now.  What I do notice though, is that sometimes, texinfo
> will place a line break between the keyword-name and the
> argument-name, for example, the pdf of make-command is:
> 
>   make-command name [#:invoke invoke] [#:command-class
>     command-class] [#:completer-class completer] [#:prefix? prefix] [#:doc
>     doc-string]
> 
> Notice the line break after '#:command-class' and after '#:doc',
> neither of which are ideal.  And so, for the two commands I am
> changing in this commit, I have made use of @w{...} to prevent line
> breaks between the keyword-name and the argument-name.  Now the pdf
> looks like this:
> 
>   make-command name [#:invoke invoke]
>     [#:command-class command-class] [#:completer-class completer]
>     [#:prefix? prefix] [#:doc doc-string]
> 
> Which seems much better.  I'll probably update the other deffn lines
> at some point.

Thanks.  This is really an "obvious fix", and is definitely OK.

Re: [PATCHv2 2/2] gdb/doc: shorten some source lines, and prevent some line breaks

[Eli Zaretskii]

> Date: Fri,  7 Jan 2022 14:45:26 +0000
> From: Andrew Burgess via Gdb-patches <gdb-patches@sourceware.org>
> Cc: Andrew Burgess <aburgess@redhat.com>
> 
> 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.
> 
> 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.

Thanks, this is an obvious fix.