diff --git a/ChangeLog b/ChangeLog
index 8529a54d1..b2ddf5a3d 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+Fri Mar 10 10:48:00 2000  Richard Frith-Macdonald <richard@brainstorm.co.uk>
+
+	* Documentation/gsdoc/NSView.gsdoc: Added a little documentation for
+	methods for removing subviews from a view.
+
 Fri Mar 10 09:35:00 2000  Richard Frith-Macdonald <richard@brainstorm.co.uk>
 
 	* Source/NSView.m: Make ([removeSubview:]) public.
diff --git a/Documentation/gsdoc/NSView.gsdoc b/Documentation/gsdoc/NSView.gsdoc
index e759124c5..191b7bbeb 100644
--- a/Documentation/gsdoc/NSView.gsdoc
+++ b/Documentation/gsdoc/NSView.gsdoc
@@ -571,13 +571,43 @@
         <method type="void">
           <sel>removeFromSuperview</sel>
           <desc>
+	    <p>
+	      Removes the receiver from its superviews list of subviews,
+	      by invoking the superviews [-removeSubview:] method, and
+	      marks the rectangle that the reciever occupied in the
+	      superview as needing redisplay.
+	    </p>
+	    <p>
+	       This is dangerous to use during display, since it alters the
+	       rectangles needing display.
+	    </p>
           </desc>
         </method>
         <method type="void">
           <sel>removeFromSuperviewWithoutNeedingDisplay</sel>
           <desc>
+	    <p>
+	      Removes the receiver from its superviews list of subviews,
+	      by invoking the superviews [-removeSubview:] method.
+	    </p>
           </desc>
         </method>
+        <method type="void">
+          <sel>removeSubview:</sel>
+          <arg type="NSView*">aView</arg>
+          <desc>
+	    <p>
+	      Removes the view from the receivers list of subviews
+	      and from the responder chain.
+	    </p>
+	    <p>
+              Also invokes [aView -viewWillMoveToWindow: nil] to handle
+	      removal of aView (and recursively, its children) from its
+	      window - performing tidyup by invalidating cursor rects etc.
+	    </p>
+          </desc>
+	  <standards><NotMacOS-X/><NotOpenStep/></standards>
+        </method>
         <method type="void">
           <sel>removeTrackingRect:</sel>
           <arg type="NSTrackingRectTag">aTag</arg>
diff --git a/Documentation/gsdoc/NSView.html b/Documentation/gsdoc/NSView.html
index 53f2480f9..e0b83d4f9 100644
--- a/Documentation/gsdoc/NSView.html
+++ b/Documentation/gsdoc/NSView.html
@@ -113,53 +113,54 @@
 <li><a href="NSView.html#method-87">-removeCursorRect:cursor:</a>
 <li><a href="NSView.html#method-88">-removeFromSuperview</a>
 <li><a href="NSView.html#method-89">-removeFromSuperviewWithoutNeedingDisplay</a>
