[PATCH 0/2] doc: MPFR is now a necessary requirement

[PATCH 0/2] doc: MPFR is now a necessary requirement

[Philippe Blain]

This short series moves the "MPFR" requirement in the doc under the
"Tools/Packages Necessary for Building GDB" heading and uniformizes the wording
between the GMP and MPFR entries.

I tested the HTML doc build.

---
Philippe Blain (2):
      gdb/doc: MPFR is now a necessary requirement
      gdb/doc: uniformize wording for GMP and MPFR entries

 gdb/doc/gdb.texinfo | 31 +++++++++++++++----------------
 1 file changed, 15 insertions(+), 16 deletions(-)
---
base-commit: 4c9066e322f46faf9d753be6ff3e6a09ae668f86
change-id: 20230306-doc-require-mpfr-fix-65e7105fc410
--
b4 

[PATCH 1/2] gdb/doc: MPFR is now a necessary requirement

[Philippe Blain]

Since 99118062785 (Use toplevel configure for GMP and MPFR for gdb,
2022-11-08), MPFR is mandatory for building GDB. That commit adjusted
the "Requirements for Building GDB" section of the documentation so that
the MPFR entry mentions "now uses" instead of "can use", but left the
whole entry under the "Tools/Packages Optional for Building GDB"
heading.

Move the MPFR entry to the "Tools/Packages Necessary for Building GDB"
heading.
---
 gdb/doc/gdb.texinfo | 30 +++++++++++++++---------------
 1 file changed, 15 insertions(+), 15 deletions(-)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 2a2077c29d1..218c2da9c86 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -39781,6 +39781,21 @@ you can use the @option{--with-gmp} option or options
 @option{--with-gmp-include} and @option{--with-gmp-lib} to specify
 its location.
 
