[Bug web/35777] New: no DFP announcement, no example text, very vague documentation

[Bug web/35777] New: no DFP announcement, no example text, very vague documentation

[bkoz at gcc dot gnu dot org]

Filing this so that the multiple requests to add DFP docs don't continue to be
ignored.

First asked here:
http://gcc.gnu.org/ml/gcc/2007-06/msg00048.html

Asked again 9 months later:
http://gcc.gnu.org/ml/gcc/2008-03/msg01025.html

Janis indicates that some patch was proposed, but then not applied for lack of
examples. I suggest instead a gradual approach, where something is applied
immediately to gcc-4.3/changes.html and then refined.

See:
http://gcc.gnu.org/ml/gcc-patches/2007-09/msg01139.html

For a starting point.

My preference would be for the examples and more extensive usage docs to go on
to the main manual node for DFP, and the announcement to link to that page.

The lapse in documenting this feature, after repeated requests to do so, is
highly annoying. GCC is a large and fast-moving target: it is hard for users
and maintainers to understand the whole  picture without the good-faith efforts
of developers to do due diligence and document new work. Significant new
features or experimental modes should be documented to give all maintainers an
equal foothold, and users a fighting chance to keep up with compiler
technology.

As it stands, DFP is not documented in changes.html, but *changes* to
*existing* DFP support *IS* mentioned. This is inconsistent.

In addition to the announcement text, the GCC manual is quite light on DFP
details:

Main DFP doc node:
http://gcc.gnu.org/onlinedocs/gcc/Decimal-Float.html#Decimal-Float

Does this need to be updated?

If DFP support and standard are a moving target, then it may be beneficial to
just add a dfp_status.html page, and update that in a similar manner to other
experimental support (like C++0x).

And the other hit:
http://gcc.gnu.org/onlinedocs/gcc/Option-Summary.html#Option-Summary

lists:
-mno-mfpgpr -mhard-dfp

for RS/6000 only. Documentation of this is:

The -mhard-dfp option allows GCC to generate the decimal floating point
instructions implemented on some POWER processors.

This is pretty vague, and I believe incorrect if DFP is now supported on x86,
as recent gcc-patches activity implies.

Timely action on behalf of DFP maintainers will be appreciated.

best,benjamin


-- 
           Summary: no DFP announcement, no example text, very vague
                    documentation
           Product: gcc
           Version: 4.3.1
            Status: UNCONFIRMED
          Severity: normal
          Priority: P3
         Component: web
        AssignedTo: unassigned at gcc dot gnu dot org
        ReportedBy: bkoz at gcc dot gnu dot org


http://gcc.gnu.org/bugzilla/show_bug.cgi?id=35777

[Bug web/35777] no DFP announcement, no example text, very vague documentation

[pinskia at gcc dot gnu dot org]

------- Comment #1 from pinskia at gcc dot gnu dot org  2008-03-31 19:52 -------
I can tell you that OpenMP has similar issues and nobody complained about that
except for me.  DFP is actually already documented in the correctly place:
http://gcc.gnu.org/onlinedocs/gcc-4.3.0/gcc/Decimal-Float.html

Fixed point extension is also documented the same place:
http://gcc.gnu.org/onlinedocs/gcc-4.3.0/gcc/Fixed_002dPoint.html

I don't see OpenMP documented there at all.


-- 


http://gcc.gnu.org/bugzilla/show_bug.cgi?id=35777

[Bug web/35777] no DFP announcement, no example text, very vague documentation

[janis at gcc dot gnu dot org]

------- Comment #2 from janis at gcc dot gnu dot org  2008-03-31 23:01 -------
I've added a note to gcc-4.3/changes.html in the "C Family" section, which is a
start towards fixing this issue.

I'll update the section of the GCC Manual that documents the extension to list
the latest published draft of TR 24732: N1241; not much has changed that isn't
covered by the changes between the drafts.  I'll look into adding some
examples.  The statement about changes to calling sequences can be expanded to
say what's expected to be stable starting in 4.3.0 and what is still
experimental and likely to change.

Should the GCC Manual talk about DPD and BID formats?


-- 

janis at gcc dot gnu dot org changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|                            |bje at gcc dot gnu dot org,
                   |                            |hjl at gcc dot gnu dot org


http://gcc.gnu.org/bugzilla/show_bug.cgi?id=35777

[Bug web/35777] no DFP announcement, no example text, very vague documentation

[bje at gcc dot gnu dot org]

------- Comment #3 from bje at gcc dot gnu dot org  2008-03-31 23:59 -------
I think the manual should just mention the existence of the formats (in the
same way that we mention that the compiler implements IEEE 754) and which
targets use which formats by default.


-- 


http://gcc.gnu.org/bugzilla/show_bug.cgi?id=35777

[Bug web/35777] no DFP announcement, no example text, very vague documentation

[brian at dessent dot net]

------- Comment #4 from brian at dessent dot net  2008-04-04 23:53 -------
Subject: Re:  no DFP announcement, no example text, very vague 
 documentation

pinskia at gcc dot gnu dot org wrote:

> I can tell you that OpenMP has similar issues and nobody complained about that
> except for me.  DFP is actually already documented in the correctly place:
> http://gcc.gnu.org/onlinedocs/gcc-4.3.0/gcc/Decimal-Float.html
> 
> Fixed point extension is also documented the same place:
> http://gcc.gnu.org/onlinedocs/gcc-4.3.0/gcc/Fixed_002dPoint.html
> 
> I don't see OpenMP documented there at all.

What about <http://gcc.gnu.org/onlinedocs/gcc-4.3.0/libgomp/>?


-- 


http://gcc.gnu.org/bugzilla/show_bug.cgi?id=35777

[Bug web/35777] no DFP announcement, no example text, very vague documentation

[pinskia at gcc dot gnu dot org]

------- Comment #5 from pinskia at gcc dot gnu dot org  2008-04-05 00:07 -------
(In reply to comment #4)
> > I don't see OpenMP documented there at all.
> 
> What about <http://gcc.gnu.org/onlinedocs/gcc-4.3.0/libgomp/>?

Still not part of the C/C++ Language Extension section of the documentation.  I
filed a bug about this too, see
http://gcc.gnu.org/bugzilla/show_bug.cgi?id=26154 I had to reopen it too.


-- 


http://gcc.gnu.org/bugzilla/show_bug.cgi?id=35777

[Bug web/35777] no DFP announcement, no example text, very vague documentation

[manu at gcc dot gnu dot org]

------- Comment #6 from manu at gcc dot gnu dot org  2009-08-06 14:41 -------
We can say that this is confirmed.

>From the messages, I think the people that could fix this bug do not see
clearly what the reporter wants. So probably a detailed list of TODO items
would help. It seems the request for updating gcc-4.3/changes.html is already
fixed.


-- 

manu at gcc dot gnu dot org changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
             Status|UNCONFIRMED                 |NEW
     Ever Confirmed|0                           |1
   Last reconfirmed|0000-00-00 00:00:00         |2009-08-06 14:41:25
               date|                            |


http://gcc.gnu.org/bugzilla/show_bug.cgi?id=35777

[Bug web/35777] no DFP announcement, no example text, very vague documentation

[bkoz at gcc dot gnu dot org]

------- Comment #7 from bkoz at gcc dot gnu dot org  2009-10-15 17:29 -------
There is now an announcement and a status page for the library work.

Thanks.


-- 

bkoz at gcc dot gnu dot org changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
             Status|NEW                         |RESOLVED
         Resolution|                            |FIXED


http://gcc.gnu.org/bugzilla/show_bug.cgi?id=35777