-<li><a href="NSView.html#method-90">-removeTrackingRect:</a>
-<li><a href="NSView.html#method-91">-renewGState</a>
-<li><a href="NSView.html#method-92">-replaceSubview:</a>
-<li><a href="NSView.html#method-93">-resetCursorRects</a>
-<li><a href="NSView.html#method-94">-resizeSubviewsWithOldSize:</a>
-<li><a href="NSView.html#method-95">-resizeWithOldSuperviewSize:</a>
-<li><a href="NSView.html#method-96">-rotateByAngle:</a>
-<li><a href="NSView.html#method-97">-scaleUnitSquareToSize:</a>
-<li><a href="NSView.html#method-98">-scrollClipView:</a>
-<li><a href="NSView.html#method-99">-scrollPoint:</a>
-<li><a href="NSView.html#method-100">-scrollRect:</a>
-<li><a href="NSView.html#method-101">-scrollRectToVisible:</a>
-<li><a href="NSView.html#method-102">-setAutoresizesSubviews:</a>
-<li><a href="NSView.html#method-103">-setAutoresizingMask:</a>
-<li><a href="NSView.html#method-104">-setBounds:</a>
-<li><a href="NSView.html#method-105">-setBoundsOrigin:</a>
-<li><a href="NSView.html#method-106">-setBoundsRotation:</a>
-<li><a href="NSView.html#method-107">-setBoundsSize:</a>
-<li><a href="NSView.html#method-108">-setFrame:</a>
-<li><a href="NSView.html#method-109">-setFrameOrigin:</a>
-<li><a href="NSView.html#method-110">-setFrameRotation:</a>
-<li><a href="NSView.html#method-111">-setFrameSize:</a>
-<li><a href="NSView.html#method-112">-setInterfaceStyle:</a>
-<li><a href="NSView.html#method-113">-setNeedsDisplay:</a>
-<li><a href="NSView.html#method-114">-setNeedsDisplayInRect:</a>
-<li><a href="NSView.html#method-115">-setNextKeyView:</a>
-<li><a href="NSView.html#method-116">-setPostsBoundsChangedNotifications:</a>
-<li><a href="NSView.html#method-117">-setPostsFrameChangedNotifications:</a>
-<li><a href="NSView.html#method-118">-setToolTip:</a>
-<li><a href="NSView.html#method-119">-setUpGState</a>
-<li><a href="NSView.html#method-120">-shouldDelayWindowOrderingForEvent:</a>
-<li><a href="NSView.html#method-121">-shouldDrawColor</a>
-<li><a href="NSView.html#method-122">-sortSubviewsUsingFunction:context:</a>
-<li><a href="NSView.html#method-123">-subviews</a>
-<li><a href="NSView.html#method-124">-superview</a>
-<li><a href="NSView.html#method-125">-tag</a>
-<li><a href="NSView.html#method-126">-toolTip</a>
-<li><a href="NSView.html#method-127">-translateOriginToPoint:</a>
-<li><a href="NSView.html#method-128">-unlockFocus</a>
-<li><a href="NSView.html#method-129">-unregisterDraggedTypes</a>
-<li><a href="NSView.html#method-130">-viewWillMoveToSuperview:</a>
-<li><a href="NSView.html#method-131">-viewWillMoveToWindow:</a>
-<li><a href="NSView.html#method-132">-viewWithTag:</a>
-<li><a href="NSView.html#method-133">-visibleRect</a>
-<li><a href="NSView.html#method-134">-widthAdjustLimit</a>
-<li><a href="NSView.html#method-135">-window</a>
-<li><a href="NSView.html#method-136">-writeEPSInsideRect:toPasteboard:</a>
+<li><a href="NSView.html#method-90">-removeSubview:</a>
+<li><a href="NSView.html#method-91">-removeTrackingRect:</a>
+<li><a href="NSView.html#method-92">-renewGState</a>
+<li><a href="NSView.html#method-93">-replaceSubview:</a>
+<li><a href="NSView.html#method-94">-resetCursorRects</a>
+<li><a href="NSView.html#method-95">-resizeSubviewsWithOldSize:</a>
+<li><a href="NSView.html#method-96">-resizeWithOldSuperviewSize:</a>
+<li><a href="NSView.html#method-97">-rotateByAngle:</a>
+<li><a href="NSView.html#method-98">-scaleUnitSquareToSize:</a>
+<li><a href="NSView.html#method-99">-scrollClipView:</a>
+<li><a href="NSView.html#method-100">-scrollPoint:</a>
+<li><a href="NSView.html#method-101">-scrollRect:</a>
+<li><a href="NSView.html#method-102">-scrollRectToVisible:</a>
+<li><a href="NSView.html#method-103">-setAutoresizesSubviews:</a>
+<li><a href="NSView.html#method-104">-setAutoresizingMask:</a>
+<li><a href="NSView.html#method-105">-setBounds:</a>
+<li><a href="NSView.html#method-106">-setBoundsOrigin:</a>
+<li><a href="NSView.html#method-107">-setBoundsRotation:</a>
+<li><a href="NSView.html#method-108">-setBoundsSize:</a>
+<li><a href="NSView.html#method-109">-setFrame:</a>
+<li><a href="NSView.html#method-110">-setFrameOrigin:</a>
+<li><a href="NSView.html#method-111">-setFrameRotation:</a>
+<li><a href="NSView.html#method-112">-setFrameSize:</a>
+<li><a href="NSView.html#method-113">-setInterfaceStyle:</a>
+<li><a href="NSView.html#method-114">-setNeedsDisplay:</a>
+<li><a href="NSView.html#method-115">-setNeedsDisplayInRect:</a>
+<li><a href="NSView.html#method-116">-setNextKeyView:</a>
+<li><a href="NSView.html#method-117">-setPostsBoundsChangedNotifications:</a>
+<li><a href="NSView.html#method-118">-setPostsFrameChangedNotifications:</a>
+<li><a href="NSView.html#method-119">-setToolTip:</a>
+<li><a href="NSView.html#method-120">-setUpGState</a>
+<li><a href="NSView.html#method-121">-shouldDelayWindowOrderingForEvent:</a>
+<li><a href="NSView.html#method-122">-shouldDrawColor</a>
+<li><a href="NSView.html#method-123">-sortSubviewsUsingFunction:context:</a>
+<li><a href="NSView.html#method-124">-subviews</a>
+<li><a href="NSView.html#method-125">-superview</a>
+<li><a href="NSView.html#method-126">-tag</a>
+<li><a href="NSView.html#method-127">-toolTip</a>
+<li><a href="NSView.html#method-128">-translateOriginToPoint:</a>
+<li><a href="NSView.html#method-129">-unlockFocus</a>
+<li><a href="NSView.html#method-130">-unregisterDraggedTypes</a>
+<li><a href="NSView.html#method-131">-viewWillMoveToSuperview:</a>
+<li><a href="NSView.html#method-132">-viewWillMoveToWindow:</a>
+<li><a href="NSView.html#method-133">-viewWithTag:</a>
+<li><a href="NSView.html#method-134">-visibleRect</a>
+<li><a href="NSView.html#method-135">-widthAdjustLimit</a>
+<li><a href="NSView.html#method-136">-window</a>
+<li><a href="NSView.html#method-137">-writeEPSInsideRect:toPasteboard:</a>
 </ul>
 <hr>
 <h2><a name="method-0">defaultMenu</a></h2>
@@ -605,244 +606,290 @@
 <h2><a name="method-88">removeFromSuperview</a></h2>
 - (void) <b>removeFromSuperview</b><br>
 
+	    
+	    
+          <p>
+
+	      Removes the receiver from its superviews list of subviews,
+	      by invoking the superviews [-removeSubview:] method, and
+	      marks the rectangle that the reciever occupied in the
+	      superview as needing redisplay.
+	    </p>
+
+	    
+          <p>
+
+	       This is dangerous to use during display, since it alters the
+	       rectangles needing display.
+	    </p>
+
           
 <hr>
 <h2><a name="method-89">removeFromSuperviewWithoutNeedingDisplay</a></h2>
 - (void) <b>removeFromSuperviewWithoutNeedingDisplay</b><br>
 
+	    
+          <p>
+
+	      Removes the receiver from its superviews list of subviews,
+	      by invoking the superviews [-removeSubview:] method.
+	    </p>
+
           
 <hr>
-<h2><a name="method-90">removeTrackingRect:</a></h2>
+<h2><a name="method-90">removeSubview:</a></h2>
+- (void) <b>removeSubview:</b> (NSView*)aView<br>
+Standards: NotMacOS-X NotOpenStep<br>
+
+	    
+	    
+          <p>
+
+	      Removes the view from the receivers list of subviews
+	      and from the responder chain.
+	    </p>
+
+	    
+          <p>
+
+              Also invokes [aView -viewWillMoveToWindow: nil] to handle
+	      removal of aView (and recursively, its children) from its
+	      window - performing tidyup by invalidating cursor rects etc.
+	    </p>
+
+          
+<hr>
+<h2><a name="method-91">removeTrackingRect:</a></h2>
 - (void) <b>removeTrackingRect:</b> (NSTrackingRectTag)aTag<br>
 
           
 <hr>
