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