|
|
Boost-Commit : |
From: lists.drrngrvy_at_[hidden]
Date: 2008-03-29 14:31:20
Author: drrngrvy
Date: 2008-03-29 14:31:19 EDT (Sat, 29 Mar 2008)
New Revision: 43933
URL: http://svn.boost.org/trac/boost/changeset/43933
Log:
Better docs.
Text files modified:
sandbox/SOC/2007/cgi/trunk/libs/cgi/doc/Jamfile.v2 | 23 ++++++-----
sandbox/SOC/2007/cgi/trunk/libs/cgi/doc/src/acknowledgements.qbk | 35 ++++++++++++++++--
sandbox/SOC/2007/cgi/trunk/libs/cgi/doc/src/cgi.qbk | 10 ++--
sandbox/SOC/2007/cgi/trunk/libs/cgi/doc/src/future_development.qbk | 28 ++------------
sandbox/SOC/2007/cgi/trunk/libs/cgi/doc/src/introduction.qbk | 24 +++++++++---
sandbox/SOC/2007/cgi/trunk/libs/cgi/doc/src/preface.qbk | 42 ++++++++++++++++++----
sandbox/SOC/2007/cgi/trunk/libs/cgi/doc/src/user_guide.qbk | 4 -
sandbox/SOC/2007/cgi/trunk/libs/cgi/doc/src/user_guide/examples.qbk | 75 ----------------------------------------
8 files changed, 105 insertions(+), 136 deletions(-)
Modified: sandbox/SOC/2007/cgi/trunk/libs/cgi/doc/Jamfile.v2
==============================================================================
--- sandbox/SOC/2007/cgi/trunk/libs/cgi/doc/Jamfile.v2 (original)
+++ sandbox/SOC/2007/cgi/trunk/libs/cgi/doc/Jamfile.v2 2008-03-29 14:31:19 EDT (Sat, 29 Mar 2008)
@@ -11,32 +11,35 @@
import doxygen ;
# compile the doxygen sources here
-#doxygen cgi_dox
-# :
+doxygen cgi_dox
+ :
# [ glob-tree ../../../boost/cgi/*.hpp : .svn ]
# [ glob-tree ../../../boost/libs/cgi/src/*.cpp : .svn ]
-# [ glob ../../../boost/cgi/*.hpp ]
+ [ glob ../../../boost/cgi/*.hpp ]
+ [ glob ../../../boost/cgi/fcgi*.hpp ]
+ [ glob ../../../boost/cgi/acgi*.hpp ]
+ [ glob ../../../boost/cgi/cgi*.hpp ]
# [ glob ../../../boost/cgi/gateway_impl/*.hpp ]
# [ glob ../../../boost/cgi/gateway_service/*.hpp ]
-# [ glob ../../../boost/cgi/http/*.hpp ]
+ [ glob ../../../boost/cgi/http/*.hpp ]
# [ glob ../../../boost/cgi/connections/*.hpp ]
# [ glob ../../../boost/cgi/request_impl/*.hpp ]
# [ glob ../../../boost/cgi/request_service/*.hpp ]
-# :
+ :
# <doxygen:param>HIDE_UNDOC_MEMBERS=NO
-# <doxygen:param>EXTRACT_PRIVATE=NO
+ <doxygen:param>EXTRACT_PRIVATE=NO
# #<doxygen:param>EXTRACT_ALL=YES
-# <doxygen:param>SEARCH_INCLUDES=YES
+ <doxygen:param>SEARCH_INCLUDES=YES
# <doxygen:param>INCLUDE_PATH=$(BOOST_ROOT)
-# ;
+ ;
xml cgi_xml : src/cgi.qbk ;
boostbook standalone
:
cgi_xml
-# cgi_dox
+ cgi_dox
:
<doxygen.processor>doxproc
<doxygen.doxproc.index>no
@@ -49,7 +52,7 @@
# the depth (of sub-pages) the TOC shows
<xsl:param>toc.max.depth=1
# Path to the stylesheet
- <xsl:param>html.stylesheet=../../../../../../../../boost/trunk/doc/html/boostbook.css
+ <xsl:param>html.stylesheet=../../../../../../boost/trunk/doc/html/boostbook.css
#
<xsl:param>toc.section.depth=2
Modified: sandbox/SOC/2007/cgi/trunk/libs/cgi/doc/src/acknowledgements.qbk
==============================================================================
--- sandbox/SOC/2007/cgi/trunk/libs/cgi/doc/src/acknowledgements.qbk (original)
+++ sandbox/SOC/2007/cgi/trunk/libs/cgi/doc/src/acknowledgements.qbk 2008-03-29 14:31:19 EDT (Sat, 29 Mar 2008)
@@ -7,14 +7,39 @@
[section Acknowledgements]
-Provided courtesy of the Google Summer of Code (GSoC '08)!
+The library in its current form was started as part of the Google Summer of Code (GSoC '07) - in my case a union of [@http://code.google.com/soc Google] collaborating with [@http://boost.org Boost]!
-Christopher Kohlhoff: for crafting Boost.Asio, which does most of the hard stuff. Chris mentored me through the GSoC (no mean feat!), without which this library would not be in your hands.
+People involved in the development of this library:
-Phil Endecott: for offering use-cases and encouragement at the start of the GSoC and for coming up with many further suggestions (such as the Client concept) in the months since.
+* [*Christopher Kohlhoff]: for crafting __asio__, which does most of the hard stuff. Chris mentored me through the GSoC (no mean feat!), without which this library would be neither in your hands, nor modelled the way it is.
-The Boost mailing lists: for so many deeply critical and objective comments about the library. :) That, is a relentless and ['Good Thing].
+* [*Phil Endecott]: for offering use-cases and encouragement at the start of the GSoC and for coming up with many further suggestions (such as the Client concept) in the months since.
-[-forgetting everyone's names:] Jeff Dunlap
+* [*Peter Simons]: His FastCGI library [@http://cryp.to/libfastcgi libfastcgi] provided initial motivation for this library. Also his article [@http://cryp.to/publications/fastcgi/ "FastCGI - The Forgotten Treasure"] is an good read for those not sold on FastCGI.
+
+Also many thanks to:
+
+* [*Jeff Dunlap]: for help with testing and for pushing the idea of supporting HTML templates. Jeff provided an online version of the amortization example which I aimed to replicate using this library and Google.cTemplate.
+
+* [*Jeff Garland]: for organising access to Boost's SVN repo, being involved in early discussion and probably being involved in my SoC application having any chance. :)
+
+* [*Christian Henning]: for help testing early code.
+
+The [*Boost mailing lists]: for so many helpful and objective comments about the library.
+
+Discussions on the Boost lists included:
+
+* *Martin Wille*
+* *Mathias Gaunard*
+* *Peter Foley*
+* *'Jose'*
+* *'Shams'*
+* *Peter Dimov*
+* *Simon Richter*
+* *Cris Frey*
+* *Sohail Somani*
+* *Jean-Christophe Roux*
+
+[-forgetting everyone's names:] Apologies to anyone missed... tell me, please!
[endsect]
Modified: sandbox/SOC/2007/cgi/trunk/libs/cgi/doc/src/cgi.qbk
==============================================================================
--- sandbox/SOC/2007/cgi/trunk/libs/cgi/doc/src/cgi.qbk (original)
+++ sandbox/SOC/2007/cgi/trunk/libs/cgi/doc/src/cgi.qbk 2008-03-29 14:31:19 EDT (Sat, 29 Mar 2008)
@@ -40,10 +40,10 @@
[def __tutorial__ [link boost.cgi.tutorial tutorial]]
[def __reference__ [link /doc/html/cgi/reference.html reference]]
-[def __current_branch__ http://svn.boost.org/trac/boost/browser/sandbox/SOC/2007/cgi/branches/acceptor_work]
+[def __current_branch__ http://svn.boost.org/trac/boost/browser/sandbox/SOC/2007/cgi/branches/release]
-[def __examples__ [@http://svn.boost.org/trac/boost/browser/sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/example examples]]
-[def __amort_example__ [@http://svn.boost.org/trac/boost/browser/sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/example/acgi/amortization Amortization]]
+[def __examples__ [@http://svn.boost.org/trac/boost/browser/sandbox/SOC/2007/cgi/branches/release/libs/cgi/example examples]]
+[def __amort_example__ [@http://svn.boost.org/trac/boost/browser/sandbox/SOC/2007/cgi/branches/release/libs/cgi/example/acgi/amortization Amortization]]
[def __GET__ `GET` ]
@@ -52,7 +52,7 @@
[def __PUT__ `PUT` ]
-[def __Service__ [@http://asio.sourceforge.net/boost_asio_0_3_8/libs/asio/doc/html/boost_asio/reference/Service.html Service]]
+[def __Service__ [@http://asio.sourceforge.net/boost_asio_0_3_9/libs/asio/doc/html/boost_asio/reference/Service.html Service]]
[/def __boost_thread__ #link#to#boost#thread#docs#]
[/def __IoService__ #link#to#io#service#docs#]
@@ -117,4 +117,4 @@
[include:server_support user_guide/server_support.qbk]
-[/include acknowledgements.qbk]
+[include acknowledgements.qbk]
Modified: sandbox/SOC/2007/cgi/trunk/libs/cgi/doc/src/future_development.qbk
==============================================================================
--- sandbox/SOC/2007/cgi/trunk/libs/cgi/doc/src/future_development.qbk (original)
+++ sandbox/SOC/2007/cgi/trunk/libs/cgi/doc/src/future_development.qbk 2008-03-29 14:31:19 EDT (Sat, 29 Mar 2008)
@@ -13,13 +13,13 @@
[h4 SCGI support.]
-Due to configuration issues, this isn't functional yet.
+I haven't managed to get apache/lighttpd configured properly for SCGI, so this isn't functional yet.
[h4 FastCGI support.]
FastCGI support is essential to any modern CGI library. There is currently ['no] known FastCGI library for C or C++ that aims to implement the complete [@http://www.fastcgi.com/devkit/doc/fcgi-spec.html FastCGI 1.0] specification. Providing support for multiplexing FastCGI daemons is one of this library's major goals.
-There are a couple of issues that have yet to be worked out, but in general the new framework is known to 'fit' with all the details of FastCGI and should lend itself to an efficient implementation. It's only partially working at the moment.
+There are a couple of issues that have yet to be worked out, but FastCGI is working in a basic way now.
[h4 Access to error output streams]
@@ -106,32 +106,14 @@
[h4 Support for environment Passed on Command Line]
-See section 4.4 of [@http://www.ietf.org/rfc/rfc3875].
+See section 4.4 of [@http://www.ietf.org/rfc/rfc3875]. Should be easy to do by modifying the `acgi::service` class.
[h4 Support for Multi-part POST Forms]
-
-
-[h4 `operator[]` Overloading]
-
-What is currently:
-``
-request req;
-std::string a( req.form_("a") );
-map& forms = req.form_();
-``
-could become:
-``
-request req;
-std::string a(req[form_, "a"]);
-map& forms = req[form_];
-a = req[form_]["a"]; // better to the above, plus is more 'standard'
-``
+This has been added to the CGI part of the library, but it's very ugly and hackish. The idea is to create a `form_parser` class that can be used both internally and externally to parse multipart forms.
[/h4 Removing aCGI/CGI Divide]
-[/h4 Support for wide characters]
-
-[/The library generally works on octets, but there should be some way to ]
+[/h4 Unicode Support]
[endsect]
Modified: sandbox/SOC/2007/cgi/trunk/libs/cgi/doc/src/introduction.qbk
==============================================================================
--- sandbox/SOC/2007/cgi/trunk/libs/cgi/doc/src/introduction.qbk (original)
+++ sandbox/SOC/2007/cgi/trunk/libs/cgi/doc/src/introduction.qbk 2008-03-29 14:31:19 EDT (Sat, 29 Mar 2008)
@@ -22,11 +22,15 @@
return_(req, resp, 0); // write the response and 'return 0;'
}
+``
Example request:
+``
example.com/program_name?name=Mr.+Allison
+``
-Output:
+Output (as viewed in a web browser):
+``
Hello there, Universe. -- Mr. Allison
``
@@ -39,7 +43,7 @@
[h4 Concepts]
-The library provides abstractions which hide details of the vastly different specifications of CGI, FastCGI and SCGI. The main abstractions are, briefly:
+The library provides abstractions which hide details of the varying specifications of CGI, FastCGI and SCGI. The main abstractions are, briefly:
[table
[
@@ -72,17 +76,23 @@
[h4 Protcols]
-[:['See __protocol_details__ for more.]]
+[:['See __protocol_details__ for more.]] [/ **FIXME** ]
-In a nutshell, CGI is the simple and 'original' way of communicating with web servers. I'll assume you know what it is: one request per process and communication using standard input/output. A nice and simple way of making ['web pages that can change].
+In a nutshell, CGI is the simple and 'original' way of communicating with web servers. I'll assume you know what it is: one request per process and communication using standard input/output. A nice and simple way of making ['dynamic web pages].
-FastCGI was then developed as a means of allowing much more scalable CGI-like programs to be written. In fact, the FastCGI specification implies scalability was the main motivation for the protocol. Communication with the server works over sockets or pipes (only TCP sockets are supported for now). Each process and each connection can be used for handling multiple requests. In theory this means you could have a single monolithic process behind your HTTP server handling all incoming requests concurrently.
+[tip If you're new to CGI, have a look at this: [@http://hoohoo.ncsa.uiuc.edu/cgi/]]
+
+__FastCGI__ was then developed as a means of allowing much more scalable CGI-like programs to be written. In fact, the FastCGI specification implies scalability was the main motivation for the protocol. Communication with the server works over sockets or pipes (only TCP sockets are supported for now). Each process and each connection can be used for handling multiple requests. In theory this means you could have a single monolithic process behind your HTTP server handling all incoming requests concurrently.
+
+[note
+ Some initial benchmarks show that simple FastCGI programs are 3-5x faster than their CGI counterparts. When using database connections and/or HTML templates, the gap should get even bigger.
+]
-SCGI is essentially a simpler version - hence [*S]imple[*CGI] - of FastCGI but is still a significant step up from vanilla CGI, mainly because each process can handle multiple requests. Use of FastCGI is recommended over SCGI, but unfortunately support for FastCGI is unreliable and buggy with some servers and/or you may not have that option.
+__SCGI__ is essentially a simpler version of FastCGI - hence [*S]imple[*CGI] - but is still a significant step up from vanilla CGI, mainly because each process can handle multiple requests. Use of FastCGI is recommended over SCGI, but unfortunately support for FastCGI is unreliable and buggy with some servers and/or you may not have that option. [/ **FIXME**] SCGI support isn't included yet.
[h4 Multiple Requests per Process]
-So I keep harping on about this, that's because it removes so many limitations of traditional CGI programming. Your programs can become servers, capable of handling an arbitrary number of requests with each invocation (assuming they don't crash, or leak memory!). This gives you the freedom to keep database connections open between requests or cache ready-parsed responses, for example. Processing of a client request can even be continued in the case of the client crashing - the `response` can then be stored and given to them when they return - saving precious CPU cycles.
+Having persistent processes is very handy. It removes so many of the limitations of traditional CGI programming; suddenly CGI programs aren't so different to desktop applications. CGI 'scripts' become FastCGI servers, capable of handling an arbitrary number of requests with each invocation (assuming they don't crash, or leak memory!). This gives you the freedom to keep database connections open between requests or cache ready-parsed responses, for example. Processing of a client request can even be continued in the case of the client crashing - the `response` can then be stored and given to them when they return - saving precious CPU cycles.
The downside is added complexity: managing multiple requests and having to keep a tight reign on memory/resource consumption.
Modified: sandbox/SOC/2007/cgi/trunk/libs/cgi/doc/src/preface.qbk
==============================================================================
--- sandbox/SOC/2007/cgi/trunk/libs/cgi/doc/src/preface.qbk (original)
+++ sandbox/SOC/2007/cgi/trunk/libs/cgi/doc/src/preface.qbk 2008-03-29 14:31:19 EDT (Sat, 29 Mar 2008)
@@ -23,7 +23,7 @@
[h3 Motivation]
-C++ isn't the language of choice for many CGI programmers, despite being a powerful one that can be used to produce scalable, maintainable and uncompromisingly efficient applications.
+C++ may not be the most common language used for CGI programming, but it is a powerful one that can be used to produce scalable, maintainable and uncompromisingly efficient applications.
A discussion about the benefits of CGI programming in C++ is beyond the scope of this document and I've assumed you're here because you want to try C++ CGI programming, but here is a short list anyway:
@@ -31,9 +31,9 @@
* C++ has a very large and professional user base, providing a wealth of expertise and experience.
-* Billions of lines of C++ code can be reused to reduce development/testing times.
+* Millions of lines of C++ code can be reused to reduce development/testing times.
-* In places where RAD (rapid application development) is of the utmost importance, scripting languages can still be used, for instance by using [link __boost_python__ Boost.Python] - though it could be argued that C++ and RAD are not mutually exclusive.
+* In places where RAD (rapid application development) is of the utmost importance, scripting languages can still be used, for instance by using [link __boost_python__ Boost.Python.
* C++ is ['fast]. You can rest assured that the language will never be a bottleneck for your applications.
@@ -45,23 +45,47 @@
The generally poor support for CGI programming for C++ - most libraries are either unmaintained, or don't take advantage of modern C++ capabilities - has driven the development of this library. [-moremoremore]
-[h3 How to use this manual]
+[section:using How to use this manual]
[note
-At the moment, the Boost [@http://www.boost.org/more/lib_guide.htm#Guidelines style guidelines] aren't honoured properly or consistently. Please ignore this for now, as the ambiguity is intentional (['since this [*is not] a Boost library]) and is simple enough to rectify.
+At the moment, the Boost [@http://www.boost.org/more/lib_guide.htm#Guidelines style guidelines] aren't honoured properly or consistently. Please ignore this for now, as the ambiguity is half-intentional (['since this [*is not] a Boost library]). It's simple enough to rectify.
]
-Start with the introduction, then the tutorial. You can skip the 'scripting' section, as that is a quickstart and the information in it is repeated throughout the rest of the manual. The doxygen header reference is very ugly for now and is going to be heavily reworked and reorganised.
-
[h4 Naming Conventions]
+[h5 Headers]
+
+[table What Headers to Include
+ [[Protocol] [`#include` line]]
+ [[All] [`#include <boost/cgi.hpp>`]]
+ [[CGI] [`#include <boost/cgi/cgi.hpp>`]]
+ [[aCGI] [`#include <boost/cgi/acgi.hpp>`]]
+ [[FastCGI] [`#include <boost/cgi/fcgi.hpp>`]]
+]
+
+[h5 Namespaces]
+
+The classes/functions that are shared between protocols are in the `cgi::common` namespace. Using the above headers dumps these into the relevant namespace.
+
+[table
+ [[Protocol] [`namespace`]]
+ [[CGI] [`namespace boost::cgi`
+ `namespace cgi::cgi`]]
+ [[aCGI] [`namespace boost::acgi`
+ `namespace cgi::acgi`]]
+ [[FastCGI] [`namespace boost::fcgi`
+ `namespace cgi::fcgi`]]
+]
+
[h5 Macros]
Macros are prefixed with `BOOST_CGI_*` .
+[/ **FIXME**] There aren't any tested public macros yet, when there are they will be listed here.
+
[h5 Code snippets]
-As you are probably used to, it is assumed that code snippets in this manual have the correct `#include`s and "`using namespace cgi;`" prepended to them. Information about the correct headers to include can be found [link __headers__ here].
+As you are probably used to, it is assumed that code snippets in this manual have the correct `#include`s and "`using namespace boost::<protocol>;`" prepended to them.
[h3 Comments and Support]
@@ -71,4 +95,6 @@
or thereabouts.
+[endsect][/ using]
+
[endsect]
Modified: sandbox/SOC/2007/cgi/trunk/libs/cgi/doc/src/user_guide.qbk
==============================================================================
--- sandbox/SOC/2007/cgi/trunk/libs/cgi/doc/src/user_guide.qbk (original)
+++ sandbox/SOC/2007/cgi/trunk/libs/cgi/doc/src/user_guide.qbk 2008-03-29 14:31:19 EDT (Sat, 29 Mar 2008)
@@ -13,15 +13,13 @@
[include:server_config user_guide/server_configuration.qbk]
-[include:headers user_guide/headers.qbk]
-
[endsect]
[/include:protocols user_guide/protocols.qbk]
[/include:tutorial user_guide/tutorial.qbk]
-[include:examples user_guide/examples.qbk]
+[include:examples ../../example/doc.qbk]
[include user_guide/tutorial/tutorial.qbk]
Modified: sandbox/SOC/2007/cgi/trunk/libs/cgi/doc/src/user_guide/examples.qbk
==============================================================================
--- sandbox/SOC/2007/cgi/trunk/libs/cgi/doc/src/user_guide/examples.qbk (original)
+++ sandbox/SOC/2007/cgi/trunk/libs/cgi/doc/src/user_guide/examples.qbk 2008-03-29 14:31:19 EDT (Sat, 29 Mar 2008)
@@ -1,76 +1 @@
-[section Examples]
-
-[template example_link[protocol example_name link_text] [@../../example/\ [protocol]/[example_name]/main.cpp [link_text]]]
-
-The examples can be built by going into their directory and typing `bjam`. If you have a server set up and wish to test the applications behind them, you can automatically copy them to your server's cgi-bin (or fcgi-bin or scgi-bin) one of two ways:
-
-* `bjam install --cgi-bin=/usr/lib/cgi-bin` - installs the program (or set of programs) into `/usr/lib/cgi-bin` [*iff] they are a CGI program. If you want to install examples in the `/libs/cgi/example/fcgi/` directory, for instance, type the above but replace `--cgi-bin` to `--fcgi-bin`.
-
-* set the environment variable `BOOST_CGI_BIN_PATH` (or `BOOST_FCGI_BIN_PATH`/`BOOST_SCGI_BIN_PATH`) and just type `bjam install`. The example(s) will be installed into the relevant directory.
-
-[note
- The command line option will override the environment variable, so you can use the environment variables for default installation.
-]
-
-[section aCGI]
-
-[import ../../../example/cgi/echo/main.cpp]
-
-Linky: [example_link acgi..echo..aCGI Echo example]
-
-[@../../../example/cgi/echo/main.cpp]
-
-[file]
-
-[endsect] [/ acgi]
-
-[section CGI]
-
-[endsect] [/ cgi]
-
-[section FastCGI]
-
-[def __fcgi_hello_world__ ../../../example/fcgi/hello_world/main.cpp]
-[def __fcgi_echo__ ../../../example/fcgi/echo/main.cpp]
-
-[section "Hello, world."]
-
-[import ../../../example/fcgi/hello_world/main.cpp]
-
-Click to see the [link __fcgi_hello_world__ source file]
-
-[file]
-
-[endsect] [/ hello_world]
-
-[section Echo]
-
-[/import __fcgi_echo__]
-
-[template call_import[protocol_t example_name]
-[import ../../example/\ [protocol_t]/[name]/main.cpp]
-]
-
-[call_import fcgi..amortization]
-
-[template import_example[protocol name]
-
-[import ../../example/[protocol]/[name]/main.cpp]
-
-Click to see the [@../../../example/[protocol]/[name]/main.cpp source file].
-
-]
-
-[import_example fcgi..echo]
-
-Click to see the [/example_link[fcgi..echo..source file]].
-
-[fcgi_echo]
-
-[endsect] [/ echo]
-
-[endsect] [/ fastcgi]
-
-[endsect]
-
Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk