From 6676521c23ff5605caefa27250d5f646a05499df Mon Sep 17 00:00:00 2001
From: Rasmus Lerdorf <rasmus@php.net>
Date: Sat, 20 Jun 2009 18:07:12 +0000
Subject: [PATCH] Improve goto description and add a couple of examples. 
 Remove the warning because I think it is better to simply describe that
 restriction up front.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@282476 c90b9560-bf6c-de11-be94-00142212c4b1
---
 language/control-structures/goto.xml | 66 ++++++++++++++++++++++++----
 1 file changed, 58 insertions(+), 8 deletions(-)

diff --git a/language/control-structures/goto.xml b/language/control-structures/goto.xml
index 773a82dfe3..68f930ce53 100644
--- a/language/control-structures/goto.xml
+++ b/language/control-structures/goto.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
 
 <sect1 xml:id="control-structures.goto" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <title><literal>goto</literal></title>
@@ -7,7 +7,13 @@
   The <literal>goto</literal> operator can be used to jump to another
   section in the program.  The target point is specified by a label
   followed by a colon, and the instruction is given as
-  <literal>goto</literal> followed by the desired target label.
+  <literal>goto</literal> followed by the desired target label.  This
+  is not a full unrestricted <literal>goto</literal>.  The target
+  label must be within the same context, meaning that you cannot jump
+  out of a function or method, nor can you jump into one.  You also
+  cannot jump into any sort of loop or switch structure.  You may jump
+  out of these, and a common use is to use a <literal>goto</literal>
+  in place of a multi-level <literal>break</literal>.
  </para>
  <para>
   <example>
@@ -27,6 +33,56 @@ echo 'Bar';
    <screen>
 <![CDATA[
 Bar
+]]>
+   </screen>
+  </example>
+ </para>
+ <para>
+  <example>
+   <title><literal>goto</literal> loop example</title>
+   <programlisting role="php">
+<![CDATA[
+<?php
+for($i=0,$j=50; $i<100; $i++) {
+  while($j--) {
+    if($j==17) goto end; 
+  }  
+}
+echo "i = $i";
+end:
+echo 'j hit 17';
+?>
+]]>
+   </programlisting>
+   &example.outputs;
+   <screen>
+<![CDATA[
+j hit 17
+]]>
+   </screen>
+  </example>
+ </para>
+ <para>
+  <example>
+   <title>This will not work</title>
+   <programlisting role="php">
+<![CDATA[
+<?php
+goto loop;
+for($i=0,$j=50; $i<100; $i++) {
+  while($j--) {
+    loop:
+  }
+}
+echo "$i = $i";
+?>
+]]>
+   </programlisting>
+   &example.outputs;
+   <screen>
+<![CDATA[
+Fatal error: 'goto' into loop or switch statement is disallowed in
+script on line 2
 ]]>
    </screen>
   </example>
@@ -36,12 +92,6 @@ Bar
    The <literal>goto</literal> operator is available as of PHP 5.3.
   </para>
  </note>
- <warning>
-  <para>
-   It is not allowed to jump into a loop or switch statement. A fatal
-   error is issued in such cases.
-  </para>
- </warning>
  <para>
   <mediaobject>
    <imageobject>