docs update

README.textile

@@ -99,6 +99,7 @@ one terminal and start playing http pubsub:
 
 h1(#examples). Some Examples <a name="examples" href="#">&nbsp;</a>
 
+* "Curl examples":curl
 * "Forever (hidden) iFrame":forever_iframe
 * "Event Source":event_source
 * "WebSocket":websocket
@@ -111,6 +112,16 @@ h1(#FAQ). FAQ <a names="faq" href="#">&nbsp;</a>
 
 Doubts?! Check the "FAQ":wiki.
 
+h1(#bug_report). Bug report <a name="bug_report" href="#">&nbsp;</a>
+
+To report a bug, please provide the following information when applicable
+
+# Which push stream module version is been used (commit sha1)?
+# Which nginx version is been used?
+# Nginx configuration in use
+# "nginx -V" command outuput
+# Core dump indicating a failure on the module code. Check "here":nginx_debugging how to produce one.
+# Step by step description to reproduce the error.
 
 h1(#who). Who is using the module? <a names="faq" href="#">&nbsp;</a>
 
@@ -226,6 +237,7 @@ h1(#contributors). Contributors
 [repository]https://github.com/wandenberg/nginx-push-stream-module
 [contributors]https://github.com/wandenberg/nginx-push-stream-module/contributors
 [changelog]CHANGELOG.textile
+[curl]docs/examples/curl.textile#curl
 [forever_iframe]docs/examples/forever_iframe.textile#forever_iframe
 [event_source]docs/examples/event_source.textile#event_source
 [websocket]docs/examples/websocket.textile#websocket
@@ -267,3 +279,4 @@ h1(#contributors). Contributors
 [push_stream_allowed_origins]docs/directives/subscribers.textile#push_stream_allowed_origins
 [push_stream_websocket_allow_publish]docs/directives/subscribers.textile#push_stream_websocket_allow_publish
 [wiki]https://github.com/wandenberg/nginx-push-stream-module/wiki/_pages
+[nginx_debugging]http://wiki.nginx.org/Debugging

docs/examples/curl.textile

+h1(#curl). Curl examples <a name="curl" href="#">&nbsp;</a>
+
+Some commands to explain how the module protocol is implemented, and help to do your own client ;)
+
+Configure your server like suggested bellow. You should complete this configuration with other directives according to the target application.
+
+*Server:*
+
+<pre>
+    location /channels-stats {
+        # activate channels statistics mode for this location
+        push_stream_channels_statistics;
+
+        # query string based channel id
+        push_stream_channels_path               $arg_id;
+    }
+
+    location /pub {
+        # activate publisher (admin) mode for this location
+        push_stream_publisher admin;
+
+        # query string based channel id
+        push_stream_channels_path               $arg_id;
+    }
+
+    location ~ /sub/(.*) {
+        # activate long-polling mode for this location
+        push_stream_subscriber      long-polling;
+
+        # positional channel path
+        push_stream_channels_path         $1;
+
+        # message template
+        push_stream_message_template                "{\"id\":~id~,\"channel\":\"~channel~\",\"text\":\"~text~\"}";
+
+        # connection timeout
+        push_stream_longpolling_connection_ttl        30s;
+    }
+</pre>
+
+
+h2(#common_operations). Common operations
+
+<pre>
+# Subscribe to a channel
+curl -s -v --no-buffer 'http://localhost/sub/my_channel_1'
+curl -s -v --no-buffer 'http://localhost/sub/your_channel_1'
+curl -s -v --no-buffer 'http://localhost/sub/your_channel_2'
+
+# Publish messages
+curl -s -v -X POST 'http://localhost/pub?id=my_channel_1' -d 'Hello World!'
+curl -s -v -X POST 'http://localhost/pub?id=your_channel_1' -d 'Hi everybody!'
+curl -s -v -X POST 'http://localhost/pub?id=your_channel_2' -d 'Goodbye!'
+
+# Channels Stats for publisher (json format)
+curl -s -v 'http://localhost/pub?id=my_channel_1'
+
+# All Channels Stats summarized (json format)
+curl -s -v 'http://localhost/channels-stats'
+
+# All Channels Stats detailed (json format)
+curl -s -v 'http://localhost/channels-stats?id=ALL'
+
+# Prefixed Channels Stats detailed (json format)
+curl -s -v 'http://localhost/channels-stats?id=your_channel_*'
+
+# Channels Stats (json format)
+curl -s -v 'http://localhost/channels-stats?id=my_channel_1'
+
+# Delete Channels
+curl -s -v -X DELETE 'http://localhost/pub?id=my_channel_1'
+</pre>
+
+
+h2(#getting_old_messages). Getting old messages
+
+To get old messages you can use a backtrack, an event id or a time in the past to specify a start point.
+All control methods use some HTTP headers by default, except for backtrack.
+But they can use other methods also, like URL parameters.
+
+To deliver old messages it's necessary to properly configure the directives "push_stream_store_messages", "push_stream_max_messages_stored_per_channel" and "push_stream_message_ttl".
+
+
+*Using backtrack:*
+
+<pre>
+# To get the last 4 messages from channelA, the last 2 messages from channelC and no old messages from channelB
+curl -s -v --no-buffer 'http://localhost/sub/channelA.b4/channelB/channelC.b2'
+</pre>
+
+
+*Using time in the past:*
+
+When a message is published it receives a time and a tag value.
+The tag is used to untie messages published on the same second.
+These values are available to the message template using the ==~time~== and ==~tag~== patterns, and also on headers "Last-Modified" and "Etag" when on long-polling mode.
+
+<pre>
+# publish a message on t1
+curl -s -v -X POST 'http://localhost/pub?id=channelA' -d '1'
+# publish another message on t2
+curl -s -v -X POST 'http://localhost/pub?id=channelA' -d '2'
+# publish another message on t2
+curl -s -v -X POST 'http://localhost/pub?id=channelA' -d '3'
+# publish another message on t3
+curl -s -v -X POST 'http://localhost/pub?id=channelA' -d '4'
+
+# Get the messages published after the t2 time, tag 1
+curl -s -v --no-buffer 'http://localhost/sub/channelA' -H 'If-Modified-Since: t2' -H 'If-None-Match: 1'
+
+# t2, must be on the format "%a, %d %b %Y %T %Z", for instance "Thu, 1 Jan 1970 00:00:00 GMT"
+# this subscriber will receive the messages "3" and "4"
+</pre>
+
+*Using time in the past (not using headers):*
+
+Adding the directives "push_stream_last_received_message_time", "push_stream_last_received_message_tag" to subscriber location,
+is possible to set the values for getting old messages using other methods, like URL parameters or a piece of the path.
+
+modified server:
+
+<pre>
+    location ~ /sub/(.*) {
+        push_stream_subscriber      long-polling;
+        push_stream_channels_path         $1;
+
+        push_stream_last_received_message_time $arg_time;
+        push_stream_last_received_message_tag  $arg_tag;
+
+        push_stream_message_template           "{\"id\":~id~,\"channel\":\"~channel~\",\"text\":\"~text~\", \"time\":\"~time~\", \"tag\":\"~tag~\"}";
+
+        push_stream_longpolling_connection_ttl        30s;
+    }
+</pre>
+
+using the same published messages on the above example:
+
+<pre>
+# Get the messages published after the t2 time, tag 2
+curl -s -v --no-buffer 'http://localhost/sub/channelA?tag=2&time=t2'
+
+# t2, must be on the format "%a, %d %b %Y %T %Z", for instance "Thu, 1 Jan 1970 00:00:00 GMT"
+# this subscriber will receive only the message "4"
+</pre>
+
+
+*Using EventId:*
+
+When a message is published with an Event-Id header this value can be used as a start point to get old messages.
+It's available to the message template using the ==~event-id~== pattern.
+
+<pre>
+
+curl -s -v -X POST 'http://localhost/pub?id=channelA' -d '1'
+curl -s -v -X POST 'http://localhost/pub?id=channelA' -d '2' -H 'Event-Id: some_special_event'
+curl -s -v -X POST 'http://localhost/pub?id=channelA' -d '3'
+curl -s -v -X POST 'http://localhost/pub?id=channelA' -d '4'
+
+# Get the messages published after that event, in this example messages '3' and '4'
+curl -s -v --no-buffer 'http://localhost/sub/channelA' -H 'Last-Event-Id: some_special_event'
+</pre>
+
+*Using EventId (not using headers):*
+
+Adding the directive "push_stream_last_event_id" to subscriber location,
+is possible to set the value for getting old messages using other methods, like URL parameters or a piece of the path.
+
+modified server:
+
+<pre>
+    location ~ /sub/(.*) {
+        push_stream_subscriber      long-polling;
+        push_stream_channels_path         $1;
+
+        push_stream_last_event_id $arg_last_id;
+
+        push_stream_message_template           "{\"id\":~id~,\"channel\":\"~channel~\",\"text\":\"~text~\", \"event\":\"~event-id~\"}";
+
+        push_stream_longpolling_connection_ttl        30s;
+    }
+</pre>
+
+using the same published messages on the above example:
+
+<pre>
+# Get the messages published after the event 'some_special_event'
+curl -s -v --no-buffer 'http://localhost/sub/channelA?last_id=some_special_event'
+
+# this subscriber will receive the messages '3' and '4'
+</pre>

docs/examples/event_source.textile

@@ -3,7 +3,7 @@ h1(#event_source). Event Source <a name="event_source" href="#">&nbsp;</a>
 Using EventSource to receive the messages.
 *This example uses the PushStream class present in _misc/js/pushstream.js_ file, copy it to your server htdocs.*
 
-Configure your server like suggested bellow. You should complete this configuration with other directives according with target application.
+Configure your server like suggested bellow. You should complete this configuration with other directives according to the target application.
 Create a html page with the content on **Client** part, access it from browser and try with the command *curl http://localhost/pub?id=ch1 -d =="Some Text"==* .
 
 *Server:*

docs/examples/forever_iframe.textile

@@ -3,7 +3,7 @@ h1(#forever_iframe). Forever Iframe <a name="forever_iframe" href="#">&nbsp;</a>
 Using an invisible iFrame on the page to receive the messages and pass them to main page.
 *This example uses the PushStream class present in _misc/js/pushstream.js_ file, copy it to your server htdocs.*
 
-Configure your server like suggested bellow. You should complete this configuration with other directives according with target application.
+Configure your server like suggested bellow. You should complete this configuration with other directives according to the target application.
 Create a html page with the content on **Client** part, access it from browser and try with the command *curl http://localhost/pub?id=ch1 -d =="Some Text"==* .
 
 *Server:*

docs/examples/long_polling.textile

@@ -3,7 +3,7 @@ h1(#long_polling). Long Polling <a name="long_polling" href="#">&nbsp;</a>
 Using PushStream to receive the messages through long polling technique.
 *This example uses the PushStream class present in _misc/js/pushstream.js_ file, copy it to your server htdocs.*
 
-Configure your server like suggested bellow. You should complete this configuration with other directives according with target application.
+Configure your server like suggested bellow. You should complete this configuration with other directives according to the target application.
 Create a html page with the content on **Client** part, access it from browser and try with the command *curl http://localhost/pub?id=ch1 -d =="Some Text"==* .
 
 *Server:*
@@ -214,7 +214,7 @@ h1(#jsonp). JSONP <a name="jsonp" href="#">&nbsp;</a>
 Using PushStream to receive the messages through JSONP technique.
 *This example uses the PushStream class present in _misc/js/pushstream.js_ file, copy it to your server htdocs.*
 
-Configure your server like suggested bellow. You should complete this configuration with other directives according with target application.
+Configure your server like suggested bellow. You should complete this configuration with other directives according to the target application.
 Create a html page with the content on **Client** part, access it from browser and try with the command *curl http://localhost/pub?id=ch1 -d "Some Text"*.
 
 _The configuration in the example is the same used on long polling, just forcing the use of JSONP, this is automatic when the domains are different_

docs/examples/websocket.textile

@@ -3,7 +3,7 @@ h1(#websocket). WebSocket <a name="websocket" href="#">&nbsp;</a>
 Using WebSocket to receive the messages.
 *This example uses the PushStream class present in _misc/js/pushstream.js_ file, copy it to your server htdocs.*
 
-Configure your server like suggested bellow. You should complete this configuration with other directives according with target application.
+Configure your server like suggested bellow. You should complete this configuration with other directives according to the target application.
 Create a html page with the content on **Client** part, access it from browser and try with the command *curl http://localhost/pub?id=ch1 -d =="Some Text"==* .
 
 *Server:*

misc/Rakefile

@@ -120,7 +120,7 @@ begin
   task :watch do
     puts "watching for changes on textile files"
     Dir.chdir(project_dir) do
-      FileWatcher.new(["*.textile"]).watch do |file, event|
+      FileWatcher.new(["**/*.textile"]).watch do |file, event|
         if(event != :delete)
           generate_preview_for(file, project_dir, base_path)
         end