Re #1742 (misc): Updated latest pjsip-book and added make install target to install the book to WWWDIR

git-svn-id: http://svn.pjsip.org/repos/pjproject/trunk@4772 74dad513-b988-da41-8d7b-12977e46ad98

4 files changed, 36 insertions, 26 deletions

diff --git a/doc/pjsip-book/Makefile b/doc/pjsip-book/Makefile
index 9f5bc222..696410e2 100644
--- a/doc/pjsip-book/Makefile
+++ b/doc/pjsip-book/Makefile
@@ -45,6 +45,16 @@ clean:
 	-rm -rf xml
 	-rm -rf html
 
+install:
+	@if test -z "$(WWWDIR)" ; then \
+	  echo WWWDIR is not set; \
+	else \
+	  echo Copying html dir to $(WWWDIR)/docs/book-latest/..; \
+	  cp -a -f _build/html $(WWWDIR)/docs/book-latest/; \
+	  echo Copying PJSUA2Doc.pdf to $(WWWDIR)/docs/book-latest/..; \
+	  cp -f _build/latex/PJSUA2Doc.pdf $(WWWDIR)/docs/book-latest/; \
+	fi
+
 xml:	Doxyfile ../../pjsip/include/pjsua2
 	doxygen
 
diff --git a/doc/pjsip-book/consider.rst b/doc/pjsip-book/consider.rst
index 70c10ce4..9533503b 100644
--- a/doc/pjsip-book/consider.rst
+++ b/doc/pjsip-book/consider.rst
@@ -1,5 +1,4 @@
 
-
 Development Guidelines and Considerations
 *****************************************
 
@@ -15,8 +14,9 @@ Preparation
 
 Development
 -------------
+* **Essential:** Follow the `Getting Started <http://trac.pjsip.org/repos/wiki/Getting-Started>`_ instructions to build PJSIP for your platform.
 * **Essential:** Interactive debugging capability is essential during development
-* Start with default settings in `<pj/config_site_sample.h>`.
+* Start with default settings in `<pj/config_site_sample.h>`. The default settings should be good to get you started. You can always optimize later after things are running okay.
 
 Coding Style
 -------------
@@ -72,7 +72,7 @@ Android
 -------
 All features except video are expected to work (video is coming soon!). Considerations for Android:
 
-#. You can only use pjsua2 Java binding for this target.
+#. You can only use PJSUA2 Java binding for this target.
 #. It has been reported that Android audio device is not so good in general, so some audio tuning may be needed. Echo cancellation also needs to be checked.
 #. This is also a new platform for us. 
 
@@ -103,7 +103,7 @@ Other considerations for Windows Mobile platform are:
 
 Windows Phone 8
 ---------------
-Windows Phone 8 (WP8) support is being added to PJSIP version 2.2 and is still under development. Specific considerations for this platform are:
+Windows Phone 8 (WP8) support is being added and is still under development on `projects/winphone` branch. Specific considerations for this platform are:
 
 #. WP8 governs specific interaction with WP8 GUI and framework that needs to be followed by application in order to make VoIP call work seamlessly on the device. Some lightweight process will be created by WP8 framework in order for background call to work and PJSIP needs to put its background processing in this process' context. Currently this feature is under development.
 
@@ -155,7 +155,7 @@ Motivations for using PJSUA-LIB library includes:
 #. Better efficiency than higher level API
 
 
-pjsua2 C++ API
+PJSUA2 C++ API
 --------------
 pjsua2 is a new, objected oriented, C++ API created on top of PJSUA-LIB. The API is different than PJSUA-LIB, but it should be even easier to use and it should have better documentation too (such as this book). The pjsua2 API removes most cruxes typically associated with PJSIP, such as the pool and pj_str_t, and add new features such as object persistence so you can save your configs to a file, for example. All data structures are rewritten for more clarity. 
 
@@ -169,16 +169,17 @@ Benefits of using pjsua2 C++ API include:
 #. The ability to access PJSUA-LIB and lower level libraries when needed (including the ability to extend the libraries, for example creating custom PJSIP module, pjmedia_port, pjmedia_transport, etc.)
 
 
-Some considerations on pjsua2 C++ API are:
+Some considerations on PJSUA2 C++ API are:
+
 #. Instead of returning error, the API uses exception for error reporting
-#. pjsua2 uses standard C++ library
+#. It uses standard C++ library (STL)
 #. The performance penalty due to the API abstraction should be negligible on typical modern device
 
 
 
-pjsua2 API for Java, Python, and Others
+PJSUA2 API for Java, Python, and Others
 ---------------------------------------
-The pjsua2 API is also available for non-native code via SWIG binding. Configurations for Java and Python are provided with the distribution. Thanks to SWIG, other language bindings may be generated relatively easily.
+The PJSUA2 API is also available for non-native code via SWIG binding. Configurations for Java and Python are provided with the distribution. Thanks to SWIG, other language bindings may be generated relatively easily.
  
 The pjsua2 API for non-native code is effectively the same as pjsua2 C++ API. However, unlike C++, you cannot access PJSUA-LIB and the underlying C libraries from the scripting language, hence you are limited to what pjsua2 provides.
 
@@ -192,7 +193,7 @@ Network and Infrastructure Considerations
 
 NAT Issues
 ----------
-
+TBD.
 
 TCP Requirement
 ---------------
@@ -204,11 +205,11 @@ Sound Device
 
 Latency
 -------
