Bug#654931: gcc-4.6: missing manpage
 

Package: gcc-4.6
Version: 4.6.2-11
Severity: wishlist
Tags: patch

gcc-4.6 and company are missing manpages. I am aware that this is a
result of the upstream manpages being non-free. Since policy requires a
manpage for each binary, I am including a skeletal manpage that covers
some of the most commonly used options. I will update it further in the
future.

-- System Information:
Debian Release: wheezy/sid
APT prefers unstable
APT policy: (500, 'unstable'), (1, 'experimental')
Architecture: amd64 (x86_64)

Kernel: Linux 3.1.0-1-amd64 (SMP w/4 CPU cores)
Locale: LANG=en_US.UTF-8, LC_CTYPE=en_US.UTF-8 (charmap=UTF-8)
Shell: /bin/sh linked to /bin/dash

Versions of packages gcc-4.6 depends on:
ii binutils 2.22-3
ii cpp-4.6 4.6.2-11
ii gcc-4.6-base 4.6.2-11
ii libc6 2.13-24
ii libgcc1 1:4.6.2-11
ii libgmp10 2:5.0.2+dfsg-2
ii libgomp1 4.6.2-11
ii libmpc2 0.9-4
ii libmpfr4 3.1.0-3
ii libquadmath0 4.6.2-11
ii zlib1g 1:1.2.3.4.dfsg-3

Versions of packages gcc-4.6 recommends:
ii libc6-dev 2.13-24

Versions of packages gcc-4.6 suggests:
pn binutils-gold <none>
pn gcc-4.6-doc <none>
pn gcc-4.6-locales <none>
pn gcc-4.6-multilib 4.6.2-11
pn libgcc1-dbg <none>
pn libgomp1-dbg <none>
pn libmudflap0-4.6-dev <none>
pn libmudflap0-dbg <none>
pn libquadmath0-dbg <none>

-- no debconf information

