Merge branch 'master' into test

1 files changed, 50 insertions, 0 deletions

diff --git a/readme b/readme
new file mode 100644
index 0000000..59dfc25
--- /dev/null
+++ b/readme
@@ -0,0 +1,50 @@
+    Description
+Magi Library (libmagi) implements Gateway Interfaces, namely CGI and FastCGI.
+
+    Overview
+Magi are free and open-source software: legal info is in the 'license' file.
+They are written in ANSI C, without any dependecies, except for C standard
+library.  All source and header files are located in the 'src' directory.
+Files with 'inner' part in their names are not intended for external use.
+Since filenames in the project are short and simple consider placing
+header files in subdirectory 'magi' of your include.
+
+    Compiling
+Compilation and its options are described in the 'Makefile'.
+Running 'make' produces 'libmagi.a' file, which is precompiled library itself,
+ready to be statically linked into your project.
+
+    Examples
+Compilation and its options are described in the local 'examples/Makefile'.
+Running 'make' in the 'examples' directory produces 'append', 'cookie',
+'upload', and 'echo' CGI executables.  Descriptions and details are in
+corresponding source files.
+
+    Usage
+magi_request analyses incoming request, general workflow is to:
+1. Prepare request for analysis, setup defaults via 'magi_request_setup';
+2. Process non-post part of the CGI request via 'magi_request_cgi';
+   (The division of post and non-post analysis comes from the fact that
+    post body can be really huge, so you probably will want to specify
+    some constraints on it, based on non-post info.  For example session id
+    from non-post part allowes some users (e.g. admins) to load more in post.)
+3. Process post part of the CGI request via 'magi_request_resume_cgi';
+4. Now you have the full request analysed, so do your work;
+5. And finally, free memory via 'magi_request_destroy'.
+For more see 'src/request.h'.
+
+magi_response provides output capabilities.  You can form the response with
+'magi_response_setup' used to setup defaults, and the following functions to
+fill in your data ('...' means 'magi_response_'):
+  ...content_type: set Content Type (by default XHTML);
+        ...cookie: set HTTP Cookie;
+...cookie_discard: discard HTTP Cookie;
+          ...http: setup arbitarary HTTP header;
+           ...add: add something to the body;
+    ...add_format: add comething to the body, using format (similar to printf);
+Outputting itself can be done with 'magi_response_cgi'.
+To correctly free all occupied memory call 'magi_response_destroy'.
+For more see 'src/response.h'.
+
+    Motivation
+Web must be fun.