[Resend] Document -mimpure-text (for Solaris)

[Florian Weimer]

[This is a resend (yes, I fixed that typo).  Sorry if I missed a
previous approval.]

The error message "relocations remain against allocatable but
non-writable sections" is not clearly explained anywere (the ld(1)
manpage even says that the "-z text" option is not the default!).  As
a result, people regularly use "-mimpure-text" without justification.

The documentation below tries to address this problem.

Okay for mainline?

Index: invoke.texi
===================================================================
RCS file: /cvs/gcc/gcc/gcc/doc/invoke.texi,v
retrieving revision 1.283
diff -u -r1.283 invoke.texi
--- invoke.texi	21 May 2003 21:23:03 -0000	1.283
+++ invoke.texi	27 May 2003 15:59:27 -0000
@@ -5924,6 +5924,22 @@
 Generate output containing quad-word (long double) floating point
 instructions.
 
+@item -mimpure-text
+@opindex mimpure-text
+@option{-mimpure-text}, used in addition to @option{-shared}, tells
+the compiler to not pass @option{-z text} to the linker when linking a
+shared object.  Using this option, you can link position-dependent
+code into a shared object.  
+
+@option{-mimpure-text} suppresses the ``relocations remain against
+allocatable but non-writable sections'' linker error message.
+However, the necessary relocations will trigger copy-on-write, and the
+shared object is not actually shared across processes.  Instead of
+using @option{-mimpure-text}, you should compile all source code with
+@option{-fpic} or @option{-fPIC}.
+
+This option is only available on SunOS and Solaris.
+
 @item -msoft-quad-float
 @opindex msoft-quad-float
 Generate output containing library calls for quad-word (long double)