Author: derek Date: Wed Jul 4 22:06:07 2007 New Revision: 349 Removed: sofaswitch/trunk/callflow/docs/current/eachicon.dxy sofaswitch/trunk/callflow/docs/overview.dxy Modified: sofaswitch/trunk/callflow/docs/callflow.xml sofaswitch/trunk/callflow/docs/chap1.sgml sofaswitch/trunk/callflow/src/callflow.cpp Log: Move more code into the docbook format. Add link to the generated html code from doxygen. Modified: sofaswitch/trunk/callflow/docs/callflow.xml ============================================================================== --- sofaswitch/trunk/callflow/docs/callflow.xml (original) +++ sofaswitch/trunk/callflow/docs/callflow.xml Wed Jul 4 22:06:07 2007 @@ -9,6 +9,7 @@ <!ENTITY chap1 SYSTEM "chap1.sgml"> <!ENTITY chap2 SYSTEM "chap2.sgml"> <!ENTITY chap3 SYSTEM "chap3.sgml"> +<!ENTITY code SYSTEM "code.sgml"> <!ENTITY app1 SYSTEM "app1.sgml"> @@ -51,6 +52,7 @@ &chap3; +&code; &app1; </book> Modified: sofaswitch/trunk/callflow/docs/chap1.sgml ============================================================================== --- sofaswitch/trunk/callflow/docs/chap1.sgml (original) +++ sofaswitch/trunk/callflow/docs/chap1.sgml Wed Jul 4 22:06:07 2007 @@ -1,10 +1,80 @@ <chapter> <title>Introduction</title> + +<para> +This is an Open Source application specifically designed to ease the +development of call control in the &sofaswitch; suite of applications. +</para> + + +<para> +The code is based on <ulink url="http://www.wxwidgets.org">wxWidgets</ulink> (for portability), in C++ (for +functionality and ease of integrating with wxWidgets) and has been released +under the MPL license. +</para> + + +<sect1> +<title> Why do we need &callflow;?</title> +<para> +My (DJS) initial thoughts on the design of &sofaswitch; was that there would +be individual entities (server, voip, am etc) all controlled by a custom +script, written in some scripting language. I wrote the entities first, and +then wrote simple python scripts to test the entities. +</para> + +<para> +The python scripts started to grow quite large. Along the way, I altered the +control protocol, as I realised that there were some aspects missing from the +original design. This had the unfortunate outcome of making those scripts +invalid. A second lesson was learnt - python is not very good on +threads. Things like the global interpreter lock started to get in the +way. Further, the scripts became a maintainence nightmare. This was +discouraging. +</para> + +<para> +At this stage, I was uncertain. Should I change to a different (and more +superior) scripting language? Some thought and discussion showed that python +is the way to go. Choosing an unknown (but superior?) language like XYZ would +indeed solve the above problems, but introduce two new problems: 1)it is now +much harder to get get going in the project and 2)it becomes much harder to +install &sofaswitch;. Minor considerations such as, "we might loose +cross-platform features if we switch to XYZ" were part of the problem space. +</para> + + +<para> +Worse still, by demanding the scripting language is written in Python (or +Perl, or Lua, or C, etc) I was raising the bar for the system administrator +before he/she could use &sofaswitch;. They were now reqired to learn the +scripting language and how &sofaswitch; works. Everyone understands flowcharts - +if only there was a scripting language based on flowcharts. +</para> + +<para> +Clearly, the way ahead was to write a custom utility to write the python +control scripts. Now, we expect that some may wish to write their own python +scripts. This is fine - you are welcome to learn from our current +codebase. Given the modular structure of &sofaswitch;, this is +inevitable. Different modules will be glued together in different ways. +</para> + +<para> +Thus, the design of &callflow; is such that you can create scripts to do very +complex things with the minimum of effort. +</para> +</sect1> + + +<sect1> +<title>&callflow; - synopsis</title> <para>&callflow; is a utility which has been designed to enable the user to control the various entities in the &sofaswitch; system. This utility allows the user to graphically design call setup, connection, and teardown. This utility takes the graphical layout and generates Python code, which implements the -desired operation. </para> +desired operation. +</para> <para>Python is areasonably tidy language, cross platform, straightforward syntax and does not have the dependency hell of perl. Sadly, nothing is easy, and it takes @@ -12,18 +82,16 @@ graphical approach is preferable. </para> -<para> -The user will be exposed to some Python, but at a relatively simple +<para>The user will be exposed to some Python, but at a relatively simple level. These blocks of Python code are regular expressions and label defination. Consequently, it is straightforward, and quite manageable for the novice. The example flow graphs contain many blocks of Python code, which are -a useful guide to the novice. -</para> +a useful guide to the novice.</para> <para>The following section gives an overview of the operation of &callflow;. Subsequent chapters describe the operation of &callflow; by means -of examples, and by a detailed description of each available control structure. -</para> +of examples, and by a detailed description of each available control structure.</para> +</sect1> <sect1> <title>Overview of operation</title> <para>Various items are selected from the tool bar, and placed on the screen. These are connected @@ -84,11 +152,12 @@ thread running in Python is a whole new running interpreter, which consumes system resources. This posed a problem - if the controller is going to handle lots of concurrent calls, it would be poor practice to place each controller -handled call into a separate Python thread. </para> +handled call into a separate Python thread.</para> -<para> We therefore base this code around -<ulink url="http://twistedmatrix.com/trac">Twisted</ulink>, an event driven -network framework written in Python. Using <ulink +<para> +We therefore base this code around <ulink +url="http://twistedmatrix.com/trac">Twisted</ulink>, an event driven network +framework written in Python. Using <ulink url="http://twistedmatrix.com/trac">Twisted</ulink> solved the handling of the any number of asynchronous events.. From a users point of view, we have one thread per call and graph management is simplified. The reality is that there @@ -101,7 +170,6 @@ the end of the current graph. Execution then waits for a event to happen, which move the current point of execution back to the relevant event handler. Thus, a call flow graph in this system will only have one start point, but may -have many termination points. -</para> +have many termination points.</para> </sect1> </chapter> Modified: sofaswitch/trunk/callflow/src/callflow.cpp ============================================================================== --- sofaswitch/trunk/callflow/src/callflow.cpp (original) +++ sofaswitch/trunk/callflow/src/callflow.cpp Wed Jul 4 22:06:07 2007 @@ -594,7 +594,9 @@ callflowHelpWindow->Create(core, wxID_ANY, wxDefaultPosition, GetClientSize(), wxTAB_TRAVERSAL|wxNO_BORDER, wxHF_DEFAULT_STYLE); - callflowHtmlHelp.AddBook(wxFileName(_T("doc.zip"))); + callflowHtmlHelp.AddBook(wxFileName(_T("callflow.zip"))); + callflowHtmlHelp.AddBook(wxFileName(_T("overview.zip"))); + callflowHtmlHelp.AddBook(wxFileName(_T("get_started.zip"))); callflowHtmlHelp.Display(_T("Introduction")); #else //Respond to menu here