|
|
Boost-Commit : |
From: lists.drrngrvy_at_[hidden]
Date: 2007-08-16 18:46:18
Author: drrngrvy
Date: 2007-08-16 18:46:14 EDT (Thu, 16 Aug 2007)
New Revision: 38734
URL: http://svn.boost.org/trac/boost/changeset/38734
Log:
Completing earlier commit with more docs.
Added:
sandbox/SOC/2007/cgi/libs/cgi/doc/src/building.qbk (contents, props changed)
sandbox/SOC/2007/cgi/libs/cgi/doc/src/future_development.qbk (contents, props changed)
sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide.qbk (contents, props changed)
sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/headers.qbk (contents, props changed)
sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/server_configuration.qbk (contents, props changed)
sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/server_support.qbk (contents, props changed)
Text files modified:
sandbox/SOC/2007/cgi/boost/cgi/acgi/request.hpp | 7 +--
sandbox/SOC/2007/cgi/boost/cgi/cgi/request.hpp | 8 ++--
sandbox/SOC/2007/cgi/boost/cgi/detail/cgi_request_impl_base.hpp | 10 +++---
sandbox/SOC/2007/cgi/boost/cgi/detail/cgi_service_impl_base.hpp | 6 +-
sandbox/SOC/2007/cgi/boost/cgi/detail/common_headers.hpp | 20 ++++++------
sandbox/SOC/2007/cgi/boost/cgi/detail/protocol_traits.hpp | 6 +-
sandbox/SOC/2007/cgi/libs/cgi/doc/Jamfile.v2 | 4 +-
sandbox/SOC/2007/cgi/libs/cgi/doc/src/cgi.qbk | 64 +++++++++++++++++----------------------
sandbox/SOC/2007/cgi/libs/cgi/doc/src/introduction.qbk | 18 ++++++++++
sandbox/SOC/2007/cgi/libs/cgi/doc/src/preface.qbk | 47 ++++++++--------------------
sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/building.qbk | 49 +++++++++++++++++++++++------
sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/protocols.qbk | 6 +-
sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/tutorial.qbk | 33 ++++++++------------
sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/tutorial/accepting.qbk | 6 +-
sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/tutorial/loading.qbk | 6 +-
sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/tutorial/meta_data.qbk | 39 ++++++++++++++++-------
16 files changed, 176 insertions(+), 153 deletions(-)
Modified: sandbox/SOC/2007/cgi/boost/cgi/acgi/request.hpp
==============================================================================
--- sandbox/SOC/2007/cgi/boost/cgi/acgi/request.hpp (original)
+++ sandbox/SOC/2007/cgi/boost/cgi/acgi/request.hpp 2007-08-16 18:46:14 EDT (Thu, 16 Aug 2007)
@@ -11,10 +11,9 @@
#include "request_impl.hpp"
#include "request_service.hpp"
-#include "../tags.hpp"
-#include "../basic_request_fwd.hpp"
-#include "../request_impl/acgi_request_impl.hpp"
-//#include "../service_impl/acgi_service_impl.hpp"
+#include "boost/cgi/tags.hpp"
+#include "boost/cgi/basic_request_fwd.hpp"
+#include "boost/cgi/acgi/request_impl.hpp"
namespace cgi {
Modified: sandbox/SOC/2007/cgi/boost/cgi/cgi/request.hpp
==============================================================================
--- sandbox/SOC/2007/cgi/boost/cgi/cgi/request.hpp (original)
+++ sandbox/SOC/2007/cgi/boost/cgi/cgi/request.hpp 2007-08-16 18:46:14 EDT (Thu, 16 Aug 2007)
@@ -10,10 +10,10 @@
#define CGI_CGI_REQUEST_HPP_INCLUDED__
#include "request_service.hpp"
-#include "../tags.hpp"
-#include "../basic_request_fwd.hpp"
-#include "../request_impl/cgi_request_impl.hpp"
-#include "../basic_request.hpp"
+#include "boost/cgi/tags.hpp"
+#include "boost/cgi/basic_request_fwd.hpp"
+#include "boost/cgi/cgi/cgi_request_impl.hpp"
+#include "boost/cgi/basic_request.hpp"
namespace cgi {
Modified: sandbox/SOC/2007/cgi/boost/cgi/detail/cgi_request_impl_base.hpp
==============================================================================
--- sandbox/SOC/2007/cgi/boost/cgi/detail/cgi_request_impl_base.hpp (original)
+++ sandbox/SOC/2007/cgi/boost/cgi/detail/cgi_request_impl_base.hpp 2007-08-16 18:46:14 EDT (Thu, 16 Aug 2007)
@@ -14,11 +14,11 @@
#include <boost/noncopyable.hpp>
#include <boost/shared_ptr.hpp>
-#include "../http/status_code.hpp"
-#include "../connections/stdio.hpp"
-#include "../role_type.hpp"
-#include "../status_type.hpp"
-#include "../map.hpp"
+#include "boost/cgi/http/status_code.hpp"
+#include "boost/cgi/connections/stdio.hpp"
+#include "boost/cgi/role_type.hpp"
+#include "boost/cgi/status_type.hpp"
+#include "boost/cgi/map.hpp"
//#include
// Make this ProtocolService-independent
Modified: sandbox/SOC/2007/cgi/boost/cgi/detail/cgi_service_impl_base.hpp
==============================================================================
--- sandbox/SOC/2007/cgi/boost/cgi/detail/cgi_service_impl_base.hpp (original)
+++ sandbox/SOC/2007/cgi/boost/cgi/detail/cgi_service_impl_base.hpp 2007-08-16 18:46:14 EDT (Thu, 16 Aug 2007)
@@ -10,9 +10,9 @@
#include <boost/tokenizer.hpp>
#include <boost/system/error_code.hpp>
-#include "../map.hpp"
-#include "../role_type.hpp"
-#include "../detail/extract_params.hpp"
+#include "boost/cgi/map.hpp"
+#include "boost/cgi/role_type.hpp"
+#include "boost/cgi/detail/extract_params.hpp"
//#include "../connections/stdio.hpp"
namespace cgi {
Modified: sandbox/SOC/2007/cgi/boost/cgi/detail/common_headers.hpp
==============================================================================
--- sandbox/SOC/2007/cgi/boost/cgi/detail/common_headers.hpp (original)
+++ sandbox/SOC/2007/cgi/boost/cgi/detail/common_headers.hpp 2007-08-16 18:46:14 EDT (Thu, 16 Aug 2007)
@@ -12,15 +12,15 @@
// #include all protocol-independent headers only. Protocol-specific
// headers can just include this after other headers.
-#include "../buffer.hpp"
-#include "../map.hpp"
-#include "../io_service.hpp"
-#include "../streambuf.hpp"
-#include "../basic_request.hpp"
-//#include "../basic_request_acceptor.hpp"
-#include "../reply.hpp"
-//#include "../logger.hpp"
-#include "../read.hpp"
-#include "../write.hpp"
+#include "boost/cgi/buffer.hpp"
+#include "boost/cgi/map.hpp"
+#include "boost/cgi/io_service.hpp"
+#include "boost/cgi/streambuf.hpp"
+#include "boost/cgi/basic_request.hpp"
+//#include "boost/cgi/basic_request_acceptor.hpp"
+#include "boost/cgi/reply.hpp"
+//#include "boost/cgi/logger.hpp"
+#include "boost/cgi/read.hpp"
+#include "boost/cgi/write.hpp"
#endif // CGI_CGI_CGI_HPP_INCLUDED__
Modified: sandbox/SOC/2007/cgi/boost/cgi/detail/protocol_traits.hpp
==============================================================================
--- sandbox/SOC/2007/cgi/boost/cgi/detail/protocol_traits.hpp (original)
+++ sandbox/SOC/2007/cgi/boost/cgi/detail/protocol_traits.hpp 2007-08-16 18:46:14 EDT (Thu, 16 Aug 2007)
@@ -9,9 +9,9 @@
#ifndef CGI_REQUEST_TRAITS_HPP_INCLUDED__
#define CGI_REQUEST_TRAITS_HPP_INCLUDED__
-#include "../tags.hpp"
-#include "../basic_request_fwd.hpp"
-#include "../basic_connection_fwd.hpp"
+#include "boost/cgi/tags.hpp"
+#include "boost/cgi/basic_request_fwd.hpp"
+#include "boost/cgi/basic_connection_fwd.hpp"
namespace cgi {
Modified: sandbox/SOC/2007/cgi/libs/cgi/doc/Jamfile.v2
==============================================================================
--- sandbox/SOC/2007/cgi/libs/cgi/doc/Jamfile.v2 (original)
+++ sandbox/SOC/2007/cgi/libs/cgi/doc/Jamfile.v2 2007-08-16 18:46:14 EDT (Thu, 16 Aug 2007)
@@ -43,8 +43,8 @@
<xsl:param>boost.libraries=/usr/local/src/boost/libs/libraries.htm
<xsl:param>boost.images=http://beta.boost.org/images
<xsl:param>toc.max.depth=0
- <xsl:param>toc.section.depth=3
- <xsl:param>chunk.section.depth=2
+ <xsl:param>toc.section.depth=2
+ <xsl:param>chunk.section.depth=10
;
#install html
Added: sandbox/SOC/2007/cgi/libs/cgi/doc/src/building.qbk
==============================================================================
--- (empty file)
+++ sandbox/SOC/2007/cgi/libs/cgi/doc/src/building.qbk 2007-08-16 18:46:14 EDT (Thu, 16 Aug 2007)
@@ -0,0 +1,53 @@
+[/
+ / Copyright (c) 2007 Darren Garvey
+ /
+ / Distributed under the Boost Software License, Version 1.0. (See accompanying
+ / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ /]
+
+[section Building]
+
+Boost.CGI is a header-only library (for now), but it relies on [link __boost_system__ Boost.System], which for now must be built.
+
+[/h5 What you need:]
+
+[note
+* Boost-related elements can be downloaded from the Boost download site at sourceforge, here: http://sf.net/project/showfiles.php?group_id=7586
+
+* "invoking `bjam`" implies calling "`bjam --toolset=`[link __toolsets__ one_of_these]". More information can be found [link __boost_getting_started__ here] (these are general instructions for building Boost [*and] configuring `bjam`. Following these instructions will also 'tick' the first two requirements below.
+]
+
+[table What you need
+ [[Element] [Optional?] [Instructions]]
+ [
+ [Boost.Jam - `bjam`]
+ [No]
+ [Download 'boost-jam' (precomiled versions are highly recommended) and make it accessible by putting it somewhere pointed to by your system's PATH.]
+ ]
+ [
+ [Boost.System]
+ [No]
+ [* Download the latest Boost distro, 'boost'.
+
+ * Set the environment variable BOOST_ROOT on your system to the download location.
+
+ * Go to the directory BOOST_ROOT and invoke `bjam` (see above). This should finish without any fails.]
+ ]
+ [
+ [Documentation]
+ [Yes]
+ [These are built by going to the libs/cgi/doc directory and invoking `bjam` (see above). You can then read the docs by directing your browser to libs/cgi/index.html]
+ ]
+ [
+ [Unit tests]
+ [Yes]
+ [Tests can be run by going to the libs/cgi/test directory and invoking `bjam` (see above). Boost.CGI aims to be cross-platform, but not all platforms are available for testing. If any tests fail, problems can be reported to [link __reporting_problems__ here].]
+ ]
+ [
+ [Examples]
+ [Yes]
+ [The examples are a useful guide to uses of the library. They are also useful for testing your server configuration. They can all be found in the lib/cgi/example directory. Invoking `bjam` in the example directory should build all examples whereas invoking `bjam` in each sub-directory will build only the example contained therein.]
+ ]
+]
+
+[endsect]
Modified: sandbox/SOC/2007/cgi/libs/cgi/doc/src/cgi.qbk
==============================================================================
--- sandbox/SOC/2007/cgi/libs/cgi/doc/src/cgi.qbk (original)
+++ sandbox/SOC/2007/cgi/libs/cgi/doc/src/cgi.qbk 2007-08-16 18:46:14 EDT (Thu, 16 Aug 2007)
@@ -6,7 +6,7 @@
/]
[library CGI
- [quickbook 1.3]
+ [quickbook 1.4]
[version 0.01]
[id boost.cgi]
[dirname the_document_dir]
@@ -32,49 +32,41 @@
[def __tutorial__ [link boost.cgi.tutorial tutorial]]
[def __reference__ [link /doc/html/cgi/reference.html reference]]
-[/
-[def __Service__ #link#to#service#concept#description#]
-
-[def __boost_thread__ #link#to#boost#thread#docs#]
-[def __IoService__ #link#to#io#service#docs#]
-[def __protocol__ #link#to#protocol#section# boost.user_guide.protocols]
-[def __ProtocolService__ boost.reference.concepts.protocol_service]
-[def __io_service__ #link#to#doxygen#reference#]
-[def __async_write__
- __async_read__
- __async_write_some__
- __async_read_some__
-]
-]
-[def __accepting__ boost.cgi.user_guide.tutorial.accepting]
-[def __loading__ boost.cgi.user_guide.tutorial.loading]
+[def __GET__ `GET` ]
+[def __POST__ `POST`]
+[def __HEAD__ `HEAD`]
+[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 __boost_thread__ #link#to#boost#thread#docs#]
+[/def __IoService__ #link#to#io#service#docs#]
+[/def __protocol__ #link#to#protocol#section# boost.user_guide.protocols]
+[/def __ProtocolService__ boost.reference.concepts.protocol_service]
+[/def __io_service__ #link#to#doxygen#reference#]
+[/def __async_write__]
+[/ __async_read__]
+[/ __async_write_some__]
+[/ __async_read_some__]
+
+[/ 'ug' is the id of the User's Guide section]
+[/ 'gs' is the id of the Getting Started section, which is in the User's Guide]
+[/ 'tut' is the id of the Tutorial, which is in the User's Guide]
+
+[def __headers__ boost.cgi.ug.gs.headers]
+[def __accepting__ boost.cgi.ug.tut.accepting]
+[def __loading__ boost.cgi.ug.tut.loading]
[include preface.qbk]
[include introduction.qbk]
-[section User Guide]
-
-This section of the docs is for all users of the library. For details about the internals of the library see either the __sources__ or the __reference__ section.
-
-[include user_guide/getting_started.qbk]
-
-[include user_guide/protocols.qbk]
-
-[include user_guide/tutorial.qbk]
-
-[include user_guide/examples.qbk]
-
-[endsect]
-
+[include user_guide.qbk]
[xinclude ../cgi_dox.boostbook]
-[/xinclude ../output.boostbook]
-
-[include reference.qbk]
+[include future_development.qbk]
[/include acknowledgements.qbk]
-
-[include future_development.qbk]
Added: sandbox/SOC/2007/cgi/libs/cgi/doc/src/future_development.qbk
==============================================================================
--- (empty file)
+++ sandbox/SOC/2007/cgi/libs/cgi/doc/src/future_development.qbk 2007-08-16 18:46:14 EDT (Thu, 16 Aug 2007)
@@ -0,0 +1,53 @@
+[/
+ / Copyright (c) 2007 Darren Garvey
+ /
+ / Distributed under the Boost Software License, Version 1.0. (See accompanying
+ / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ /]
+
+[section:future Future Development]
+
+[h4 Iostream functionality.]
+
+Streamed IO, likely to be similar to Boost.Asio's `basic_socket_stream<>` is required.
+
+[h4 SCGI support.]
+
+Due to configuration issues, this isn't functional yet.
+
+[h4 FastCGI support.]
+
+Complete FastCGI support is essential to any modern CGI library.
+
+[h4 Access to error output streams]
+
+CGI, SCGI and FastCGI all make provisions for some sort of error outputting, according to the following table:
+
+[table
+ [[Protocol][Native error reporting capabilities]]
+ [[CGI] [Single error output stream (`std::cout`)]]
+ [[SCGI] [A single output stream is shared between requests: Boost.CGI will guarantee thread-safe access to it.]]
+ [[FastCGI] [Error stream per request. Inherently thread-safe.]]
+]
+
+Even though the server is not obliged to do anything with this output, it is generally dumped into the default server error log. This can be invaluable for debugging.
+
+Access to the above streams will be implemented as a __Service__, which can be switched on or off at runtime. Output can be sent either to stdout, stderr, or both simultaneously. If this isn't enough, a user can add their own custom service layer, which can manipulate the data as it is read/written in any way they wish (such as logging to a database, url-encoding/filtering data, or playing an April Fool's prank on your website visitors).
+
+[h4 Session handling.]
+
+Access to persistent session data is a very useful stop-gap to using a complete RDBMS to store/retrieve data. In some cases, such as when an object is supposed to stay in active memory, a RDBMS will not be sufficient, so session management fits in nicely. A templated `basic_session<>` will be provided so various session-storage methods can be used. Boost.Interprocess is an ideal default, while Boost.UUID can be used to generate unique session identifiers.
+
+[h4 Having `meta_*` functions return a `cgi::param` type instead of `std::string`]
+
+An advantage to this approach, for the functions that look up request meta-data, is that multiple values can be easily extracted from the same key, when they exist. Currently, a user must get the complete map of meta-data and use that themselves. Since environment meta-data can't be uniformly retrieved as a `cgi::map_type&` (since they are actually process-level environment variables, accessible only through `::getenv()`) this can be awkward.
+
+Another advantage is that a macro can be provided to turn on/off implicit conversion to `std::string`, which is in essence a form of tainting, akin to perl's taint mode.
+
+Yet another possibility, is that a member function `as<>` can be provided as a shortcut to `boost::lexical_cast<>`. This could greatly improve readability of web programs, where lexical casting is very common and may make programs overly verbose.
+
+[h4 Concept Documentation]
+
+Even though this library introduces very few new concepts, they are not currently documented. Links to Boost.Asio's concept documentation is also required (essentially as part of a reworking of the doxygen reference section).
+
+[endsect]
Modified: sandbox/SOC/2007/cgi/libs/cgi/doc/src/introduction.qbk
==============================================================================
--- sandbox/SOC/2007/cgi/libs/cgi/doc/src/introduction.qbk (original)
+++ sandbox/SOC/2007/cgi/libs/cgi/doc/src/introduction.qbk 2007-08-16 18:46:14 EDT (Thu, 16 Aug 2007)
@@ -7,6 +7,22 @@
[section:intro Introduction]
+``
+#include <boost/cgi/cgi.hpp>
+using namespace cgi;
+
+int main(int, char**)
+{
+ request req;
+ reply rep;
+
+ rep<< "Hello there, Universe. "
+ << "Oh wait, no, it's you " << req.meta_form("name")
+ << ", isn't it?!";
+ rep.send(req);
+}
+``
+
This CGI library reasonably high-level library for web programming. Herein the controller portion of the Model-View-Controller idiom is implemented. The intricacies of dealing with the widely varying specifications of CGI, FastCGI and SCGI are abstracted into three main sub-parts:
* Accepting,
@@ -23,7 +39,7 @@
Even though a `cgi::srequest` is set up differently to asynchronous request types, the alternative `cgi::request` (or the explicit form `cgi::acgi_request`) can be used in exactly the same way as FastCGI and SCGI requests. This symmetry makes migrating code between different protocols trivial (see [link __interoperability__ interoperability] for more) and aids debugging of server configuration issues.
]
-FastCGI and SCGI both remove this restriction and there is support for them - of widely varying quality and completeness (see [link __server_support__ here])- in most HTTP servers. These protocols add an extra layer to your CGI programs, as you now must manage the request queue.
+FastCGI and SCGI both remove this restriction and there is support for them - of widely varying quality and completeness (see [link __server_support__ here]) - in most HTTP servers. These protocols add an extra layer to your CGI programs, as you now must manage the request queue.
In return for the added complexity, your programs become complete servers, capable of handling arbitrary numbers of requests during each invocation (assuming they don't crash!): Database connections can be kept open between requests; ready-parsed XML files can be cached; processing of a client request can even be continued in the case of the client crashing - the reply can be cached and returned to them when they return - saving precious CPU cycles.
Modified: sandbox/SOC/2007/cgi/libs/cgi/doc/src/preface.qbk
==============================================================================
--- sandbox/SOC/2007/cgi/libs/cgi/doc/src/preface.qbk (original)
+++ sandbox/SOC/2007/cgi/libs/cgi/doc/src/preface.qbk 2007-08-16 18:46:14 EDT (Thu, 16 Aug 2007)
@@ -7,13 +7,13 @@
[section Preface]
-[section Overview]
+[: [*['All science is either Physics, or stamp collecting.]] [br] -- Ernest Rutherford.]
-Boost.CGI is a library for writing CGI programs in Standard C++. It can be used to write anything from simple 'adming scripts' to full-fledged, scalable applications. This library rests on top of and should appear familiar to users of Boost.Asio. Currently the __cgi__, [-__scgi__ and __fcgi__] protocols are supported.
+[h3 Overview]
-[endsect]
+Boost.CGI is a library for writing CGI programs in Standard C++. It can be used to write anything from simple 'adming scripts' to full-fledged, scalable applications. This library rests on top of and should appear familiar to users of Boost.Asio. Currently the __cgi__, [-__scgi__ and __fcgi__] protocols are supported.
-[section Motivation]
+[h3 Motivation]
C++ isn't a particularly common choice for CGI programming, although it is a powerful one and can be used to produce maintainable and uncompromisingly efficient applications with any feature possible in any other language.
@@ -32,43 +32,24 @@
* C++ rarely misses out on access to new technologies: for instance, if a new RDBMS came out tomorrow, it would almost certainly ship with a C/C++ API. The same would not be true for most other languages.
+In these days of 'Web 2.0' - with web applications becoming increasingly complex and responsive (ie. asynchronous, vis-Ã -vis AJAX) all the while being required to scale boundlessly - the benefits of C++ begin to show.
-In these days of 'Web 2.0' - with web applications becoming increasingly complex and responsive (ie. asynchronous, vis-Ã -vis AJAX) all while being required to scale boundlessly - the benefits of C++ begin to appear.
-
-[endsect]
-
-[section How to use this manual]
-
-You should probably just read it in order. Simple enough, no?
-
-[section Naming Conventions]
+[h3 How to use this manual]
-[table
- [[Library 'tag'] [Underlying Protocol] [`typedef`s]]
- [[][][request][service][acceptor]]
- [[tags::cgi][CGI][cgi_request][cgi_service][cgi_acceptor]]
- [[tags::fcgi][FastCGI][fcgi_request][fcgi_service][fcgi_acceptor]]
+[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 and is simple enough to rectify.
]
-CGI -> cgi
+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.
-asynchronous CGI/aCGI acgi
+[h4 Naming Conventions]
-FastCGI -> fcgi
+[h5 Macros]
-SCGI -> scgi
-
-*_request
-
-*_acceptor
-
-*_service
-
-[endsect]
-
-
-[endsect]
+Macros are prefixed with `BOOST_CGI_*`
+[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].
[endsect]
Added: sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide.qbk
==============================================================================
--- (empty file)
+++ sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide.qbk 2007-08-16 18:46:14 EDT (Thu, 16 Aug 2007)
@@ -0,0 +1,31 @@
+[/
+ / Copyright (c) 2007 Darren Garvey
+ /
+ / Distributed under the Boost Software License, Version 1.0. (See accompanying
+ / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ /]
+
+[section:ug User's Guide]
+
+This section of the docs is for all users of the library. For details about the internals of the library see either the __sources__ or the __reference__ section.
+
+[section:gs Getting Started]
+
+This section of the documentation is probably best read before the __tutorial__. In a nutshell, this is a quick and dirty run-through of how to get and install the library [-and configure your server].
+
+[include user_guide/building.qbk]
+
+[include user_guide/server_configuration.qbk]
+
+[include user_guide/server_support.qbk]
+
+[endsect]
+
+[include user_guide/protocols.qbk]
+
+[include user_guide/tutorial.qbk]
+
+[include user_guide/examples.qbk]
+
+
+[endsect]
Modified: sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/building.qbk
==============================================================================
--- sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/building.qbk (original)
+++ sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/building.qbk 2007-08-16 18:46:14 EDT (Thu, 16 Aug 2007)
@@ -5,20 +5,47 @@
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
/]
-[section:building Building Programs]
+[section Building]
-For now the library is header-only (dependency on Boost.System?) so you can use the library by just including one of the following headers:
+Boost.CGI is a header-only library (for now), but it relies on [link __boost_system__ Boost.System], which for now must be built.
-``
-#include <boost/cgi.hpp> // include all header files
+[/h5 What you need:]
-#include <boost/cgi/cgi.hpp> // include all headers required for (sync) CGI usage
+Boost-related elements can be downloaded from the Boost download site at sourceforge, [@http://sf.net/project/showfiles.php?group_id=7586 located here].
-#include <boost/cgi/acgi.hpp> // include all headers required for aCGI usage
-
-#include <boost/cgi/fcgi.hpp> // include all headers required for FastCGI usage
-
-#include <boost/cgi/scgi.hpp> // include all headers required for SCGI usage
-``
+[note
+"invoking `bjam`" implies calling "`bjam --toolset=<your_toolset>`", where "`<your_toolset>`" is one of [@http://www.boost.org/doc/html/bbv2/reference.html#bbv2.reference.tools.compilers these]. More information can be found [link __boost_getting_started__ here] (these are general instructions for building Boost [*and] configuring `bjam`. Following these instructions will also 'tick' the first two requirements below.
+]
+
+[table What you need
+ [[Element] [Optional?] [Instructions]]
+ [
+ [Boost.Jam - `bjam`]
+ [No]
+ [Download 'boost-jam' (precomiled versions are highly recommended) and make it accessible by putting it somewhere pointed to by your system's PATH.]
+ ]
+ [
+ [Boost.System]
+ [No]
+ [1. Download the latest Boost distro, 'boost'.[br][br]
+ 2. Set the environment variable BOOST_ROOT on your system to the download location.
+ 3. Go to the directory BOOST_ROOT and invoke `bjam` (see above). This should finish without any fails.]
+ ]
+ [
+ [Documentation]
+ [Yes]
+ [These are built by going to the libs/cgi/doc directory and invoking `bjam` (see above). You can then read the docs by directing your browser to libs/cgi/index.html]
+ ]
+ [
+ [Unit tests]
+ [Yes]
+ [Tests can be run by going to the libs/cgi/test directory and invoking `bjam` (see above). Boost.CGI aims to be cross-platform, but not all platforms are available for testing. If any tests fail, problems can be reported to [link __reporting_problems__ here].]
+ ]
+ [
+ [Examples]
+ [Yes]
+ [The examples are a useful guide to uses of the library. They are also useful for testing your server configuration. They can all be found in the lib/cgi/example directory. Invoking `bjam` in the example directory should build all examples whereas invoking `bjam` in each sub-directory will build only the example contained therein.]
+ ]
+]
[endsect]
Added: sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/headers.qbk
==============================================================================
--- (empty file)
+++ sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/headers.qbk 2007-08-16 18:46:14 EDT (Thu, 16 Aug 2007)
@@ -0,0 +1,49 @@
+[/
+ / Copyright (c) 2007 Darren Garvey
+ /
+ / Distributed under the Boost Software License, Version 1.0. (See accompanying
+ / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ /]
+
+
+[section:headers Choosing the correct headers]
+
+Depending on what protocol you plan on using, you should include [*one] of the following headers:
+
+``
+#include <boost/cgi.hpp> // include header files for any protocol
+
+#include <boost/cgi/cgi.hpp> // include all headers required for (sync) CGI usage
+
+#include <boost/cgi/acgi.hpp> // include all headers required for aCGI usage
+
+#include <boost/cgi/fcgi.hpp> // include all headers required for FastCGI usage
+
+#include <boost/cgi/scgi.hpp> // include all headers required for SCGI usage
+``
+
+Including <boost/cgi.hpp> [*and] defining one of the `BOOST_CGI_IMPLICIT_*` macros is equivalent to including one of the protocol-specific headers. As such, the shortcuts `cgi::request`, `cgi::acceptor` and `cgi::service` become `typedef`s for that protocol's more explicit types.
+
+For example:
+``
+#define BOOST_CGI_IMPLICIT_SCGI 1
+#include <boost/cgi.hpp>
+cgi::request req;
+``
+Is equivalent to:
+``
+#include <boost/cgi/scgi.hpp>
+cgi::request req;
+``
+Which is equivalent to:
+``
+#include <boost/cgi.hpp> // or <boost/cgi/scgi.hpp>, here
+cgi::scgi_request req;
+``
+But:
+``
+#include <boost/cgi.hpp>
+cgi::request req; // error
+``
+
+[endsect]
Modified: sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/protocols.qbk
==============================================================================
--- sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/protocols.qbk (original)
+++ sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/protocols.qbk 2007-08-16 18:46:14 EDT (Thu, 16 Aug 2007)
@@ -30,7 +30,7 @@
The distinction between CGI and aCGI is that aCGI uses __asio__'s io_service to perform asynchronous operations - whereas CGI does not provide such operations - and is also more complicated to use. A distinction has been made with the sole purpose of lowering the entry barrier to the library and to provide a means of migrating programs over to use this library.
-[h4:differences Differences Between CGI and aCGI Programs]
+[h4 Differences Between CGI and aCGI Programs]
['See also: __hello_world__]
@@ -115,8 +115,8 @@
[section:comparison Feature Comparison]
[table
- [[ ] [Protocol ]]
- [[Feature ] [CGI] [aCGI] [FastCGI] [SCGI ]]
+ [[Feature ] [Protocol ]]
+ [[ ] [CGI] [aCGI] [FastCGI] [SCGI ]]
[[Requires io_service ] [No ] [Yes ] [Yes ] [Yes ]]
[[Is natively asynchronous] [No ] [No ] [Yes ] [Yes ]]
[[Has native error stream ] [Yes] [Yes ] [Yes ] [Shared]]
Added: sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/server_configuration.qbk
==============================================================================
--- (empty file)
+++ sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/server_configuration.qbk 2007-08-16 18:46:14 EDT (Thu, 16 Aug 2007)
@@ -0,0 +1,16 @@
+[/
+ / Copyright (c) 2007 Darren Garvey
+ /
+ / Distributed under the Boost Software License, Version 1.0. (See accompanying
+ / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ /]
+
+[section Server Configuration]
+
+[note
+Setting up server's for use with the library can be tricky, especially when using FastCGI. Concise links to guides on other sites is probably the way this section will go, perhaps with some basic outlines of ways to test it.
+]
+
+[*Under construction]
+
+[endsect]
Added: sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/server_support.qbk
==============================================================================
--- (empty file)
+++ sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/server_support.qbk 2007-08-16 18:46:14 EDT (Thu, 16 Aug 2007)
@@ -0,0 +1,16 @@
+[/
+ / Copyright (c) 2007 Darren Garvey
+ /
+ / Distributed under the Boost Software License, Version 1.0. (See accompanying
+ / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ /]
+
+[/def __fastcgi_support__]
+
+[section Server Support]
+
+This is an incomplete table of what server's there are and what level of support they provide. Any further (verifiable) information that can be provided would be helpful.
+
+[*Alternative] - Just link to a page from Wikipedia with this information.
+
+[endsect]
Modified: sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/tutorial.qbk
==============================================================================
--- sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/tutorial.qbk (original)
+++ sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/tutorial.qbk 2007-08-16 18:46:14 EDT (Thu, 16 Aug 2007)
@@ -5,32 +5,25 @@
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
/]
-[section Tutorial]
-
-[tip Have you read __reading_the_docs__?]
+[section:tut Tutorial]
Except for when using CGI synchronously, a typical program will have two fundamental parts:
[/handling a client request generally involves the following stages:]
-[variablelist
- [
- [Gathering requests]
- [
- [link __accepting__ Accepting] requests;
- [link __loading__ Loading] and parsing request meta-data;
- ]
- ]
- [
- [Handling requests]
- [
- Using the [link __meta_data__ meta-data];
- [link __writing__ Writing] a reply;
- [link boost.cgi.user_guide.handling_requests.wrapping_up Wrapping up];
- ]
- ]
-] [/variablelist]
+[h4 Gathering requests]
+
+* [link __accepting__ Accepting] requests;
+
+* [link __loading__ Loading] and parsing request meta-data;
+
+[h4 Handling requests]
+
+* Using the [link __meta_data__ meta-data];
+
+* [link __writing__ Writing] a reply;
+* [link boost.cgi.ug.handling_requests.wrapping_up Wrapping up];
[include tutorial/accepting.qbk]
Modified: sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/tutorial/accepting.qbk
==============================================================================
--- sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/tutorial/accepting.qbk (original)
+++ sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/tutorial/accepting.qbk 2007-08-16 18:46:14 EDT (Thu, 16 Aug 2007)
@@ -7,13 +7,13 @@
[section:accepting Accepting Requests]
-A `basic_request_acceptor<>` is responsible for accepting requests. There are __common_typedef__s for ease of use, as with `basic_request<>`s. A program written for SCGI or FastCGI will generally have one acceptor running in a loop. A `cgi_request` cannot be used with an acceptor, but acgi_request`s will work fine: ie. only the first accept will succeed.
+A `basic_request_acceptor<>` is responsible for accepting requests. There are [link __naming_conventions__ common typedefs] for ease of use, as with `basic_request<>`s. A program written for SCGI or FastCGI will generally have one acceptor running in a loop. A `cgi_request` cannot be used with an acceptor, but an `acgi_request` will work fine: ie. only the first accept will succeed.
Accepting requests is considered distinct to the [link __loading__ loading] stage for several reasons, the most significant of which is to allow for multiplexing protocols like FastCGI work with the library.
-All you need do is create an `*_acceptor` by passing an instance of a __ProtocolService__ to its constructor. The following member functions are available:
+All you need do is create an `*_acceptor` by passing an instance of a __ProtocolService__ to its constructor. The following member functions are available (take xcgi to imply one of fcgi/scgi/acgi):
-[table [/xcgi_acceptor member functions]
+[table
[[Function signature] [Purpose]]
[
[`void accept(xcgi_request& empty_request)`]
Modified: sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/tutorial/loading.qbk
==============================================================================
--- sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/tutorial/loading.qbk (original)
+++ sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/tutorial/loading.qbk 2007-08-16 18:46:14 EDT (Thu, 16 Aug 2007)
@@ -13,12 +13,12 @@
[[Function signature] [Purpose]]
[
[`void basic_request<>::load(bool parse_stdin = true)`]
- [Loads the request meta-data into internal `cgi::map`s. If `parse_stdin == true`, which it is by default, CGI POST data is also read and parsed. If an error occurs, an exception is thrown.]
+ [Loads the request meta-data into internal `cgi::map`s.[br][br]If `parse_stdin == true`, which it is by default, CGI POST data is also read and parsed. If an error occurs, an exception is thrown.]
]
[
[`boost::system::error_code&
basic_request<>::load(boost::system::error_code& ec, bool parse_stdin = true)`]
- [Loads the request meta-data into internal `cgi::map`s. If `parse_stdin == true`, which it is by default, CGI POST data is also read and parsed. If an error occurs, ec is set to the value of the error such that `!ec == false`.]
+ [Loads the request meta-data into internal `cgi::map`s.[br][br]If `parse_stdin == true`, which it is by default, CGI POST data is also read and parsed. If an error occurs, ec is set to the value of the error such that `!ec == false`.]
]
[
[`void basic_request<>::async_load(bool parse_stdin, Handler handler)`]
@@ -26,7 +26,7 @@
]
] [/table]
-What the call does is aquire the request environment data as necessary and parse the CGI GET and HTTP_COOKIE variables. Also, if `parse_stdin == true` and the request method is POST, the CGI POST data will be read and parsed.
+What the call does is aquire the request environment data as necessary and parse the CGI __GET__ and `"HTTP_COOKIE"` variables. Also, if `parse_stdin == true` and the request method is POST, the CGI __POST__ data will be read and parsed.
[h5 CGI example]
Modified: sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/tutorial/meta_data.qbk
==============================================================================
--- sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/tutorial/meta_data.qbk (original)
+++ sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/tutorial/meta_data.qbk 2007-08-16 18:46:14 EDT (Thu, 16 Aug 2007)
@@ -11,25 +11,40 @@
A request [*must] be [link __loading__ loaded] before the meta-data can be accessed. The ['only] exception to this rule is calling `meta_env()` on CGI and aCGI request objects. These are (essentially) equivalent to a call to `::getenv()` and will always work. However, exploit this 'feature' cautiously as it will render a program unsuitable for use with the more scalable protocols on offer.
]
-There are five member functions of `basic_request<>` that provide access to the meta-data associated to that request. These are:
-
+There are six member functions of `basic_request<>` that provide access to the meta-data associated to that request.
[table Meta-data accessor functions
[[Function signature] [Purpose]]
- [[`std::string meta_env(const std::string&)`] [Takes the name of the environment variable wanted and returns the value associated with it.]]
- [[`std::string meta_get(const std::string&)`][Takes the name of the __GET__ variable and returns the value associated with it (if any).]]
- [[`std::string meta_post(const std::string&, bool greedy = true)`][Takes the name of the __POST__ variable and returns the value associated with it (if any). If `greedy == true` - which it is by default - then more data is read from the request if required until all of the POST data has been read.]]
- [[`std::string meta_form(const std::string&, bool greedy = true)`][Takes the name of either a __GET__ or __POST__ variable and returns the value associated with it (if any). If `greedy == true` - which it is by default - then more data is read from the request as required until all of the POST data has been read.]]
- [[`std::string meta_cookie(const std::string& name)`][Takes the name of the cookie variable and returns the value associated with it (if any).]]
- [[`std::string meta_var(const std::string& name, bool greedy = true)`][Takes the name of [*any] meta-variable and returns the value associated with it (if any). If `greedy == true` - which it is by default - then more data is read from the request if required until either the requested variable is found or all of the POST data has been read, which ever comes first.
-]]
+ [
+ [`std::string meta_env(const std::string&)`]
+ [Takes the name of the environment variable wanted and returns the value associated with it.]
+ ]
+ [
+ [`std::string meta_get(const std::string&)`]
+ [Takes the name of the __GET__ variable and returns the value associated with it (if any).]
+ ]
+ [
+ [`std::string meta_post(const std::string&, bool greedy = true)`]
+ [Takes the name of a __POST__ variable and returns the value associated with it (if any).[br][br] If `greedy == true` - which it is by default - then more data is read from the request if required until all of the POST data has been read.]
+ ]
+ [
+ [`std::string meta_form(const std::string&, bool greedy = true)`]
+ [Takes the name of either a __GET__ or __POST__ variable and returns the value associated with it (if any). Note that this will only search the type referred to by the environment variable `"REQUEST_METHOD"`, so it is generally safe to use.[br][br]If `greedy == true` - which it is by default - then more data is read from the request as required until all of the POST data has been read.]
+ ]
+ [
+ [`std::string meta_cookie(const std::string& name)`]
+ [Takes the name of the cookie variable and returns the value associated with it (if any).]
+ ]
+ [
+ [`std::string meta_var(const std::string& name, bool greedy = true)`]
+ [Takes the name of [*any] meta-variable and returns the value associated with it (if any).[br][br] If `greedy == true` - which it is by default - then more data is read from the request if required until either the requested variable is found or all of the POST data has been read, which ever comes first.]
+ ]
]
-[/ should this return a `std::pair<std::string, cgi::meta_type>` instead, where a `cgi::meta_type` is one of `get`, `post`, `env`, or `cookie`?]
-
[warning
-It is generally accepted that a CGI program should pay attention to where meta-data has come from.[footnote citations w.r.t. XSS and GET/POST/COOKIE ambiguities] In other words, since `meta_var` removes such distinctions, its use should be limited to places where origin of the variable doesn't matter. For example, a language setting (like `"hl=en"`, as Google uses) could come from anywhere and doing so is not an issue.
+It is generally accepted that a CGI program should pay attention to where meta-data has come from.[footnote citations w.r.t. XSS and GET/POST/HTTP_COOKIE ambiguities] In other words, since `meta_var` removes such distinctions, its use should be limited to places where the source of the variable doesn't matter. For example, a language toggle (like `"hl=en"`, as Google uses) could come from anywhere and doing so is not an issue.
]
+[/ should this return a `std::pair<std::string, cgi::meta_type>` instead, where a `cgi::meta_type` is one of `get`, `post`, `env`, or `cookie`?]
[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