-<h2><a name="method-91">renewGState</a></h2>
+<h2><a name="method-92">renewGState</a></h2>
 - (void) <b>renewGState</b><br>
 
           
 <hr>
-<h2><a name="method-92">replaceSubview:</a></h2>
+<h2><a name="method-93">replaceSubview:</a></h2>
 - (void) <b>replaceSubview:</b> (NSView*)oldView<br>
 
           
 <hr>
-<h2><a name="method-93">resetCursorRects</a></h2>
+<h2><a name="method-94">resetCursorRects</a></h2>
 - (void) <b>resetCursorRects</b><br>
 
           
 <hr>
-<h2><a name="method-94">resizeSubviewsWithOldSize:</a></h2>
+<h2><a name="method-95">resizeSubviewsWithOldSize:</a></h2>
 - (void) <b>resizeSubviewsWithOldSize:</b> (NSSize)oldFrameSize<br>
 
           
 <hr>
-<h2><a name="method-95">resizeWithOldSuperviewSize:</a></h2>
+<h2><a name="method-96">resizeWithOldSuperviewSize:</a></h2>
 - (void) <b>resizeWithOldSuperviewSize:</b> (NSSize)oldFrameSize<br>
 
           
 <hr>
-<h2><a name="method-96">rotateByAngle:</a></h2>
+<h2><a name="method-97">rotateByAngle:</a></h2>
 - (void) <b>rotateByAngle:</b> (float)angle<br>
 
           
 <hr>
-<h2><a name="method-97">scaleUnitSquareToSize:</a></h2>
+<h2><a name="method-98">scaleUnitSquareToSize:</a></h2>
 - (void) <b>scaleUnitSquareToSize:</b> (NSSize)newUnitSize<br>
 
           
 <hr>
-<h2><a name="method-98">scrollClipView:</a></h2>
+<h2><a name="method-99">scrollClipView:</a></h2>
 - (void) <b>scrollClipView:</b> (NSClipView*)aClipView<br>
 
           
 <hr>
-<h2><a name="method-99">scrollPoint:</a></h2>
+<h2><a name="method-100">scrollPoint:</a></h2>
 - (void) <b>scrollPoint:</b> (NSPoint)aPoint<br>
 
           
 <hr>
-<h2><a name="method-100">scrollRect:</a></h2>
+<h2><a name="method-101">scrollRect:</a></h2>
 - (void) <b>scrollRect:</b> (NSRect)aRect<br>
 
           
 <hr>
-<h2><a name="method-101">scrollRectToVisible:</a></h2>
+<h2><a name="method-102">scrollRectToVisible:</a></h2>
 - (BOOL) <b>scrollRectToVisible:</b> (NSRect)aRect<br>
 
           
 <hr>
-<h2><a name="method-102">setAutoresizesSubviews:</a></h2>
+<h2><a name="method-103">setAutoresizesSubviews:</a></h2>
 - (void) <b>setAutoresizesSubviews:</b> (BOOL)flag<br>
 
           
 <hr>
-<h2><a name="method-103">setAutoresizingMask:</a></h2>
+<h2><a name="method-104">setAutoresizingMask:</a></h2>
 - (void) <b>setAutoresizingMask:</b> (unsigned int)mask<br>
 
           
 <hr>
-<h2><a name="method-104">setBounds:</a></h2>
+<h2><a name="method-105">setBounds:</a></h2>
 - (void) <b>setBounds:</b> (NSRect)boundsRect<br>
 
           
 <hr>
