[magi]

3 files changed, 52 insertions, 25 deletions

diff --git a/Makefile b/Makefile
index d57c2d1..db1fefd 100644
--- a/Makefile
+++ b/Makefile
@@ -1,6 +1,6 @@
 # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
 #     Compilation Options
-# Debug mode (uncoment to be able to debug the library via gdb):
+# Debug mode (allowing to debug the library via gdb):
 # DEBUG   = yes
 # Specify your favourite C compiler here (e.g. tcc):
 CC      = gcc
@@ -27,7 +27,7 @@ OBJ     = $(SRC:.c=.o)
 
 # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
 #     Targets
-# 'make' will produce library by default:
+# 'make' produces library by default:
 default: $(LIB)
 
 # Cleaning means removing everything automatically produced:
diff --git a/examples/Makefile b/examples/Makefile
index d93176b..2f57b1e 100644
--- a/examples/Makefile
+++ b/examples/Makefile
@@ -1,29 +1,48 @@
-# Uncomment following to enable debug mode:
+# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
+#     Compilation Options
+# Debug mode (allowing to debug the examples via gdb):
 # DEBUG    = yes
-
+# Specify your favourite C compiler here (e.g. tcc):
 CC       = gcc
+
+
+# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
+#     Preparations
 EXAMPLES = append cookie upload echo
 
+# Compile under the most strict conditions:
 CFLAGS   = -xc -ansi -pedantic -Wall
+# Debug and optimisation are not compatible:
 ifeq '$(DEBUG)' 'yes'
 CFLAGS  += -g -O0
 else
 CFLAGS  += -O3
 endif
 
+# Including magi library headers and setting linker to use it:
 INCLUDE  = -I ../src
 LFLAGS   = -L.. -lmagi
 
+# Specification of library file to produce it, if not provided:
 MAGI     = ../libmagi.a
 
 
+# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
+#     Targets
+# 'make' produces all examples by default:
 default: $(EXAMPLES)
 
-$(MAGI):
-	cd ..; $(MAKE)
+# Cleaning means removing everything automatically produced:
+clean:
+	rm -f $(EXAMPLES)
+
 
+# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
+#     Compilation
+# Compile executables from corresponding sources and library:
 %: %.c $(MAGI)
 	$(CC) $(CFLAGS) $(INCLUDE) $< $(LFLAGS) -o $@
 
-clean:
-	rm -f $(EXAMPLES)
+# Run make for library to produce it:
+$(MAGI):
+	cd ..; $(MAKE)
diff --git a/readme b/readme
index 8cc3b8b..59dfc25 100644
--- a/readme
+++ b/readme
@@ -2,8 +2,8 @@
 Magi Library (libmagi) implements Gateway Interfaces, namely CGI and FastCGI.
 
     Overview
-Magi is free and open-source software: legal info is in the 'license' file.
-It is written in ANSI C, without any dependecies, except for C standard
+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
@@ -21,22 +21,30 @@ Running 'make' in the 'examples' directory produces 'append', 'cookie',
 corresponding source files.
 
     Usage
-Magi main purpose is to analyse request and provide it in 'struct magi_request'
-variable.  It is described in 'src/request.h'; to setup defaults before actual
-processing run 'magi_request_setup'.  Next step is to analyse post-unrelated
-part of request via 'magi_request_cgi'.  Since post part can be realy big,
-it is generally useful to constrain its analysis biased on the rest of request.
-Post part analyse is done via 'magi_request_resume_cgi'.  You can destroy
-request structure via 'magi_request_destroy'.
+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'.
 
-Also magi provide output capabilities via 'struct magi_response'.
-Similary to request, 'magi_response_setup' is initialisation of response with
-defaults.  Content type need to be specified for response, to set it run
-'magi_response_content_type'.  You can set cookie with 'magi_response_cookie',
-as well as discard them with 'magi_response_cookie_discard'.  You can set HTTP
-headers with 'magi_response_http'.  For filling response body use 
-'magi_response_add' and 'magi_response_add_format'.  To send response call
-'magi_response_cgi'.  Desctruction is provided in 'magi_response_destroy'.
+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.