[elpa] 109/119: doc for new content/transfer encoding helpers

[Eric Schulte]

eschulte pushed a commit to branch master
in repository elpa.

commit 11e50b506e54d7190e4e9bb547e0a35f54f3cf7e
Author: Eric Schulte <address@hidden>
Date:   Wed Feb 12 17:08:20 2014 -0700

    doc for new content/transfer encoding helpers
---
 NOTES                                     |    4 +-
 doc/web-server.texi                       |   77 ++++++++++++++++++++++++++--
 examples/016-content-encoding-gzip.el     |    2 +-
 examples/017-transfer-encoding-chunked.el |    2 +-
 web-server.el                             |   13 ++++-
 5 files changed, 86 insertions(+), 12 deletions(-)

diff --git a/NOTES b/NOTES
index 00febfb..e086b93 100644
--- a/NOTES
+++ b/NOTES
@@ -4,8 +4,8 @@
 #+Options: ^:{}
 
 * Notes
-* Tasks [17/21]
-** TODO Content and Transfer encodings
+* Tasks [18/21]
+** DONE Content and Transfer encodings
 - Content and Transfer encoding values
   http://www.iana.org/assignments/http-parameters/http-parameters.xhtml
 - http://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.6
diff --git a/doc/web-server.texi b/doc/web-server.texi
index e86ff93..0ae094b 100644
--- a/doc/web-server.texi
+++ b/doc/web-server.texi
@@ -191,6 +191,8 @@ These examples demonstrate usage.
 * Org-mode Export::             Export files to HTML and Tex
 * File Upload::                 Upload files and return their sha1sum
 * Web Socket::                  Web socket echo server
+* Gzipped Transfer Encoding::   Gzip content encoding
+* Chunked Transfer Encoding::   Chunked transfer encoding
 @end menu
 
 @node Hello World, Hello World UTF8, Usage Examples, Usage Examples
@@ -313,7 +315,7 @@ $ sha1sum /usr/share/emacs/24.3/etc/COPYING
 8624bcdae55baeef00cd11d5dfcfa60f68710a02  /usr/share/emacs/24.3/etc/COPYING
 @end example
 
address@hidden Web Socket, Function Index, File Upload, Usage Examples
address@hidden Web Socket, Chunked Transfer Encoding, File Upload, Usage 
Examples
 @section Web Socket
 
 Example demonstrating the use of web sockets for full duplex
@@ -340,6 +342,28 @@ the @code{:keep-alive} keyword, as demonstrated in the 
example.
 
 @verbatiminclude ../examples/009-web-socket.el
 
address@hidden Gzipped Transfer Encoding, Chunked Transfer Encoding, Web 
Socket, Usage Examples
address@hidden Gzipped Transfer Encoding
+
+HTTP Responses may be compressed by setting the ``gzip'' (or
+``compress'' or ``deflate'') content- or transfer-encoding HTTP
+headers in @code{ws-response-header}.  Any further data sent to the
+process using @code{ws-send} will automatically be appropriately
+compressed.
+
address@hidden ../examples/016-content-encoding-gzip.el
+
address@hidden Chunked Transfer Encoding, Function Index, Web Socket, Usage 
Examples
address@hidden Chunked Transfer Encoding
+
+Similarly, HTTP Responses may be sent using the ``chunked'' transfer
+encoding by passing the appropriate HTTP header to
address@hidden  Any further data sent to the process using
address@hidden will automatically be appropriately encoded for chunked
+transfer.
+
address@hidden ../examples/017-transfer-encoding-chunked.el
+
 @node Function Index, Copying, Usage Examples, Top
 @chapter Function Index
 @cindex function index
@@ -407,11 +431,13 @@ associated with responding to HTTP requests.
 
 @anchor{ws-response-header}
 @cindex content type