-<h2><a name="method-105">setBoundsOrigin:</a></h2>
+<h2><a name="method-106">setBoundsOrigin:</a></h2>
 - (void) <b>setBoundsOrigin:</b> (NSPoint)newOrigin<br>
 
           
 <hr>
-<h2><a name="method-106">setBoundsRotation:</a></h2>
+<h2><a name="method-107">setBoundsRotation:</a></h2>
 - (void) <b>setBoundsRotation:</b> (float)angle<br>
 
           
 <hr>
-<h2><a name="method-107">setBoundsSize:</a></h2>
+<h2><a name="method-108">setBoundsSize:</a></h2>
 - (void) <b>setBoundsSize:</b> (NSSize)newSize<br>
 
           
 <hr>
-<h2><a name="method-108">setFrame:</a></h2>
+<h2><a name="method-109">setFrame:</a></h2>
 - (void) <b>setFrame:</b> (NSRect)frameRect<br>
 
           
 <hr>
-<h2><a name="method-109">setFrameOrigin:</a></h2>
+<h2><a name="method-110">setFrameOrigin:</a></h2>
 - (void) <b>setFrameOrigin:</b> (NSPoint)newOrigin<br>
 
           
 <hr>
-<h2><a name="method-110">setFrameRotation:</a></h2>
+<h2><a name="method-111">setFrameRotation:</a></h2>
 - (void) <b>setFrameRotation:</b> (float)angle<br>
 
           
 <hr>
-<h2><a name="method-111">setFrameSize:</a></h2>
+<h2><a name="method-112">setFrameSize:</a></h2>
 - (void) <b>setFrameSize:</b> (NSSize)newSize<br>
 
           
 <hr>
-<h2><a name="method-112">setInterfaceStyle:</a></h2>
+<h2><a name="method-113">setInterfaceStyle:</a></h2>
 - (void) <b>setInterfaceStyle:</b> (NSInterfaceStyle)interfaceStyle<br>
 
           
 <hr>
-<h2><a name="method-113">setNeedsDisplay:</a></h2>
+<h2><a name="method-114">setNeedsDisplay:</a></h2>
 - (void) <b>setNeedsDisplay:</b> (BOOL)flag<br>
 
           
 <hr>
-<h2><a name="method-114">setNeedsDisplayInRect:</a></h2>
+<h2><a name="method-115">setNeedsDisplayInRect:</a></h2>
 - (void) <b>setNeedsDisplayInRect:</b> (NSRect)invalidRect<br>
 
           
 <hr>
-<h2><a name="method-115">setNextKeyView:</a></h2>
+<h2><a name="method-116">setNextKeyView:</a></h2>
 - (void) <b>setNextKeyView:</b> (NSView*)aView<br>
 
           
 <hr>
-<h2><a name="method-116">setPostsBoundsChangedNotifications:</a></h2>
+<h2><a name="method-117">setPostsBoundsChangedNotifications:</a></h2>
 - (void) <b>setPostsBoundsChangedNotifications:</b> (BOOL)flag<br>
 
           
 <hr>
-<h2><a name="method-117">setPostsFrameChangedNotifications:</a></h2>
+<h2><a name="method-118">setPostsFrameChangedNotifications:</a></h2>
 - (void) <b>setPostsFrameChangedNotifications:</b> (BOOL)flag<br>
 
           
 <hr>
-<h2><a name="method-118">setToolTip:</a></h2>
+<h2><a name="method-119">setToolTip:</a></h2>
 - (void) <b>setToolTip:</b> (NSString*)string<br>
 
           
 <hr>
-<h2><a name="method-119">setUpGState</a></h2>
+<h2><a name="method-120">setUpGState</a></h2>
 - (void) <b>setUpGState</b><br>
 
           
 <hr>
