--- a/docs/man3/SDL_CreateRGBSurface.3	Sun Jun 10 18:39:47 2001 +0000
+++ b/docs/man3/SDL_CreateRGBSurface.3	Sun Jun 10 19:31:57 2001 +0000
@@ -1,4 +1,4 @@
-.TH "SDL_CreateRGBSurface" "3" "Mon 12 Mar 2001, 01:04" "SDL" "SDL API Reference" 
+.TH "SDL_CreateRGBSurface" "3" "Sun 10 Jun 2001, 19:41" "SDL" "SDL API Reference" 
 .SH "NAME"
 SDL_CreateRGBSurface\- Create an empty SDL_Surface
 .SH "SYNOPSIS"
@@ -19,11 +19,51 @@
 SDL will attempt to create the surface in video memory\&. This will allow SDL to take advantage of Video->Video blits (which are often accelerated)\&.
 .TP 20
 \fBSDL_SRCCOLORKEY\fP
-With this flag SDL will attempt to find the best location for this surface, either in system memory or video memory, to obtain hardware colorkey blitting support\&.
+This flag turns on colourkeying for blits from this surface\&. If \fBSDL_HWSURFACE\fP is also specified and colourkeyed blits are hardware-accelerated, then SDL will attempt to place the surface in video memory\&. Use \fI\fBSDL_SetColorKey\fP\fR to set or clear this flag after surface creation\&.
 .TP 20
 \fBSDL_SRCALPHA\fP
-With this flag SDL will attempt to find the best location for this surface, either in system memory or video memory, to obtain hardware alpha support
+This flag turns on alpha-blending for blits from this surface\&. If \fBSDL_HWSURFACE\fP is also specified and alpha-blending blits are hardware-accelerated, then the surface will be placed in video memory if possible\&. Use \fI\fBSDL_SetAlpha\fP\fR to set or clear this flag after surface creation\&.
+.PP
+.RS
+\fBNote:  
+.PP
+If an alpha-channel is specified (that is, if \fBAmask\fR is nonzero), then the \fBSDL_SRCALPHA\fP flag is automatically set\&. You may remove this flag by calling \fI\fBSDL_SetAlpha\fP\fR after surface creation\&.
+.RE
+.SH "RETURN VALUE"
+.PP
+Returns the created surface, or \fBNULL\fR upon error\&.
+.SH "EXAMPLE"
+.PP
+.nf
+\f(CW    /* Create a 32-bit surface with the bytes of each pixel in R,G,B,A order,
+       as expected by OpenGL for textures */
+    SDL_Surface *surface;
+    Uint32 rmask, gmask, bmask, amask;
+
+    /* SDL interprets each pixel as a 32-bit number, so our masks must depend
+       on the endianness (byte order) of the machine */
+#if SDL_BYTEORDER == SDL_BIG_ENDIAN
+    rmask = 0xff000000;
+    gmask = 0x00ff0000;
+    bmask = 0x0000ff00;
+    amask = 0x000000ff;
+#else
+    rmask = 0x000000ff;
+    gmask = 0x0000ff00;
+    bmask = 0x00ff0000;
+    amask = 0xff000000;
+#endif
+
+    surface = SDL_CreateRGBSurface(SDL_SWSURFACE, width, height, 32,
+                                   rmask, gmask, bmask, amask);
+    if(surface == NULL) {
+        fprintf(stderr, "CreateRGBSurface failed: %s
+", SDL_GetError());
+        exit(1);
+    }\fR
+.fi
+.PP
 .SH "SEE ALSO"
 .PP
-\fI\fBSDL_CreateRGBSurfaceFrom\fP\fR, \fI\fBSDL_FreeSurface\fP\fR, \fI\fBSDL_SetVideoMode\fP\fR, \fI\fBSDL_LockSurface\fP\fR, \fI\fBSDL_PixelFormat\fR\fR, \fI\fBSDL_Surface\fR\fR
-...\" created by instant / docbook-to-man, Mon 12 Mar 2001, 01:04
+\fI\fBSDL_CreateRGBSurfaceFrom\fP\fR, \fI\fBSDL_FreeSurface\fP\fR, \fI\fBSDL_SetVideoMode\fP\fR, \fI\fBSDL_LockSurface\fP\fR, \fI\fBSDL_PixelFormat\fR\fR, \fI\fBSDL_Surface\fR\fR \fI\fBSDL_SetAlpha\fP\fR \fI\fBSDL_SetColorKey\fP\fR
+...\" created by instant / docbook-to-man, Sun 10 Jun 2001, 19:41