--- a/doc/ChangeLog	Mon Apr 16 21:29:04 2007 +0000
+++ b/doc/ChangeLog	Mon Apr 16 23:16:58 2007 +0000
@@ -5,6 +5,11 @@
 
 2007-04-16  Søren Hauberg  <hauberg@gmail.com>
 
+	* intrepreter/stmt.txi: Improve documentation of switch statement.
+
+	* interpreter/tips.txi: Update description of how copyright
+	statements are recognized.
+
 	* interpreter/octave.texi: Don't include stream.texi.
 	Remove menu entry for I/O streams.
 

--- a/doc/interpreter/stmt.txi	Mon Apr 16 21:29:04 2007 +0000
+++ b/doc/interpreter/stmt.txi	Mon Apr 16 23:16:58 2007 +0000
@@ -200,13 +200,42 @@
 @cindex @code{otherwise} statement
 @cindex @code{endswitch} statement
 
-The @code{switch} statement was introduced in Octave 2.0.5.  It should
-be considered experimental, and details of the implementation may change
-slightly in future versions of Octave.  If you have comments or would
-like to share your experiences in trying to use this new command in real
-programs, please send them to @email{maintainers@@octave.org}.  (But if
-you think you've found a bug, please report it to
-@email{bug@@octave.org}.
+It is very common to take different actions depending on the value of
+one variable. This is possible using the @code{if} statement in the
+following way
+
+@example
+if (X == 1)
+  do_something ();
+elseif (X == 2)
+  do_something_else ();
+else
+  do_something_completely_different ();
+endif
+@end example
+
+@noindent
+This kind of code can however be very cumbersome to both write and
+maintain. To overcome this problem Octave supports the @code{switch}
+statement. Using this statement, the above example becomes
+
+@example
+switch (X)
+  case 1
+    do_something ();
+  case 2
+    do_something_else ();
+  otherwise
+    do_something_completely_different ();
+endswitch
+@end example
+
+@noindent
+This code makes the repetitive structure of the problem more explicit,
+making the code easier to read, and hence maintain. Also, if the
+variable @code{X} should change it's name, only one line would need
+changing compared to one line per case when @code{if} statements are
+used.
 
 The general form of the @code{switch} statement is
 
@@ -225,30 +254,50 @@
 @end group
 @end example
 
-@itemize @bullet
-@item
-The identifiers @code{switch}, @code{case}, @code{otherwise}, and
-@code{endswitch} are now keywords. 
-
-@item
-The @var{label} may be any expression.
+@noindent
+where @var{label} can be any expression. However, duplicate
+@var{label} values are not detected, and only the @var{command_list}
+corresponding to the first match will be executed. For the
+@code{switch} statement to be meaningful at least one
+@code{case @var{label} @var{command_list}} clause must be present,
+while the @code{otherwise @var{command_list}} clause is optional.
 
-@item
-Duplicate @var{label} values are not detected.  The @var{command_list}
-corresponding to the first match will be executed.
-
-@item
-You must have at least one @code{case @var{label} @var{command_list}}
-clause.
-
-@item
-The @code{otherwise @var{command_list}} clause is optional.
-
-@item
 As with all other specific @code{end} keywords, @code{endswitch} may be
 replaced by @code{end}, but you can get better diagnostics if you use
 the specific forms.
 
+@c Strings can be matched
+
+One advantage of using the @code{switch} statement compared to using
+@code{if} statements is that the @var{label}s can be strings. If an
+@code{if} statement is used it is @emph{not} possible to write
+
+@example
+if (X == "a string") # This is NOT valid
+@end example
+
+@noindent
+since a character-to-character comparison between @code{X} and the
+string will be made instead of evaluating if the strings are equal.
+This special-case is handled by the @code{switch} statement, and it
+is possible to write programs that look like this
+
+@example
+switch (X)
+  case "a string"
+    do_something
+  @dots{}
+endswitch
+@end example
+
+@node Notes for the C programmer
+@subsection Notes for the C programmer
+
+The @code{switch} statement is also used in the widely used C
+programming language. There are, however, some differences
+between the statement in Octave and C
+
+@itemize @bullet
 @item
 Cases are exclusive, so they don't `fall through' as do the cases
 in the switch statement of the C language.
@@ -281,13 +330,6 @@
 
 @noindent
 particularly for C programmers.
-
-@item
-The implementation is simple-minded and currently offers no real
-performance improvement over an equivalent @code{if} block, even if all
-the labels are integer constants.  Perhaps a future variation on this
-could detect all constant integer labels and improve performance by
-using a jump table.
 @end itemize
 
 @node The while Statement

--- a/doc/interpreter/tips.txi	Mon Apr 16 21:29:04 2007 +0000
+++ b/doc/interpreter/tips.txi	Mon Apr 16 23:16:58 2007 +0000
@@ -283,22 +283,8 @@
 Octave uses the first block of comments in a function file that do not
 appear to be a copyright notice as the help text for the file.  For
 Octave to recognize the first comment block as a copyright notice, it
-must match the regular expression
-
-@example
-^ Copyright (C).*\n\n This file is part of Octave.
-@end example
-
-@noindent
-or
-
-@example
-^ Copyright (C).*\n\n This program is free softwar
-@end example
-
-@noindent
-(after stripping the leading comment characters).  This is a fairly
-strict requirement, and may be relaxed somewhat in the future.
+must start with the word `Copyright' after stripping the leading
+comment characters.
 
 After the copyright notice and help text come several @dfn{header
 comment} lines, each beginning with @samp{## @var{header-name}:}.  For