+@item MPFR
+@anchor{MPFR}
+@value{GDBN} now uses the GNU MPFR multiple-precision floating-point
+library.  This library may be included with your operating system
+distribution; if it is not, you can get the latest version from
+@url{http://www.mpfr.org}.  The @file{configure} script will search
+for this library in several standard locations; if it is installed
+in an unusual path, you can use the @option{--with-mpfr} option or options
+@option{--with-mpfr-include} and @option{--with-mpfr-lib} to specify
+its location.
+
+GNU MPFR is used to emulate target floating-point arithmetic during
+expression evaluation when the target uses different floating-point
+formats than the host.
+
 @end table
 
 @heading Tools/Packages Optional for Building @value{GDBN}
@@ -39858,21 +39873,6 @@ the usual place, then the @file{configure} script will use it
 automatically.  If it is installed in an unusual path, you can use the
 @option{--with-liblzma-prefix} option to specify its location.
 
-@item MPFR
-@anchor{MPFR}
-@value{GDBN} now uses the GNU MPFR multiple-precision floating-point
-library.  This library may be included with your operating system
-distribution; if it is not, you can get the latest version from
-@url{http://www.mpfr.org}.  The @file{configure} script will search
-for this library in several standard locations; if it is installed
-in an unusual path, you can use the @option{--with-mpfr} option or options
-@option{--with-mpfr-include} and @option{--with-mpfr-lib} to specify
-its location.
-
-GNU MPFR is used to emulate target floating-point arithmetic during
-expression evaluation when the target uses different floating-point
-formats than the host.
-
 @item Python
 @value{GDBN} can be scripted using Python language.  @xref{Python}.
 By default, @value{GDBN} will be compiled if the Python libraries are

-- 
2.34.1

[PATCH 2/2] gdb/doc: uniformize wording for GMP and MPFR entries

[Philippe Blain]

Make the wording of the GMP and MPFR entries in the "Requirements for
Building GDB" section of the documentation more uniform by:

- mentioning the configure script in the GMP entry, as is done in the
  MPFR entry
- adding the long name of the MPFR library between parenthesis, as is
  done in the GMP entry
- removing the second paragraph of the MPFR entry and moving its content
  to the first one, mimicking the wording of the GMP entry
---
 gdb/doc/gdb.texinfo | 13 ++++++-------
 1 file changed, 6 insertions(+), 7 deletions(-)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 218c2da9c86..44e3859658e 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -39776,15 +39776,18 @@ make program.  Other variants of @code{make} will not work.
 @value{GDBN} now uses GMP to perform some of its arithmetics.
 This library may be included with your operating system distribution;
 if it is not, you can get the latest version from
-@url{https://gmplib.org/}. If GMP is installed at an unusual path,
+@url{https://gmplib.org/}. The @file{configure} script will search
+for this library in several standard locations; if it is installed at an unusual path,
 you can use the @option{--with-gmp} option or options
 @option{--with-gmp-include} and @option{--with-gmp-lib} to specify
 its location.
 
-@item MPFR
+@item MPFR (The GNU MPFR Library)
 @anchor{MPFR}
 @value{GDBN} now uses the GNU MPFR multiple-precision floating-point
-library.  This library may be included with your operating system
+library to emulate target floating-point arithmetic during
+expression evaluation when the target uses different floating-point
+formats than the host.  This library may be included with your operating system
 distribution; if it is not, you can get the latest version from
 @url{http://www.mpfr.org}.  The @file{configure} script will search
 for this library in several standard locations; if it is installed
@@ -39792,10 +39795,6 @@ in an unusual path, you can use the @option{--with-mpfr} option or options
 @option{--with-mpfr-include} and @option{--with-mpfr-lib} to specify
 its location.
 
-GNU MPFR is used to emulate target floating-point arithmetic during
-expression evaluation when the target uses different floating-point
-formats than the host.
-
 @end table
 
 @heading Tools/Packages Optional for Building @value{GDBN}

-- 
2.34.1

Re: [PATCH 1/2] gdb/doc: MPFR is now a necessary requirement

[Eli Zaretskii]

> Date: Fri, 10 Mar 2023 12:46:56 -0500
> Cc: Andrew Pinski <apinski@marvell.com>
> From: Philippe Blain via Gdb-patches <gdb-patches@sourceware.org>
> 
> Since 99118062785 (Use toplevel configure for GMP and MPFR for gdb,
> 2022-11-08), MPFR is mandatory for building GDB. That commit adjusted
> the "Requirements for Building GDB" section of the documentation so that
> the MPFR entry mentions "now uses" instead of "can use", but left the
> whole entry under the "Tools/Packages Optional for Building GDB"
> heading.
> 
> Move the MPFR entry to the "Tools/Packages Necessary for Building GDB"
> heading.
> ---
>  gdb/doc/gdb.texinfo | 30 +++++++++++++++---------------
>  1 file changed, 15 insertions(+), 15 deletions(-)

Thanks, this is OK.

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

Re: [PATCH 2/2] gdb/doc: uniformize wording for GMP and MPFR entries

[Eli Zaretskii]

> Date: Fri, 10 Mar 2023 12:46:57 -0500
> Cc: Andrew Pinski <apinski@marvell.com>
> From: Philippe Blain via Gdb-patches <gdb-patches@sourceware.org>
> 
> Make the wording of the GMP and MPFR entries in the "Requirements for
> Building GDB" section of the documentation more uniform by:
> 
> - mentioning the configure script in the GMP entry, as is done in the
>   MPFR entry
> - adding the long name of the MPFR library between parenthesis, as is
>   done in the GMP entry
> - removing the second paragraph of the MPFR entry and moving its content
>   to the first one, mimicking the wording of the GMP entry
> ---
>  gdb/doc/gdb.texinfo | 13 ++++++-------
>  1 file changed, 6 insertions(+), 7 deletions(-)

I don't mind the changes, but I also don't mind leaving the original
text intact: there's nothing wrong with it per se.

Thanks.

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

Re: [PATCH 2/2] gdb/doc: uniformize wording for GMP and MPFR entries

[Philippe Blain]

Hi Eli,

Le 2023-03-10 à 14:17, Eli Zaretskii a écrit :
>> Date: Fri, 10 Mar 2023 12:46:57 -0500
>> Cc: Andrew Pinski <apinski@marvell.com>
>> From: Philippe Blain via Gdb-patches <gdb-patches@sourceware.org>
>>
>> Make the wording of the GMP and MPFR entries in the "Requirements for
>> Building GDB" section of the documentation more uniform by:
>>
>> - mentioning the configure script in the GMP entry, as is done in the
>>   MPFR entry
>> - adding the long name of the MPFR library between parenthesis, as is
>>   done in the GMP entry
>> - removing the second paragraph of the MPFR entry and moving its content
>>   to the first one, mimicking the wording of the GMP entry
>> ---
>>  gdb/doc/gdb.texinfo | 13 ++++++-------
>>  1 file changed, 6 insertions(+), 7 deletions(-)
> 
> I don't mind the changes, but I also don't mind leaving the original
> text intact: there's nothing wrong with it per se.
> 
> Thanks.
> 
> Reviewed-By: Eli Zaretskii <eliz@gnu.org>
> 

Thanks for the reviwew. I do not have push access, would you be so
kind as to push both patches ? 

Thanks,

Philippe.

Re: [PATCH 2/2] gdb/doc: uniformize wording for GMP and MPFR entries

[Eli Zaretskii]

> Cc: gdb-patches@sourceware.org, apinski@marvell.com
> From: Philippe Blain <levraiphilippeblain@gmail.com>
> Date: Mon, 13 Mar 2023 12:45:04 -0400
> 
> Hi Eli,
> 
> Le 2023-03-10 à 14:17, Eli Zaretskii a écrit :
> >> Date: Fri, 10 Mar 2023 12:46:57 -0500
> >> Cc: Andrew Pinski <apinski@marvell.com>
> >> From: Philippe Blain via Gdb-patches <gdb-patches@sourceware.org>
> >>
> >> Make the wording of the GMP and MPFR entries in the "Requirements for
> >> Building GDB" section of the documentation more uniform by:
> >>
> >> - mentioning the configure script in the GMP entry, as is done in the
> >>   MPFR entry
> >> - adding the long name of the MPFR library between parenthesis, as is
> >>   done in the GMP entry
> >> - removing the second paragraph of the MPFR entry and moving its content
> >>   to the first one, mimicking the wording of the GMP entry
> >> ---
> >>  gdb/doc/gdb.texinfo | 13 ++++++-------
> >>  1 file changed, 6 insertions(+), 7 deletions(-)
> > 
> > I don't mind the changes, but I also don't mind leaving the original
> > text intact: there's nothing wrong with it per se.
> > 
> > Thanks.
> > 
> > Reviewed-By: Eli Zaretskii <eliz@gnu.org>
> > 
> 
> Thanks for the reviwew. I do not have push access, would you be so
> kind as to push both patches ? 

My preference is to install only the first of these, for the reasons I
explained, but I'm waiting to hear opinions of others, if they differ.

Re: [PATCH 2/2] gdb/doc: uniformize wording for GMP and MPFR entries

[Philippe Blain]

Hi Eli,

Le 2023-03-14 à 08:08, Eli Zaretskii a écrit :
>> Cc: gdb-patches@sourceware.org, apinski@marvell.com
>> From: Philippe Blain <levraiphilippeblain@gmail.com>
>> Date: Mon, 13 Mar 2023 12:45:04 -0400
>>
>> Hi Eli,
>>
>> Le 2023-03-10 à 14:17, Eli Zaretskii a écrit :
>>>> Date: Fri, 10 Mar 2023 12:46:57 -0500
>>>> Cc: Andrew Pinski <apinski@marvell.com>
>>>> From: Philippe Blain via Gdb-patches <gdb-patches@sourceware.org>
>>>>
>>>> Make the wording of the GMP and MPFR entries in the "Requirements for
>>>> Building GDB" section of the documentation more uniform by:
>>>>
>>>> - mentioning the configure script in the GMP entry, as is done in the
>>>>   MPFR entry
>>>> - adding the long name of the MPFR library between parenthesis, as is
>>>>   done in the GMP entry
>>>> - removing the second paragraph of the MPFR entry and moving its content
>>>>   to the first one, mimicking the wording of the GMP entry
>>>> ---
>>>>  gdb/doc/gdb.texinfo | 13 ++++++-------
>>>>  1 file changed, 6 insertions(+), 7 deletions(-)
>>>
>>> I don't mind the changes, but I also don't mind leaving the original
>>> text intact: there's nothing wrong with it per se.
>>>
>>> Thanks.
>>>
>>> Reviewed-By: Eli Zaretskii <eliz@gnu.org>
>>>
>>
>> Thanks for the reviwew. I do not have push access, would you be so
>> kind as to push both patches ? 
> 
> My preference is to install only the first of these, for the reasons I
> explained, but I'm waiting to hear opinions of others, if they differ.

OK, thanks. let's wait a bit to see if someone else wants to chime in.

I guess I was confused by the fact that 'Approved-by' is used here in a different way
than in the Git project, where it is an explicit approval (and Approved-by is not used).

Maybe an argument for the second patch is that since the first patch makes the GMP and
MPFR neighboring entries, it makes more sense to uniformize the wording between the two
entries. At least, this is why I made this change: it looked a bit off when I read the doc
after only the first patch.

Thanks,

Philippe.

Re: [PATCH 2/2] gdb/doc: uniformize wording for GMP and MPFR entries

[Philippe Blain]

Le 2023-03-14 à 13:12, Philippe Blain a écrit :
> Hi Eli,
> 
[...]
> 
> I guess I was confused by the fact that 'Approved-by' is used here in a different way
> than in the Git project, where it is an explicit approval 

I meant 'Reviewed-by' here, sorry.

Re: [PATCH 2/2] gdb/doc: uniformize wording for GMP and MPFR entries

[Eli Zaretskii]

> Cc: gdb-patches@sourceware.org, apinski@marvell.com
> From: Philippe Blain <levraiphilippeblain@gmail.com>
> Date: Tue, 14 Mar 2023 13:12:19 -0400
> 
> >>> Reviewed-By: Eli Zaretskii <eliz@gnu.org>
> >>>
> >>
> >> Thanks for the reviwew. I do not have push access, would you be so
> >> kind as to push both patches ? 
> > 
> > My preference is to install only the first of these, for the reasons I
> > explained, but I'm waiting to hear opinions of others, if they differ.
> 
> OK, thanks. let's wait a bit to see if someone else wants to chime in.
> 
> I guess I was confused by the fact that 'Approved-by' is used here in a different way
> than in the Git project, where it is an explicit approval (and Approved-by is not used).

I didn't give Approved-by, I gave Reviewed-By.

Re: [PATCH 2/2] gdb/doc: uniformize wording for GMP and MPFR entries

[Eli Zaretskii]

> From: Philippe Blain <levraiphilippeblain@gmail.com>
> Cc: gdb-patches@sourceware.org, apinski@marvell.com
> Date: Tue, 14 Mar 2023 13:38:08 -0400
> 
> Le 2023-03-14 à 13:12, Philippe Blain a écrit :
> > Hi Eli,
> > 
> [...]
> > 
> > I guess I was confused by the fact that 'Approved-by' is used here in a different way
> > than in the Git project, where it is an explicit approval 
> 
> I meant 'Reviewed-by' here, sorry.

Do they really use Reviewed-by as an approval?  _That_ would be
confusing, since the word "review" means just that, it doesn't mean
any approval.

Re: [PATCH 2/2] gdb/doc: uniformize wording for GMP and MPFR entries

[Philippe Blain]

Hi Eli,

Le 2023-03-14 à 15:41, Eli Zaretskii a écrit :
>> From: Philippe Blain <levraiphilippeblain@gmail.com>
>> Cc: gdb-patches@sourceware.org, apinski@marvell.com
>> Date: Tue, 14 Mar 2023 13:38:08 -0400
>>
>> Le 2023-03-14 à 13:12, Philippe Blain a écrit :
>>> Hi Eli,
>>>
>> [...]
>>>
>>> I guess I was confused by the fact that 'Approved-by' is used here in a different way
>>> than in the Git project, where it is an explicit approval 
>>
>> I meant 'Reviewed-by' here, sorry.
> 
> Do they really use Reviewed-by as an approval?  _That_ would be
> confusing, since the word "review" means just that, it doesn't mean
> any approval.
> 

Yes, in the Git project, Reviewd-by is approval, see for example 
item 3. at https://git-scm.com/docs/SubmittingPatches#sign-off 
(under "If you like, you can put extra tags at the end"):


	Reviewed-by:, unlike the other tags, can only be offered by the 
	reviewers themselves when they are completely satisfied with the 
	patch after a detailed analysis.

This is in line with what it means for Linux also, as far as I understand [1].

Thanks,

Philippe.

[1] https://www.kernel.org/doc/html/v4.17/process/submitting-patches.html#using-reported-by-tested-by-reviewed-by-suggested-by-and-fixes

Re: [PATCH 0/2] doc: MPFR is now a necessary requirement

[Philippe Blain]

Le 2023-03-10 à 12:46, Philippe Blain a écrit :
> This short series moves the "MPFR" requirement in the doc under the
> "Tools/Packages Necessary for Building GDB" heading and uniformizes the wording
> between the GMP and MPFR entries.
> 
> I tested the HTML doc build.
> 
> ---
> Philippe Blain (2):
>       gdb/doc: MPFR is now a necessary requirement
>       gdb/doc: uniformize wording for GMP and MPFR entries
> 
>  gdb/doc/gdb.texinfo | 31 +++++++++++++++----------------
>  1 file changed, 15 insertions(+), 16 deletions(-)
> ---
> base-commit: 4c9066e322f46faf9d753be6ff3e6a09ae668f86
> change-id: 20230306-doc-require-mpfr-fix-65e7105fc410
> --
> b4 
> 

A small ping.

If nobody else has an opinion on 2/2, maybe someone with push access
could push 1/2 which is already approved ?

Thank you,

Philippe.

Re: [PATCH 1/2] gdb/doc: MPFR is now a necessary requirement

[Simon Marchi]

On 3/10/23 12:46, Philippe Blain via Gdb-patches wrote:
> Since 99118062785 (Use toplevel configure for GMP and MPFR for gdb,
> 2022-11-08), MPFR is mandatory for building GDB. That commit adjusted
> the "Requirements for Building GDB" section of the documentation so that
> the MPFR entry mentions "now uses" instead of "can use", but left the
> whole entry under the "Tools/Packages Optional for Building GDB"
> heading.
> 
> Move the MPFR entry to the "Tools/Packages Necessary for Building GDB"
> heading.
> ---
>  gdb/doc/gdb.texinfo | 30 +++++++++++++++---------------
>  1 file changed, 15 insertions(+), 15 deletions(-)
> 
> diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
> index 2a2077c29d1..218c2da9c86 100644
> --- a/gdb/doc/gdb.texinfo
> +++ b/gdb/doc/gdb.texinfo
> @@ -39781,6 +39781,21 @@ you can use the @option{--with-gmp} option or options
>  @option{--with-gmp-include} and @option{--with-gmp-lib} to specify
>  its location.
>  
> +@item MPFR
> +@anchor{MPFR}
> +@value{GDBN} now uses the GNU MPFR multiple-precision floating-point

Unlike in the NEWS file, where we describe the changes from one version
to another, the documentation is meant to describe the GDB version is
comes with.  Therefore, I find it odd to use "now" in the documentation.
I would just say "GDB uses the GNU MPFR...".  I know it's pre-existing
text and it's the same in the GMP paragraph, but it sounds weird there
too.  Imagine reading the doc 20 years down the road, and it says "GDB
now uses the GNU GMP...", as if it's a new thing.

Simon

Re: [PATCH 2/2] gdb/doc: uniformize wording for GMP and MPFR entries

[Simon Marchi]

> My preference is to install only the first of these, for the reasons I
> explained, but I'm waiting to hear opinions of others, if they differ.
Since you are waiting for some opinion, I'll give mine.  I like the more
uniform text after patch 2.  I like having the description of why GDB
uses the library at the start (even if it's just informative, it doesn't
help the user accomplish anything in the end).  I think that the change
that mentions the "configure" script is nice, otherwise it can be
unclear where to use those --with-gmp/--with-gmp-include/--with-gmp-lib
options.

Simon

Re: [PATCH 1/2] gdb/doc: MPFR is now a necessary requirement

[Philippe Blain]

Hi Simon,

Le 2023-03-27 à 17:13, Simon Marchi a écrit :
> On 3/10/23 12:46, Philippe Blain via Gdb-patches wrote:
>> Since 99118062785 (Use toplevel configure for GMP and MPFR for gdb,
>> 2022-11-08), MPFR is mandatory for building GDB. That commit adjusted
>> the "Requirements for Building GDB" section of the documentation so that
>> the MPFR entry mentions "now uses" instead of "can use", but left the
>> whole entry under the "Tools/Packages Optional for Building GDB"
>> heading.
>>
>> Move the MPFR entry to the "Tools/Packages Necessary for Building GDB"
>> heading.
>> ---
>>  gdb/doc/gdb.texinfo | 30 +++++++++++++++---------------
>>  1 file changed, 15 insertions(+), 15 deletions(-)
>>
>> diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
>> index 2a2077c29d1..218c2da9c86 100644
>> --- a/gdb/doc/gdb.texinfo
>> +++ b/gdb/doc/gdb.texinfo
>> @@ -39781,6 +39781,21 @@ you can use the @option{--with-gmp} option or options
>>  @option{--with-gmp-include} and @option{--with-gmp-lib} to specify
>>  its location.
>>  
>> +@item MPFR
>> +@anchor{MPFR}
>> +@value{GDBN} now uses the GNU MPFR multiple-precision floating-point
> 
> Unlike in the NEWS file, where we describe the changes from one version
> to another, the documentation is meant to describe the GDB version is
> comes with.  Therefore, I find it odd to use "now" in the documentation.
> I would just say "GDB uses the GNU MPFR...".  I know it's pre-existing
> text and it's the same in the GMP paragraph, but it sounds weird there
> too.  Imagine reading the doc 20 years down the road, and it says "GDB
> now uses the GNU GMP...", as if it's a new thing.

Yes, I agree. I avoided changing that to keep the existing text as is, and
indeed also because the GMP entry uses the same wording. 

I'll tweak both in v2. 

Thanks,

Philippe.

Re: [PATCH v2 0/2] doc: MPFR is now a necessary requirement

[Philippe Blain]

Hi Eli,

Le 2023-04-05 à 09:31, Eli Zaretskii a écrit :
>> From: Philippe Blain <levraiphilippeblain@gmail.com>
>> Date: Mon, 03 Apr 2023 12:47:34 -0400
>>
>> This short series moves the "MPFR" requirement in the doc under the
>> "Tools/Packages Necessary for Building GDB" heading and uniformizes the wording
>> between the GMP and MPFR entries.
>>
>> I tested the HTML doc build.
>> 
>> ---
>> Changes in v2:
>> - removed "now" from the first sentence in both the GMP and MPFR entries,
>>   as suggested by Simon
>> - Link to v1: https://inbox.sourceware.org/20230306-doc-require-mpfr-fix-v1-0-8f207504dd3e@gmail.com
> 
> Thanks for working on this.
> 
> I've eventually concluded that a much deeper surgery is needed in
> these two sections:
> 
>   . the text was repetitive, basically repeating the same boilerplate
>     stuff for each library/package
>   . the arrangement was not very logical (probably alphabetical), so
>     Python was near the end and Expat was the first one
>   . some of the data was outdated (e.g., the minimum supported Python
>     version) and some URLs used non-Texinfo markup
> 
> etc.
> 
> So I've rearranged and rewritten the text, including all the fixes
> that your patches provided.  Please take a look (commit 3401f94), and
> if I left something incorrect or unhandled, please tell.

Thanks, I took a look at your commit and it is indeed a nice cleanup of the whole
section. I've just realized that I forgot to CC the list in my v2.

I've found a few things that seem to have slipped through the cracks in your 
commit, so I'll send a fixup series later today.

Thanks for acknowledging me in the commit message. Just a side note, some projects 
use special trailers for this, like 'Suggested-by', 'Original-patch-by:', etc.

Cheers,

Philippe.