-
+TBD.
 
 Echo Cancellation
 -----------------
-
+TBD.
 
 
 
diff --git a/doc/pjsip-book/intro.rst b/doc/pjsip-book/intro.rst
index c421fc98..b76ea841 100644
--- a/doc/pjsip-book/intro.rst
+++ b/doc/pjsip-book/intro.rst
@@ -3,29 +3,24 @@ Introduction
 *******************************
 This documentation is intended for developers looking to develop Session Initiation Protocol (SIP) based client application. Some knowledge on SIP is definitely required, and of course some programming experience. Prior knowledge of PJSUA C API is not needed, although it will probably help.
 
-PJSIP libraries provide multi-level APIs to do SIP calls, presence, and instant messaging, as well as handling media and NAT traversal. Knowledge of SIP protocol details (such as the grammar, transaction, dialog, and whatnot) are not required (but it will help a lot!), however you should know how SIP works in general and particularly how to configure SIP clients to, e.g. register to a SIP provider, specify SIP URI to make call to, and so on, to use the module.
+PJSIP libraries provide multi-level APIs to do SIP calls, presence, and instant messaging, as well as handling media and NAT traversal. PJSUA2 API is the highest API from PJSIP, on top of PJSUA-LIB API. PJSUA-LIB API itself is a library that unifies SIP, audio/video media, NAT traversal, and client media application best practices into a high level, integrated, and easy to use API. The next chapter will guide you on selecting which API level to use depending on your requirements.
+
+This documentation can be `viewed online <http://www.pjsip.org/docs/book-latest/html/index.html>`_, or alternatively you can `download the PDF format <http://www.pjsip.org/docs/book-latest/PJSUA2Doc.pdf>`_ for offline viewing.
 
 Getting Started with PJSIP
 ==============================
-Check `PJSIP's Features List`_ to make sure that it has the features that you require.
-
-.. _`PJSIP's Features List`: http://trac.pjsip.org/repos/wiki/PJSIP-Datasheet
+Check `PJSIP Datasheet <http://trac.pjsip.org/repos/wiki/PJSIP-Datasheet>`_ to make sure that it has the features that you require.
 
-To start using PJSIP, the `Getting Started Guide`_ contains instructions to acquire and build PJSIP on various platforms that we support.
+To start using PJSIP, the `Getting Started Guide <http://trac.pjsip.org/repos/wiki/Getting-Started>`_ contains instructions to acquire and build PJSIP on various platforms that we support.
 
-.. _`Getting Started Guide`: http://trac.pjsip.org/repos/wiki/Getting-Started 
 
 PJSIP Info and Documentation
 ================================
 To get other relevant info and documentations about PJSIP, you can visit:
 
-- `PJSIP General Wiki`_
-- `PJSIP FAQ`_
-- `PJSIP Reference Manual`_ - please see Reference Manual section
-
-.. _`PJSIP General Wiki`: http://trac.pjsip.org/repos/wiki
-.. _`PJSIP FAQ`: http://trac.pjsip.org/repos/wiki/FAQ
-.. _`PJSIP Reference Manual`: http://trac.pjsip.org/repos/wiki
+- `PJSIP General Wiki <http://trac.pjsip.org/repos/wiki>`_ is the home for all documentation
+- `PJSIP FAQ <http://trac.pjsip.org/repos/wiki/FAQ>`_
+- `PJSIP Reference Manual <http://trac.pjsip.org/repos/wiki>`_ - please see Reference Manual section
 
 
 
diff --git a/doc/pjsip-book/intro_pjsua2.rst b/doc/pjsip-book/intro_pjsua2.rst
index b82bf1a9..c2085dfe 100644
--- a/doc/pjsip-book/intro_pjsua2.rst
+++ b/doc/pjsip-book/intro_pjsua2.rst
@@ -51,6 +51,9 @@ Threading
 ----------
 For platforms that require polling, the PJSUA2 module provides its own worker thread to poll PJSIP, so it is not necessary to instantiate own your polling thread. Having said that the application should be prepared to have the callbacks called by different thread than the main thread. The PJSUA2 module itself is thread safe.
 
+Often though, especially if you use PJSUA2 with high level languages such as Python, it is required to disable PJSUA2 internal worker threads by setting EpConfig.uaConfig.threadCnt to 0, because the high level environment doesn't like to be called by external thread (such as PJSIP's worker thread).
+
+
 Problems with Garbage Collection
 --------------------------------
 Garbage collection (GC) exists in Java and Python (and other languages, but we don't support those for now), and there are some problems with it when it comes to PJSUA2 usage:
@@ -96,7 +99,7 @@ To load from the file:
 
 Building PJSUA2
 ======================
-The PJSUA2 C++ library will be built by default by PJSIP build system.
+The PJSUA2 C++ library will be built by default by PJSIP build system. Standard C++ library is required.
 
 Building Python and Java SWIG Modules
 ======================================
@@ -105,6 +108,7 @@ The SWIG modules for Python and Java are built by invoking ``make`` and ``make i
 Requirements
 ------------
 
+#. `SWIG <http://www.swig.org>`_
 #. ``JDK``.
 #. ``Python``, version 2.7 or above is required.
    For **Linux/UNIX**, you will also need ``Python developent package`` (called ``python-devel`` (e.g. on Fedora) or ``python2.7-dev`` (e.g. on Ubuntu)). For **Windows**, you will need MinGW and ``Python SDK`` such as `ActivePython-2.7.5`_ from `ActiveState`_.