diff --git a/gcc/ChangeLog b/gcc/ChangeLog
index 24bf834c7bc..7ade881bea4 100644
--- a/gcc/ChangeLog
+++ b/gcc/ChangeLog
@@ -1,3 +1,11 @@
+2006-07-17  Nathan Sidwell  <nathan@codesourcery.com>
+
+	* doc/invoke.texi (RS/6000 and PowerPC Options): Document that
+	-mlongcall does not guarantee all calls will be long.
+	* doc/extend.texi (long_call/short_call): Document that longcall
+	does not guarantee a long call will be used.
+	(longcall/shortcall): Likewise.
+
 2006-07-18  Roger Sayle  <roger@eyesopen.com>
 
 	PR middle-end/28283
diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
index 91b52945866..7314e520ab5 100644
--- a/gcc/doc/extend.texi
+++ b/gcc/doc/extend.texi
@@ -1962,20 +1962,21 @@ from the USP register in the function prologue.
 This attribute specifies how a particular function is called on
 ARM@.  Both attributes override the @option{-mlong-calls} (@pxref{ARM Options})
 command line switch and @code{#pragma long_calls} settings.  The
-@code{long_call} attribute causes the compiler to always call the
-function by first loading its address into a register and then using the
-contents of that register.   The @code{short_call} attribute always places
+@code{long_call} attribute indicates that the function might be far
+away from the call site and require a different (more expensive)
+calling sequence.   The @code{short_call} attribute always places
 the offset to the function from the call site into the @samp{BL}
 instruction directly.
 
 @item longcall/shortcall
 @cindex functions called via pointer on the RS/6000 and PowerPC
-On the Blackfin, RS/6000 and PowerPC, the @code{longcall} attribute causes
-the compiler to always call this function via a pointer, just as it would if
-the @option{-mlongcall} option had been specified.  The @code{shortcall}
-attribute causes the compiler not to do this.  These attributes override
-both the @option{-mlongcall} switch and, on the RS/6000 and PowerPC, the
-@code{#pragma longcall} setting.
+On the Blackfin, RS/6000 and PowerPC, the @code{longcall} attribute
+indicates that the function might be far away from the call site and
+require a different (more expensive) calling sequence.  The
+@code{shortcall} attribute indicates that the function is always close
+enough for the shorter calling sequence to be used.  These attributes
+override both the @option{-mlongcall} switch and, on the RS/6000 and
+PowerPC, the @code{#pragma longcall} setting.
 
 @xref{RS/6000 and PowerPC Options}, for more information on whether long
 calls are necessary.
diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
index 1e73af45c96..7d72bd7e51d 100644
--- a/gcc/doc/invoke.texi
+++ b/gcc/doc/invoke.texi
@@ -11906,11 +11906,13 @@ names in the assembly language output using symbolic forms.
 @itemx -mno-longcall
 @opindex mlongcall
 @opindex mno-longcall
-Default to making all function calls indirectly, using a register, so
-that functions which reside further than 32 megabytes (33,554,432
-bytes) from the current location can be called.  This setting can be
-overridden by the @code{shortcall} function attribute, or by
-@code{#pragma longcall(0)}.
+By default assume that all calls are far away so that a longer more
+expensive calling sequence is required.  This is required for calls
+further than 32 megabytes (33,554,432 bytes) from the current location.
+A short call will be generated if the compiler knows
+the call cannot be that far away.  This setting can be overridden by
+the @code{shortcall} function attribute, or by @code{#pragma
+longcall(0)}.
 
 Some linkers are capable of detecting out-of-range calls and generating
 glue code on the fly.  On these systems, long calls are unnecessary and