[Asterisk-doc] docs extensions.xml,1.7,1.8

[websmith]

Comments:
Update of /cvsroot/asterisk/docs
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv20173

Modified Files:
	extensions.xml 
Log Message:
I've added a bunch of notes in square brackets to this chapter, in hopes that someone will come along later and read the notes and understand what I intended to put there.  (For me, it's often easier to sort of "map out" the sections, and then come back and fill them in later.)
Index: extensions.xml
===================================================================
RCS file: /cvsroot/asterisk/docs/extensions.xml,v
retrieving revision 1.7
retrieving revision 1.8
diff -C2 -d -r1.7 -r1.8
*** extensions.xml	19 May 2004 05:41:27 -0000	1.7
--- extensions.xml	19 May 2004 06:08:49 -0000	1.8
***************
*** 34,41 ****
--- 34,45 ----
  			All of the instructions placed after a context definition are considered part of that context, until another context is defined.
  			</para>
+ 			<para>
+ 			[Let's not forget to explain the "global" context, either here or later on.]
+ 			</para>
  		</sect2>
  		<sect2>
  			<title>Extensions</title>
  			<para>
+ 			[C'mon... we've got to change this.  Odds are that the reader won't have any idea what a "subroutine" is, and I'd be willing to be they have no idea what "old BASIC programming" is like.  Can't we explain this in plain english, and not programmer-speak?] 
  			The extension definitions are very much like subroutines in
  			programming. You will define them as the steps a call will take as
***************
*** 51,84 ****
  		<sect2>
  			<title>Priorities</title>
! 			<para/>
  		</sect2>
  	</sect1>
  	<sect1>
  		<title>A simple example</title>
! 		<para/>
! 		<sect2>
! 			<title>A simple 1FXOx1FXS setup</title>
! 			<para/>
! 		</sect2>
  		<sect2>
  			<title>The special 's' extension</title>
! 			<para/>
  		</sect2>
  		<sect2>
! 			<title>The <function>Playback()</function> and <function>Dial()</function> functions</title>
! 			<para/>
  		</sect2>
  		<sect2>
! 			<title>Handling Incoming Calls</title>
  			<informalexample>
  			<programlisting>
  			[incoming]
  			exten=&gt;s,1,Answer()<lineannotation> ; Answer the line</lineannotation>
! 			exten=&gt;s,2,Playback(welcome)<lineannotation> ; Play back the 'welcome' sound file</lineannotation>
! 			exten=&gt;s,3,Dial(Zap/2)<lineannotation> ; Dial the receptionist at channel Zap/2</lineannotation>
  			</programlisting>
  			</informalexample>	
  		</sect2>
  	</sect1>
  	<sect1>
  		<title>Adding Additional Functionality</title>
--- 55,107 ----
  		<sect2>
  			<title>Priorities</title>
! 			<para>
! 			[Priorities show which order functions are applied to a specified
!          extension.  Priority <emphasis>1</emphasis> is executed before
!          priority <emphasis>2</emphasis>, and so on.  Each priority calls a function with certain arguments.  (We'll probably have to explain functions and arguments.)]
! 			</para>
  		</sect2>
  	</sect1>
  	<sect1>
  		<title>A simple example</title>
! 		<para>
! 		Let's create our first <filename>extensions.conf file</filename>.  Because this is our first step, we'll start with a very simple example.  We'll assume for this example that all Asterisk needs to do is to answer the phone, say "Goodbye", and then hangup.  We'll use this simple example to point out the fundamentals of creating a dialplan.
! 		</para>
  		<sect2>
  			<title>The special 's' extension</title>
! 			<para>
! 			[Before we get too far into our example, we should explain the 's' extension.  Explain that when calls are answered, they almost always do to the 's' extension in the context specified by zapata.conf/sip.conf/etc.]
! 			</para>
  		</sect2>
  		<sect2>
! 			<title>The <function>Answer()</function>, <function>Playback()</function>, and <function>Hangup</function> functions</title>
! 			<para>
! 			[A brief explanation of the Answer() function.  Explain that although you don't always need to call Answer(), it's a good habit to get into.  (Playback() and a few other functions answer the call automatically if it hasn't already been answered.)]
! 			</para>
! 			<para>
! 			[A brief explanation of the Playback() function.  Explain where it looks for files (maybe we should gloss over the language-specific part for now, but let's not forget to put it in somewhere.)]
! 			</para>
! 			<para>
! 			[A very brief explanation of the Hangup() function.  This one should be really simple. :-) ]
! 			</para>
  		</sect2>
  		<sect2>
! 			<title>Our First Dialplan</title>
! 			<para>
! 			[We should probably explain that this example won't work without the other configuration files setup correctly to send the incoming call into the "incoming" context.  Again, this isn't meant to be a complete example that people can actually use -- it is meant to explain how things in extensions.conf work.[
! 			</para>
  			<informalexample>
  			<programlisting>
  			[incoming]
  			exten=&gt;s,1,Answer()<lineannotation> ; Answer the line</lineannotation>
! 			exten=&gt;s,2,Playback('vm-goodbye')<lineannotation> ; Play back the 'goodbye' sound file</lineannotation>
! 			exten=&gt;s,3,Hangup()<lineannotation> ; Now hangup the line</lineannotation>
  			</programlisting>
  			</informalexample>	
+ 			<para>
+ 			[This is where we will go through and explain each line in our silly little example above.  Again, let's err on the side of making this as self-evident as possible, so readers get a good solid foundation in contexts, extensions, and priorities.]
+ 			</para>
  		</sect2>
  	</sect1>
+ 
  	<sect1>
  		<title>Adding Additional Functionality</title>