-<h2><a name="method-120">shouldDelayWindowOrderingForEvent:</a></h2>
+<h2><a name="method-121">shouldDelayWindowOrderingForEvent:</a></h2>
 - (BOOL) <b>shouldDelayWindowOrderingForEvent:</b> (NSEvent*)theEvent<br>
 
           
 <hr>
-<h2><a name="method-121">shouldDrawColor</a></h2>
+<h2><a name="method-122">shouldDrawColor</a></h2>
 - (BOOL) <b>shouldDrawColor</b><br>
 
           
 <hr>
-<h2><a name="method-122">sortSubviewsUsingFunction:context:</a></h2>
+<h2><a name="method-123">sortSubviewsUsingFunction:context:</a></h2>
 - (void) <b>sortSubviewsUsingFunction:</b> (int (*)(id,id,void*))compare <b>context:</b> (void*)context<br>
 
           
 <hr>
-<h2><a name="method-123">subviews</a></h2>
+<h2><a name="method-124">subviews</a></h2>
 - (NSArray*) <b>subviews</b><br>
 
           
 <hr>
-<h2><a name="method-124">superview</a></h2>
+<h2><a name="method-125">superview</a></h2>
 - (NSView*) <b>superview</b><br>
 
           
 <hr>
-<h2><a name="method-125">tag</a></h2>
+<h2><a name="method-126">tag</a></h2>
 - (int) <b>tag</b><br>
 
           
 <hr>
-<h2><a name="method-126">toolTip</a></h2>
+<h2><a name="method-127">toolTip</a></h2>
 - (NSString*) <b>toolTip</b><br>
 
           
 <hr>
-<h2><a name="method-127">translateOriginToPoint:</a></h2>
+<h2><a name="method-128">translateOriginToPoint:</a></h2>
 - (void) <b>translateOriginToPoint:</b> (NSPoint)newOrigin<br>
 
           
 <hr>
-<h2><a name="method-128">unlockFocus</a></h2>
+<h2><a name="method-129">unlockFocus</a></h2>
 - (void) <b>unlockFocus</b><br>
 
           
 <hr>
-<h2><a name="method-129">unregisterDraggedTypes</a></h2>
+<h2><a name="method-130">unregisterDraggedTypes</a></h2>
 - (void) <b>unregisterDraggedTypes</b><br>
 
           
 <hr>
-<h2><a name="method-130">viewWillMoveToSuperview:</a></h2>
+<h2><a name="method-131">viewWillMoveToSuperview:</a></h2>
 - (void) <b>viewWillMoveToSuperview:</b> (NSView*)newSuperview<br>
 
           
 <hr>
-<h2><a name="method-131">viewWillMoveToWindow:</a></h2>
+<h2><a name="method-132">viewWillMoveToWindow:</a></h2>
 - (void) <b>viewWillMoveToWindow:</b> (NSWindow*)newWindow<br>
 
           
 <hr>
-<h2><a name="method-132">viewWithTag:</a></h2>
+<h2><a name="method-133">viewWithTag:</a></h2>
 - (id) <b>viewWithTag:</b> (int)aTag<br>
 
           
 <hr>
-<h2><a name="method-133">visibleRect</a></h2>
+<h2><a name="method-134">visibleRect</a></h2>
 - (NSRect) <b>visibleRect</b><br>
 
           
 <hr>
-<h2><a name="method-134">widthAdjustLimit</a></h2>
+<h2><a name="method-135">widthAdjustLimit</a></h2>
 - (float) <b>widthAdjustLimit</b><br>
 
           
 <hr>
-<h2><a name="method-135">window</a></h2>
+<h2><a name="method-136">window</a></h2>
 - (NSWindow*) <b>window</b><br>
 
           
 <hr>
-<h2><a name="method-136">writeEPSInsideRect:toPasteboard:</a></h2>
+<h2><a name="method-137">writeEPSInsideRect:toPasteboard:</a></h2>
 - (void) <b>writeEPSInsideRect:</b> (NSRect)aRect <b>toPasteboard:</b> (NSPasteboard*)pboard<br>