Starters section of EXTENDING documentation updated ("New" vs "Open",

other clean-up, and now directs people to README for determining image sizes.)

docs/CHANGES.txt

@@ -9,7 +9,7 @@ http://www.tuxpaint.org/
 $Id$
 
 
-2008.March.17 (0.9.20)
+2008.March.24 (0.9.20)
   * Localization Updates:
     ---------------------
     * German translation
@@ -46,6 +46,10 @@ $Id$
     * Mentioned that canvas size can be changed in README (so it's not
       just hidden in OPTIONS).
 
+    * Starters section of EXTENDING documentation updated ("New" vs "Open",
+      other clean-up, and now directs people to README for determining
+      image sizes.)
+
   * Bug Fixes
     ---------
     * Legacy Tux Paint images (prior to Tux Paint supporting different

docs/EXTENDING.txt

@@ -8,7 +8,7 @@
                            bill@newbreedsoftware.com
                             http://www.tuxpaint.org/
 
-                       June 14, 2002 - February 28, 2008
+                         June 14, 2002 - March 27, 2008
 
    --------------------------------------------------------------------------
 
@@ -467,14 +467,14 @@ Fonts
 
 'Starters'
 
-     'Starter' images appear in the 'Open' dialog, along with pictures you've
+     'Starter' images appear in the 'New' dialog, along with solid color
-     created. They have a green button background, instead of blue.
+     background choices. (Note: In earlier versions of Tux Paint, they
+     appeared in the 'Open' dialog, together with saved drawings.)
 
-     Unlike your saved pictures, however, when you select and open a
+     Unlike pictures drawn in Tux Paint by users and then opened later,
-     'starter,' you're actually creating a new drawing. Instead of being
+     opening a 'starter' creates a new drawing. When you save, the 'starter'
-     blank, though, the new drawing contains the contents of the 'starter.'
+     image is not overwritten. Additionally, as you edit your new picture,
-     Additionally, as you edit your new picture, the contents of the original
+     the contents of the original 'starter' affect it.
-     'starter' affect it.
 
      Coloring-Book Style
 
@@ -489,6 +489,11 @@ Fonts
        (that will come out as white in Tux Paint), and save it as a PNG
        format file.
 
+       Note: A common mistake is to make the image black and white, rather
+       than black and transparent. Unless there are transparent zones in the
+       'starter' image, all drawing done by the user in Tux Paint will be
+       covered up by the 'starter'.
+
      Scene-Style
 
        Along with the 'coloring-book' style overlay, you can also provide a
@@ -497,8 +502,9 @@ Fonts
        tools. However, the background can be!
 
        When the 'Eraser' tool is used on a picture based on this kind of
-       'starter' image, rather than turning the canvas white, it returns that
+       'starter' image, rather than turning the canvas to a solid color, such
-       part of the canvas to the original background picture.
+       as white, it returns that part of the canvas to the original
+       background picture from the 'starter'.
 
        By creating both an overlay and a background, you can create a
        'starter' which simulates depth. Imagine a background that shows the
@@ -507,20 +513,21 @@ Fonts
        'in front of' the reef.
 
        To create this kind of 'starter' picture, simply create an overlay
-       (with alpha transparency) as described above, and save it as a PNG.
+       (with transparency) as described above, and save it as a PNG. Then
-       Then create another image (without transparency), and save it with the
+       create another image (without transparency), and save it with the same
-       same filename, but with "-back" appended to the name. (e.g.,
+       filename, but with "-back" appended to the name. (e.g.,
        "reef-back.png" would be the background ocean picture that corresponds
        to the "reef.png" overlay, or foreground.)
 
-     The 'starter' images should be the same size as Tux Paint's canvas. In
+     The 'starter' images should be the same size as Tux Paint's canvas. (See
-     the default 640x480 mode, that is 448x376 pixels. If you're using
+     the "Loading Other Pictures into Tux Paint" section of README for
-     800x600 mode, it should be 608x496. (It should be 192 pixels less wide,
+     details on sizing.) If they are not, they will be stretched, without
-     and 104 pixels less tall than the resolution.)
+     affecting the shape ("aspect ratio"); however some smudging may be
+     applied to the edges.
 
-     Place them in the "starters" directory. When the 'Open' dialog is
+     Place them in the "starters" directory. When the 'New' dialog is
-     accessed in Tux Paint, the 'starter' images will appear at the beginning
+     accessed in Tux Paint, the 'starter' images will appear in the screen
-     of the list with a green background.
+     that appears, after the various solid color choices.
 
      Note: 'Starters' can't be saved over from within Tux Paint, since
      loading a 'starter' is really like creating a new image. (Instead of
@@ -535,6 +542,8 @@ Fonts
      picture loaded or started. (In other words, if you base a drawing on a
      'starter' image, it will always be affected by it.)
 
+   --------------------------------------------------------------------------
+
 Translations
 
      Tux Paint supports numerous languages, thanks to use of the "gettext"

docs/html/EXTENDING.html

@@ -23,7 +23,7 @@ New Breed Software</p>
 <p><a href="mailto:bill@newbreedsoftware.com">bill@newbreedsoftware.com</a><br>
 <a href="http://www.tuxpaint.org/">http://www.tuxpaint.org/</a></p>
 
-<p>June 14, 2002 - February 28, 2008</p>
+<p>June 14, 2002 - March 27, 2008</p>
 </center>
 
 <hr size=2 noshade>
@@ -613,14 +613,14 @@ effect.</p>
 <blockquote>
   <img src="images/open_open.png" width=48 height=48 alt="" align=right>
 
-  <p>'Starter' images appear in the 'Open' dialog, along with pictures
+  <p>'Starter' images appear in the 'New' dialog, along with solid
-  you've created.  They have a green button background, instead of blue.</p>
+  color background choices. (Note: In earlier versions of Tux&nbsp;Paint,
+  they appeared in the 'Open' dialog, together with saved drawings.)</p>
   
-  <p>Unlike your saved pictures, however, when you select and open a
+  <p>Unlike pictures drawn in Tux&nbsp;Paint by users and then opened
-  'starter,' you're actually creating a new drawing.  Instead of being
+  later, opening a 'starter' creates a new drawing.  When you save, the
-  blank, though, the new drawing contains the contents of the 'starter.'
+  'starter' image is not overwritten.  Additionally, as you edit your new
-  Additionally, as you edit your new picture, the contents of the
+  picture, the contents of the original 'starter' affect it.</p>
-  original 'starter' affect it.</p>
 
   <b>Coloring-Book Style</b>
   
@@ -635,6 +635,11 @@ effect.</p>
     picture in a paint program, make the rest of the graphic transparent
     (that will come out as white in Tux&nbsp;Paint), and save it as a
     PNG format file.</p>
+
+    <p><b>Note:</b> A common mistake is to make the image black and white,
+    rather than black and transparent.  Unless there are transparent zones
+    in the 'starter' image, <i>all</i> drawing done by the user in
+    Tux&nbsp;Paint will be covered up by the 'starter'.</p>
   </blockquote>
 
   <b>Scene-Style</b>
@@ -646,8 +651,9 @@ effect.</p>
     'Magic' tools.  However, the background can be!</p>
 
     <p>When the 'Eraser' tool is used on a picture based on this kind of
-    'starter' image, rather than turning the canvas white, it returns that
+    'starter' image, rather than turning the canvas to a solid color,
-    part of the canvas to the original background picture.</p>
+    such as white, it returns that part of the canvas to the original
+    background picture from the 'starter'.</p>
 
     <p>By creating both an overlay and a background, you can create a
     'starter' which simulates depth.  Imagine a background that shows
@@ -656,7 +662,7 @@ effect.</p>
     but never 'in front of' the reef.</p>
 
     <p>To create this kind of 'starter' picture, simply create an overlay
-    (with alpha transparency) as described above, and save it as a PNG.
+    (with transparency) as described above, and save it as a PNG.
     Then create another image (without transparency), and save it with
     the same filename, but with "<code>-back</code>" appended to the
     name.  (e.g., "<code>reef-back.png</code>" would be the background
@@ -665,13 +671,15 @@ effect.</p>
   </blockquote>
   
   <p>The 'starter' images should be the same size as Tux&nbsp;Paint's
-  canvas.  In the default 640x480 mode, that is 448x376 pixels.
+  canvas.  (See the "Loading Other Pictures into Tux&nbsp;Paint" section of
-  If you're using 800x600 mode, it should be 608x496.  (It should be
+  <a href="README.html">README</a> for details on sizing.)  If they are not,
-  192 pixels less wide, and 104 pixels less tall than the resolution.)</p>
+  they will be stretched, without affecting the shape ("aspect ratio");
+  however some smudging may be applied to the edges.</p>
   
   <p>Place them in the "<code><b>starters</b></code>" directory.
-  When the 'Open' dialog is accessed in Tux&nbsp;Paint, the 'starter'
+  When the 'New' dialog is accessed in Tux&nbsp;Paint, the 'starter'
-  images will appear at the beginning of the list with a green background.</p>
+  images will appear in the screen that appears, after the various solid color
+  choices.</p>
   
   <p><b>Note:</b> 'Starters' can't be saved over from within Tux&nbsp;Paint,
   since loading a 'starter' is really like creating a new image.
@@ -690,6 +698,9 @@ effect.</p>
   <br clear=all>
 </blockquote>
 
+<hr size=1 noshade>
+
+
 <h2>Translations</h2>
 <blockquote>
   <p>Tux Paint supports numerous languages, thanks to use of the