--
brian m. carlson / brian with sandals: Houston, Texas, US
+1 832 623 2791 | http://www.crustytoothpaste.net/~bmc | My opinion only
OpenPGP: RSA v4 4096b: 88AC E9B2 9196 305B A994 7552 F1BA 225C 0223 B187
'"
."-
." Copyright © 2012 brian m. carlson
."
." This documentation is free software; you can redistribute it and/or modify
." it under the terms of your choice of:
." * version 2 of the GNU General Public License as published by the Free
." Software Foundation;
." * version 2.0 of the Apache License as published by the Apache Software
." Foundation; or
." * version 3.0 of the Creative Commons Attribution-ShareAlike License as
." published by Creative Commons.
."
." This documentation is distributed in the hope that it will be useful,
." but WITHOUT ANY WARRANTY; without even the implied warranty of
." MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
." relevant licenses for more details.
."
." The only reference used here was the output of gcc itself. No reference was
." made to other documentation during the writing of this manual page.
.TH GCC 1 2012-01-01 GNU Debian
.SH NAME
gcc - the GNU C Compiler
.SH SYNOPSIS
.B gcc
[c
.IR options "] " FILE ...
.SH DESCRIPTION
.B gcc
is the GNU C compiler. It is used to compile programs written in C or similar
languages into programs and libraries for execution.
.P
While the
.B gcc
frontentd can also be used to compile other languages (see the
.B -x
option), using the appropriate frontend is often better as it often includes
important libraries and options needed for successful compilation. These
frontends are
.B g++
for C++,
.B gfortran
for Fortran,
.B gobjc
for Objective-C,
.B gobjc++
for Objective-C++, and
.B gccgo
for Go.
.B cpp
may be used if only the C preprocessor is needed; alternately, the
.B -E
option to an appropriate frontend may be used.
.SH OPTIONS
.B gcc
supports a large number of options. Most of these options can be used with any
frontend, but some are specific to a particular language or platform (processor
architecture or operating system).
.SS "General Options"
.TP
.B -c
Invoke only the preprocessor (if appropriate), the compiler, and the assembler.
The result is an object file for the target platform.
.TP
.B -E
Invoke only the preprocessor. The result is preprocessed source.
.TP
.BI "-o " FILE
Places the output of the compilation processes into
.IR FILE .
.TP
.B -pipe
Use pipes instead of temporary files to pass data between compilation stages.
.TP
.B -S
Invoke only the preprocessor (if appropriate) and the compiler. The result is
assembly for the target platform.
.TP
.B --save-temps
Save the temporary files created during the compilation process. This is useful
when filing a bug report.
.TP
.B -v
Prints information about the version and configuration of the compiler, and if
any compilation or preprocessing step occurs, also prints information about the
compilation process used in those steps.
.TP
.BI -Wa, OPTION
Pass OPTION to the assembler.
.TP
.BI -Wl, OPTION
Pass OPTION to the linker.
.TP
.BI -Wp, OPTION
Pass OPTION to the preprocessor.
.TP
.BI "-x " LANGUAGE
The following files are to be interpreted as being in LANGUAGE.
This continues until another
.B -x
option is given.
If LANGUAGE is
.BR none ,
revert to autodetection based on the file's extension.
Valid values include
.BR c ,
.BR c++ ,
.BR assembler ,
and
.BR none .
.SS "Options for C-like Languages"
.TP
.B -ansi
Equivalent to
.B -std=c89
for C and
.B -std=c++98
for C++.
.TP
.BR -std =fISTANDARDfP
Specify that the input conforms and the compiler should conform to STANDARD.
For C, this can be
.BR c89 ,
.BR c90 ,
or
.BR iso9899:1990
(for the ISO 1990 C standard);
.BR iso9899:199409
(for the ISO 1990 C standard as amended in 1994);
.BR c99 ,
.BR c9x ,
.BR iso9899:1999 ,
or
.BR iso9899:199x
(for the ISO 1999 C standard);
.B c1x
or
.B c11
(for the ISO 2011 C standard);
or one of
.BR gnu89 ,
.BR gnu90 ,
.BR gnu99 ,
.BR gnu9x ,
.BR gnu1x ,
or
.B gnu11
for the corresponding standard with GNU extensions.
For C++, this can be
.BR c++98 ,
or
.BR c++03
(for the ISO 1998 C++ standard as amended in 2003);
.BR c++0x
(for the ISO 2011 C++ standard);
or one of
.BR gnu++98
or
.BR gnu++0x
for the corresponding standard with GNU extensions.
.SS "Warning Options"
.PP
All the options beginning with
.B -W
can take a negative form by using
.B -Wno-
instead. If multiple arguments modify the same warning, the last modification
wins.
.TP
.B -pedantic
Warn whenever the appropriate standard requires a diagnostic.
.TP
.B -pedantic-errors
Signal an error whenever the appropriate standard requires a diagnostic.
.TP
.B -Wall
Enable most warnings.
.TP
.B -Werror
Treat all warnings as errors.
.SS "Options to Control Code Generation and Optimization"
.TP
.BR -ffunction-sections
Place each function in its own section. This may be needed on certain
architectures that have branch instructions that have a limited distance.
.TP
.BR -flto
When compiling, generate an intermediate representation as well as normal code.
When linking, use this intermediate representation to optimize across files.
In order to work, this option must be given both when compiling and linking.
.TP
.BR -fomit-frame-pointer
Omit the frame pointer. On some architectures, the register normally used for
the frame pointer can be pressed into use, which may allow the compiler to
generate code. On other architectures, the frame pointer is part of the
standard calling sequence and omitting it is not useful. Using this option may
impede debugging on some architectures.
.TP
.BR -fPIC
Generate position-independent code. This is generally required for shared
libraries to function correctly. On some platforms, all code is
position-independent and this option has no effect. Using it anyway will
produce a warning.
.TP
.BR -fPIE
Generate position-independent code suitable only for executables. The resulting
code cannot be linked into a shared library, but is still useful to generate
binaries that will work with ASLR (address space layout randomization). On some
platforms, all code is position-independent and this option has no effect.
Using it anyway will produce a warning.
.TP
.BR -fstack-protector
Generate code to check for stack overflows in most functions.
.TP
.BR -fstack-protector-all
Generate code to check for stack overflows in all functions, no matter how
small.
.TP
.BR -fwhole-program
This option tells the compiler to try to optimize the program as a whole. This
only works when all the source files are passed on the command line.
.TP
.BR -fwrapv
Signed overflow is undefined. This option makes the compiler assume that signed
overflow wraps around. The use of this option may enable certain optimizations
and disable others as a result of this assumption.
.TP
.BR -g
Generate debugging information in the default format for this platform.
Enabling optimization may cause the debugging information to appear strange.
.TP
.BI -O NUMBER
If NUMBER is 0, do not optimize the code at all. Otherwise, if NUMBER is
positive, optimize the code. NUMBER may be as large as 3, each value taking
progressively more time and memory to optimize.
.TP
.B -Ofast
Optimize the code aggressively without regard for standards compliance.
.TP
.B -Os
Optimize the code for size, not speed.
.TP
.B -shared
Generate a shared library. Generally this will be used with
.BR -fPIC .
.SS "Options to Control Code Syntax"
.TP
.B -fpermissive
Be more lenient in accepting invalid code. Since
.B gcc
tends to become stricter over time, especially with regard to C++ conformance,
this option can be used to allow older code to compile temporarily.
.TP
.B -fsigned-char
.TP
.B -funsigned-char
The
.B char
type, while distinct from
.B "signed char"
and
.BR "unsigned char" ,
has the range of values of either the former or the latter. Which one
specifically is dependent on the architecture and platform, and is usually
specified in the appropriate ABI. This option allows the default to be changed
for a given file or files.
.SH EXIT STATUS
Exits 0 on success, or nonzero on error.
.".SH FILES
.SH "CONFORMING TO"
.B gcc
attempts conforms to the relevant standards when an appropriate
.B -std
option is specified with
.BR -pedantic .
If it does not, please file a bug.
.".SH NOTES
.SH BUGS
When reporting bugs, please follow the directions listed in
.IR /usr/share/doc/gcc/README.Bugs .
Without providing sufficient information, your bug will not be able to be
reproduced or investigated and therefore will not be able to be fixed.
.PP
This manual page was written because the manual pages provided with
.B gcc
are not Free Software according to the Debian Free Software Guidelines. As
such, you should not bother the Free Software Foundation with it. Please report
bugs in this manual page to brian m. carlson <sandals@crustytoothpaste.net>.
.".SH "SEE ALSO"
." vim: set ft=groff:

Bug#654931: gcc-4.6: missing manpage
 

tags 654931 + wontfix
thanks

On 01/06/2012 11:12 PM, brian m. carlson wrote:
> Package: gcc-4.6
> Version: 4.6.2-11
> Severity: wishlist
> Tags: patch
>
> gcc-4.6 and company are missing manpages. I am aware that this is a
> result of the upstream manpages being non-free.

> Since policy requires a
> manpage for each binary, I am including a skeletal manpage that covers
> some of the most commonly used options. I will update it further in the
> future.

won't fix in the gcc-4.6 package; clearly these "skeletal" pages are not part of
the upstream sources. please package those as a separate package if you intend
to maintain these on a regular basis.



--
To UNSUBSCRIBE, email to debian-gcc-REQUEST@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
Archive: 4F07EBE5.4020809@debian.org">http://lists.debian.org/4F07EBE5.4020809@debian.org

Bug#654931: gcc-4.6: missing manpage
 

On Sat, Jan 07, 2012 at 07:53:25AM +0100, Matthias Klose wrote:
> won't fix in the gcc-4.6 package; clearly these "skeletal" pages are
> not part of the upstream sources. please package those as a separate
> package if you intend to maintain these on a regular basis.

Lots of Debian packages include manpages that are not part of the
upstream source, and Policy mandates a manpage *in the same package*.
I'd like you to reconsider, especially since having some manpage, even
if it isn't complete, is a lot better for users than having no manpage
at all.

--
brian m. carlson / brian with sandals: Houston, Texas, US
+1 832 623 2791 | http://www.crustytoothpaste.net/~bmc | My opinion only
OpenPGP: RSA v4 4096b: 88AC E9B2 9196 305B A994 7552 F1BA 225C 0223 B187

Bug#654931: gcc-4.6: missing manpage
 

On 01/07/2012 05:36 PM, brian m. carlson wrote:
> On Sat, Jan 07, 2012 at 07:53:25AM +0100, Matthias Klose wrote:
>> won't fix in the gcc-4.6 package; clearly these "skeletal" pages are
>> not part of the upstream sources. please package those as a separate
>> package if you intend to maintain these on a regular basis.
>
> Lots of Debian packages include manpages that are not part of the
> upstream source, and Policy mandates a manpage *in the same package*.
> I'd like you to reconsider, especially since having some manpage, even
> if it isn't complete, is a lot better for users than having no manpage
> at all.

we have the original man pages in non-free (at least we had these packaged for
earlier versions [1]; feel free to package these, I assume Nikita would welcome
the help). These are far better than anything written from scratch. If you
include the mediocre manpages into the gcc packages, then you have to divert
each manpage in the non-free man-page packages to replace the incomplete man
pages. The better solution is to recommend or depend on the gnu-manpage |
rewritten-manpage packages.

Matthias

[1] http://packages.qa.debian.org/g/gcc-4.3-doc-non-dfsg.html



--
To UNSUBSCRIBE, email to debian-gcc-REQUEST@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
Archive: 4F088ED5.7000209@debian.org">http://lists.debian.org/4F088ED5.7000209@debian.org

Bug#654931: gcc-4.6: missing manpage
 

> On 01/07/2012 05:36 PM, brian m. carlson wrote:
> > On Sat, Jan 07, 2012 at 07:53:25AM +0100, Matthias Klose wrote:
> >> won't fix in the gcc-4.6 package; clearly these "skeletal" pages are
> >> not part of the upstream sources. please package those as a separate
> >> package if you intend to maintain these on a regular basis.
> >
> > Lots of Debian packages include manpages that are not part of the
> > upstream source, and Policy mandates a manpage *in the same package*.
> > I'd like you to reconsider, especially since having some manpage, even
> > if it isn't complete, is a lot better for users than having no manpage
> > at all.
>
> we have the original man pages in non-free (at least we had these
> packaged for earlier versions [1]; feel free to package these, I assume
> Nikita would welcome the help).

Sure I will welcome help on updating gcc-doc packages.

I have very limited resource these days so I'm not sure when I will be able
to update gcc-doc myself (although I hope that will happen before it is
too late for wheezy).

Nikita

Bug#654931: gcc-4.6: missing manpage
 

On Sat, Jan 07, 2012 at 07:28:37PM +0100, Matthias Klose wrote:
> we have the original man pages in non-free (at least we had these packaged for
> earlier versions [1]; feel free to package these, I assume Nikita would welcome
> the help). These are far better than anything written from scratch. If you

I'm aware of this. However, the extent of my use of non-free is for
firmware.

> include the mediocre manpages into the gcc packages, then you have to divert
> each manpage in the non-free man-page packages to replace the incomplete man
> pages. The better solution is to recommend or depend on the gnu-manpage |
> rewritten-manpage packages.

I wrote the manpages to provide something useful for gcc because (a)
it's buggy according to Policy, (b) upstream isn't clueful enough to
relicense the documentation under a free license, and (c) the Debian
distribution is lacking manual pages for arguably one of its most
important packages. Plus, I might make use of them myself instead of
trying to peruse the --help output every time.

I'll look into packaging them separately, but I would like to point out
that even if I do your package will remain buggy according to Policy.
Do you have a preference on the name of the package?

--
brian m. carlson / brian with sandals: Houston, Texas, US
+1 832 623 2791 | http://www.crustytoothpaste.net/~bmc | My opinion only
OpenPGP: RSA v4 4096b: 88AC E9B2 9196 305B A994 7552 F1BA 225C 0223 B187

Bug#654931: gcc-4.6: missing manpage
 

On 01/07/2012 08:51 PM, brian m. carlson wrote:
> Do you have a preference on the name of the package?

what about {cpp,gcc,g++,gfortran}-4.x-man?



--
To UNSUBSCRIBE, email to debian-gcc-REQUEST@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
Archive: 4F0B31F4.9020101@debian.org">http://lists.debian.org/4F0B31F4.9020101@debian.org

Bug#654931: gcc-4.6: missing manpage
 

On Mon, Jan 09, 2012 at 07:29:08PM +0100, Matthias Klose wrote:
> On 01/07/2012 08:51 PM, brian m. carlson wrote:
> > Do you have a preference on the name of the package?
>
> what about {cpp,gcc,g++,gfortran}-4.x-man?

I was hoping to ship at most one package per version. There's simply no
way that ftpmasters are going to allow shipping a single manpage in each
package. My original thought was gcc-manpages, but if you'd prefer a
single package per version, I can do that, too.

--
brian m. carlson / brian with sandals: Houston, Texas, US
+1 832 623 2791 | http://www.crustytoothpaste.net/~bmc | My opinion only
OpenPGP: RSA v4 4096b: 88AC E9B2 9196 305B A994 7552 F1BA 225C 0223 B187

Bug#654931: gcc-4.6: missing manpage
 

On 01/09/2012 08:22 PM, brian m. carlson wrote:
> On Mon, Jan 09, 2012 at 07:29:08PM +0100, Matthias Klose wrote:
>> On 01/07/2012 08:51 PM, brian m. carlson wrote:
>>> Do you have a preference on the name of the package?
>>
>> what about {cpp,gcc,g++,gfortran}-4.x-man?
>
> I was hoping to ship at most one package per version. There's simply no
> way that ftpmasters are going to allow shipping a single manpage in each
> package. My original thought was gcc-manpages, but if you'd prefer a
> single package per version, I can do that, too.

fine too. but ftp-masters did already accept the packaging of the non-free
man-pages (and docs). as long as it is fine to have a manpage without a binary.
otoh we could merge the existing non-free doc packages to one as well.



--
To UNSUBSCRIBE, email to debian-gcc-REQUEST@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
Archive: 4F0B7371.7080004@debian.org">http://lists.debian.org/4F0B7371.7080004@debian.org

Bug#654931: gcc-4.6: missing manpage
 

> > I was hoping to ship at most one package per version. There's simply
> > no way that ftpmasters are going to allow shipping a single manpage in
> > each package. My original thought was gcc-manpages, but if you'd
> > prefer a single package per version, I can do that, too.
>
> fine too. but ftp-masters did already accept the packaging of the
> non-free man-pages (and docs). as long as it is fine to have a manpage
> without a binary. otoh we could merge the existing non-free doc packages
> to one as well.

gcc-doc packages used to have *.info files as well - and those are pretty
large...



--
To UNSUBSCRIBE, email to debian-gcc-REQUEST@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
Archive: 201201100721.38579@blacky.localdomain">http://lists.debian.org/201201100721.38579@blacky.localdomain