Bug 7549 - gcc3.1: Documentation glitches in info-files
Summary: gcc3.1: Documentation glitches in info-files
Status: RESOLVED FIXED
Alias: None
Product: gcc
Classification: Unclassified
Component: other (show other bugs)
Version: 3.1
: P3 normal
Target Milestone: 4.0.0
Assignee: Not yet assigned to anyone
URL:
Keywords: documentation
Depends on:
Blocks:
 
Reported: 2002-08-09 03:46 UTC by Martin.Jost
Modified: 2005-02-06 19:42 UTC (History)
1 user (show)

See Also:
Host: hppa1.1-hp-hpux10.20
Target: hppa1.1-hp-hpux10.20
Build: hppa1.1-hp-hpux10.20
Known to work:
Known to fail:
Last reconfirmed: 2003-11-23 07:41:42


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description Martin.Jost 2002-08-09 03:46:01 UTC
I stumbled over some documentation glitches in the info-files:

Warning options:
"-Wall switches on a whole bunch of -W...-Options."
Unfortunately, the info-page only mentions this at
the end of the list. (At that point I already had hand-added all those
options, just to discard them again because this was redundant and
clobbered the cmd-line...)


"Options That Control Optimization"
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D

...
`-ftrapv'
     This option generates traps for signed overflow on addition,
     subtraction, multiplication operations.

Huh ?!
I guess this will make the program slower (because of the checks) but
better checked. So why is this listed under 'Optimization' ??
Shouldn't this be included under another section ??

"
`-ffunction-sections'
`-fdata-sections'
     Place each function or data item into its own section in the =
output
     file if the target supports arbitrary sections.  The name of the
     function or the name of the data item determines the section's =
name
     in the output file.

     Use these options on systems where the linker can perform
     optimizations to improve locality of reference in the instruction
     space.  HPPA processors running HP-UX and Sparc processors running
     Solaris 2 have linkers with such optimizations.  Other systems
     using the ELF object format as well as AIX may have these
     optimizations in the future.
"

I'm using gcc on HPUX 10.20 (HPPA)
Nevertheless I get:
cc1plus: warning: -ffunction-sections not supported for this target
cc1plus: warning: -fdata-sections not supported for this target

Release:
3.1

Environment:
System: HP-UX lasagne B.10.20 U 9000/785 2007890687 unlimited-user =
license

host: hppa1.1-hp-hpux10.20
build: hppa1.1-hp-hpux10.20
target: hppa1.1-hp-hpux10.20
configured with: ../gcc-3.1/configure -prefix=3D/pd/gcc-3.1 =
--with-gnu-as --with-as=3D/pd/binutils/bin/as =
--host=3Dhppa1.1-hp-hpux10.20 --without-gnu-ld

Unformatted:
 X-send-pr-version: 3.113
 X-GNATS-Notify:
Comment 1 Martin.Jost 2002-08-09 03:46:01 UTC
Fix:

------------------------------------------------------------------------=
-----
Martin Jost		Tel.: 	++49/89/722-44248
Siemens AG		FAX.:	++49/89/722-53418
ICN WN OP TDC TC 2	(Please note my name on the FAX !)
Hofmannstr. 51		Room 1714-560
D-81359 M=FCnchen	Martin.Jost@icn.siemens.de
Comment 2 Dara Hazeghi 2003-05-26 21:26:00 UTC
Hello,

I'm not sure what the issue you describe here is. Examining the online docs, which I assume are 
similar to the texinfo ones, -Wall says:

-Wall      
All of the above -W options combined.  This enables all the warnings about constructions that 
some users consider questionable, and that are easy to avoid (or modify to prevent the warning), 
even in conjunction with macros.  This also enables some language-specific warnings described in 
C++ Dialect Options and Objective-C Dialect Options.

Furthermore, -fdata-sections and -ffunction-sections are included in the manual as global 
options, and are not specifically mentioned to support hp-ux. Do you think we should specify 
which targets they do not support? Thanks,

Dara

P.S. We really need to have a section for documentation bugs...
Comment 3 Andrew Pinski 2003-05-26 21:29:02 UTC
See Dara's question.
Comment 4 Martin.Jost 2003-06-02 10:15:44 UTC
Daras comments marked with ">"

1. -Wall:
>I'm not sure what the issue you describe here is. Examining the online docs, 
>which I assume are similar to the texinfo ones, -Wall says:
>-Wall      
>All of the above -W options combined. [...]

Yes, that's clear. My problem was the ordering for sequential reading.
If you read the options-section for warnings/errors in sequential order, all 
the "nitty gritty options" are explained _first_, _followed_ by -Wall.
I would like to see a sort of "forward reference" of the kind:
"Please note that the option "-Wall" (see below) will switch on all of the 
following options:
- ...
- ...
"
(And (I would like it) a remark: "Switched on by '-Wall'" at the relevant 
option)

I read all the options (sequentially), trying to decide which one to use; so -
Wall came as big suprise to me...


2. -fdata-sections and -ffunction-sections 
>Furthermore, -fdata-sections and -ffunction-sections are included in the 
>manual as global 
>options, and are not specifically mentioned to support hp-ux. Do you think we 
>should specify which targets they do not support?

The problem is, that it is explicitely mentioned, that HPPA _is_ supported, 
when in fact it doesn't seem to be:

Form the info-file:
"
`-ffunction-sections'
`-fdata-sections'
[...]
HPPA processors running HP-UX and Sparc processors running
=============================
     Solaris 2 have linkers with such optimizations.
               =====================================
"

> P.S. We really need to have a section for documentation bugs...

Yes, I agree !

P.S.:
I hope, I succeded this time to make my point clear.
Sorry for the late reply, I had been on holiday.
Thanks for your work on this !
Comment 5 Dara Hazeghi 2003-06-05 00:41:30 UTC
Hello,

I still can't seem to find the point you're referring to. I'm using the web manual, which is generated 
from the, .texi files (same place the .info files come from). Looking at the gcc 3.3 manual (online), I 
don't see the text you reference. Can you check the online manual and give me the URL which 
contains the text you quote? Thanks,

Dara
Comment 6 Martin.Jost 2003-06-05 11:40:59 UTC
Ahh, sorry, I didn't got, that you are asking for the references in the manual.
Here they are:

===================== -Wall ===================================================
http://gcc.gnu.org/onlinedocs/gcc-3.3/gcc/Warning-Options.html#Warning%20Options

"
-Wall 
All of the above -W options combined [...]
"

This comes waayyy down on the page. 
As mentioned I would like to a see a reference to -Wall at the beginning of 
this section and probably a note coming with each of the option, if it is 
included in -Wall. (This would make it easier to decide which -W... to use)

Funnily there are already some forward references to Wall:
"-Wformat is included in -Wall. "
"-Wnonnull is included in -Wall and -Wformat."
"-Wstrict-aliasing [...] It is included in -Wall."

For the optimization-options this is already done !
See http://gcc.gnu.org/onlinedocs/gcc-3.3/gcc/Optimize-Options.html#Optimize%
20Options
"
-O turns on the following optimization flags: 
          -fdefer-pop 
[...]
          -fcprop-registers
"
And (e.g.)
"
-fforce-mem 
[...]
Enabled at levels -O2, -O3, -Os. 
"

=================== -ftrapv =================================================
Has already been moved to "Code generation options"
(Where it fits much better)
So this is solved.

============ `-ffunction-sections' `-fdata-sections' ========================
There is no mentioning of HPPA here any more. So this is also solved.

