[openvrml-commit] openvrml/doc index.doc,1.4,1.5

[Braden M. <br...@us...>]

Update of /cvsroot/openvrml/openvrml/doc
In directory sc8-pr-cvs3.sourceforge.net:/tmp/cvs-serv3665/doc

Modified Files:
	index.doc 
Log Message:
Factored creation of openvrml::resource_istreams to a dedicated abstract factory, openvrml::resource_fetcher.  This allows the code associated with resource fetching to live at least as long as the browser instance, which it needs to do if there are any outstanding fetches happening when the browser instance is destroyed.

Index: index.doc
===================================================================
RCS file: /cvsroot/openvrml/openvrml/doc/index.doc,v
retrieving revision 1.4
retrieving revision 1.5
diff -C2 -d -r1.4 -r1.5
*** index.doc	25 Oct 2006 22:33:20 -0000	1.4
--- index.doc	22 Nov 2006 00:05:18 -0000	1.5
***************
*** 56,60 ****
   * supported by modern Web browsers (significantly, @c ftp and @c http).
   *
!  * @subsubsection introducing_resource_istream 2.1.2 Introducing resource_istream
   *
   * OpenVRML accomplishes this extensibility by extending the C++ IOStreams
--- 56,60 ----
   * supported by modern Web browsers (significantly, @c ftp and @c http).
   *
!  * @subsubsection resource_istream 2.1.2 resource_istream and resource_fetcher
   *
   * OpenVRML accomplishes this extensibility by extending the C++ IOStreams
***************
*** 72,83 ****
   * it and providing implementations for its pure virtual functions.
   *
!  * @subsubsection introducing_browser 2.1.3 Introducing browser
   *
!  * The centerpiece of the OpenVRML library is @c openvrml::browser.  This
!  * class provides the interface for loading VRML/X3D worlds.  Most management
!  * of the runtime will be handled through its member functions.  Like
!  * @c resource_istream, @c browser is an abstract class that users must inherit.
!  * However, @c browser has only one pure virtual function you must implement:
!  * the one responsible for creating @c resource_istream%s.
   *
   * @code
--- 72,82 ----
   * it and providing implementations for its pure virtual functions.
   *
!  * OpenVRML constructs @c resource_istream instances through the @c
!  * resource_fetcher interface.  @c resource_fetcher is an <a
!  * href="http://en.wikipedia.org/wiki/Abstract_factory_pattern">abstract
!  * factory</a> that also must be implemented by user code.
   *
!  * @c resource_fetcher has a single pure virtual function that must be
!  * implemented:
   *
   * @code
***************
*** 85,92 ****
   * @endcode
   *
!  * The API documentation for @c openvrml::browser::do_get_resource provides
!  * more details on the requirements for this function's implementation.
!  * Briefly, your implementation will return a @c std::auto_ptr to an instance
!  * of your class that implements @c openvrml::resource_istream.
   *
   * @note Most &ldquo;factory functions&rdquo; (i.e., functions that return an
--- 84,93 ----
   * @endcode
   *
!  * @c do_get_resource is, essentially, a construction function for concrete
!  * @c resource_istream%s.  The API documentation for
!  * @c  openvrml::resource_fetcher::do_get_resource provides details on the
!  * requirements for this function's implementation.  Briefly, your
!  * implementation will return a @c std::auto_ptr to an instance of your class
!  * that implements @c openvrml::resource_istream.
   *
   * @note Most &ldquo;factory functions&rdquo; (i.e., functions that return an
***************
*** 95,98 ****
--- 96,108 ----
   * a return value signals that the caller is taking ownership of the resource.
   *
+  * @subsubsection introducing_browser 2.1.3 Introducing browser
+  *
+  * The centerpiece of the OpenVRML library is @c openvrml::browser.  This
+  * class provides the interface for loading VRML/X3D worlds.  Most management
+  * of the runtime will be handled through its member functions.  @c browser is
+  * instantiated with a concrete subclass of @c resource_fetcher along with
+  * @c std::ostream instances where normal console output and error console output
+  * should be sent.
+  *
   * @subsubsection resource_istream_impl_considerations 2.1.4 resource_istream implementation considerations
   *
***************
*** 107,111 ****
   * OpenVRML's stream reading thread is reading the buffer.
   *
!  * The IOstreams framework is typically extended by inheriting
   * @c std::streambuf to implement new sources and sinks for data.  (Full
   * treatment of this topic is beyond the scope of this document; see <a
--- 117,121 ----
   * OpenVRML's stream reading thread is reading the buffer.
   *
!  * The IOStreams framework is typically extended by inheriting
   * @c std::streambuf to implement new sources and sinks for data.  (Full
   * treatment of this topic is beyond the scope of this document; see <a