address@hidden ws-response-header process code &rest header
-Send the headers required to start an HTTP response to @code{process}.
address@hidden should be a @code{ws-request} @code{process} of an
-active request.  For example start a standard 200 ``OK'' HTML response
-with the following.
address@hidden ws-response-header process code &rest headers
+Send the headers required to start an HTTP response to @code{proc}.
address@hidden should be a @code{ws-request} @code{proc} of an active
+request.
+
+For example start a standard 200 ``OK'' HTML response with the
+following.
 
 @example
 (ws-response-header process 200 '("Content-type" . "text/html"))
@@ -425,6 +451,24 @@ encoded response with the following.
             '("Content-type" . "text/plain; charset=utf-8"))
 @end example
 
+Additionally, when ``Content-Encoding'' or ``Transfer-Encoding''
+headers are supplied any subsequent data written to @code{proc} using
address@hidden will be encoded appropriately including sending the
+appropriate data upon the end of transmission for chunked transfer
+encoding.
+
+For example with the header @code{("Content-Encoding" . "gzip")}, any
+data subsequently written to @code{proc} using @code{ws-send} will be
+compressed using the command specified in @code{ws-gzip-cmd}.  See
address@hidden Transfer Encoding} and @ref{Chunked Transfer Encoding}
+for more complete examples.
+
address@hidden defun
+
address@hidden
address@hidden ws-send proc string
+Send @code{string} to process @code{proc}.  If any Content or Transfer
+encodings are in use, apply them to @code{string} before sending.
 @end defun
 
 @anchor{ws-send-500}
@@ -515,6 +559,27 @@ socket messages received from the client.
 @end example
 @end defun
 
address@hidden Customization Variables
+The following variables may be changed to control the behavior of the
+web server.  Specifically the @code{ws-*-cmd} variables specify the
+command lines used to compress data according to content and or
+transfer encoding HTTP headers passed to @ref{ws-response-header}.
+
address@hidden
address@hidden ws-compress-cmd
+Command used for the ``compress'' Content or Transfer coding.
address@hidden defvar
+
address@hidden
address@hidden ws-deflate-cmd
+Command used for the ``deflate'' Content or Transfer coding.
address@hidden defvar
+
address@hidden
address@hidden ws-gzip-cmd
+Command used for the ``gzip'' Content or Transfer coding.
address@hidden defvar
+
 @node Copying, GNU Free Documentation License, Function Index, Top
 @appendix GNU GENERAL PUBLIC LICENSE
 @include gpl.texi
diff --git a/examples/016-content-encoding-gzip.el 
b/examples/016-content-encoding-gzip.el
index 7a56eb1..e50bf58 100644
--- a/examples/016-content-encoding-gzip.el
+++ b/examples/016-content-encoding-gzip.el
@@ -1,4 +1,4 @@
-;;; content-encoding-gzip.el -- manual application of gzip content encoding
+;;; content-encoding-gzip.el -- gzip content encoding
 (ws-start
  (lambda (request)
    (with-slots (process headers) request
diff --git a/examples/017-transfer-encoding-chunked.el 
b/examples/017-transfer-encoding-chunked.el
index 1ec92ed..3217ccf 100644
--- a/examples/017-transfer-encoding-chunked.el
+++ b/examples/017-transfer-encoding-chunked.el
@@ -1,4 +1,4 @@
-;;; transfer-encoding-chunked.el -- manual chunked transfer encoding
+;;; transfer-encoding-chunked.el -- chunked transfer encoding
 (ws-start
  (lambda (request)
    (let ((s "
diff --git a/web-server.el b/web-server.el
index 4e885f0..1943f95 100644
--- a/web-server.el
+++ b/web-server.el
@@ -537,8 +537,17 @@ See RFC6455."
 ;;; Convenience functions to write responses
 (defun ws-response-header (proc code &rest headers)
   "Send the headers for an HTTP response to PROC.
-Currently CODE should be an HTTP status code, see
-`ws-status-codes' for a list of known codes."
+CODE should be an HTTP status code, see `ws-status-codes' for a
+list of known codes.
+
+When \"Content-Encoding\" or \"Transfer-Encoding\" headers are
+supplied any subsequent data written to PROC using `ws-send' will
+be encoded appropriately including sending the appropriate data
+upon the end of transmission for chunked transfer encoding.
+
+For example with the header `(\"Content-Encoding\" . \"gzip\")',
+any data subsequently written to PROC using `ws-send' will be
+compressed using the command specified in `ws-gzip-cmd'."
   ;; update process to reflect any Content or Transfer encodings
   (let ((content  (cdr (assoc "Content-Encoding" headers)))
         (transfer (cdr (assoc "Transfer-Encoding" headers))))