Martin

P.S.:
Thanks for following up through all the miss-understandings so far !
Comment 7 Dara Hazeghi 2003-06-05 16:36:30 UTC
Thanks, I see what you mean now. I'll try to come up with a patch for this at some point soon, if 
somebody doesn't beat me to it...
Comment 8 GCC Commits 2005-02-06 19:37:29 UTC
Subject: Bug 7549

CVSROOT:	/cvs/gcc
Module name:	gcc
Changes by:	jsm28@gcc.gnu.org	2005-02-06 19:37:25

Modified files:
	gcc            : ChangeLog 
	gcc/doc        : invoke.texi gcc.texi 

Log message:
	PR other/7549
	* doc/invoke.texi: Mention for each option included in -Wall that
	it is included in -Wall.
	* doc/gcc.texi: Update copyright and last modification date.

Patches:
http://gcc.gnu.org/cgi-bin/cvsweb.cgi/gcc/gcc/ChangeLog.diff?cvsroot=gcc&r1=2.7396&r2=2.7397
http://gcc.gnu.org/cgi-bin/cvsweb.cgi/gcc/gcc/doc/invoke.texi.diff?cvsroot=gcc&r1=1.573&r2=1.574
http://gcc.gnu.org/cgi-bin/cvsweb.cgi/gcc/gcc/doc/gcc.texi.diff?cvsroot=gcc&r1=1.65&r2=1.66

Comment 9 Andrew Pinski 2005-02-06 19:42:36 UTC
Fixed in 4.0.0.