helm/DEVEL/pxp/netstring/doc/README.xml

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!DOCTYPE readme SYSTEM "readme.dtd" [
   3
   4 <!ENTITY % common SYSTEM "common.xml">
   5 %common;
   6
   7 <!-- Special HTML config: -->
   8 <!ENTITY % readme:html:up '<a href="../..">up</a>'>
   9
  10 <!ENTITY % config SYSTEM "config.xml">
  11 %config;
  12
  13 ]>
  14
  15 <readme title="README - Netstring, string processing functions for the net">
  16   <sect1>
  17     <title>Abstract</title>
  18     <p>
  19 <em>Netstring</em> is a collection of string processing functions that are
  20 useful in conjunction with Internet messages and protocols. In particular,
  21 it contains functions for the following purposes:</p>
  22
  23 <ul>
  24       <li><p>Parsing MIME messages</p>
  25       </li>
  26       <li><p>Several encoding/decoding functions (Base 64, Quoted Printable, Q, URL-encoding)</p>
  27       </li>
  28       <li><p>A new implementation of the CGI interface that allows users to upload files</p>
  29       </li>
  30       <li><p>A simple HTML parser</p>
  31       </li>
  32       <li><p>URL parsing, printing and processing</p>
  33       </li>
  34       <li><p>Conversion between character sets</p>
  35       </li>
  36     </ul>
  37
  38   </sect1>
  39
  40   <sect1>
  41     <title>Download</title>
  42     <p>
  43 You can download <em>Netstring</em> as gzip'ed <a
  44                                                href="&url.netstring-download;">tarball</a>.
  45 </p>
  46
  47   </sect1>
  48
  49   <sect1>
  50     <title>Documentation</title>
  51     <p>
  52 Sorry, there is no manual. The mli files describe each function in
  53 detail. Furthermore, the following additional information may be useful.</p>
  54
  55     <sect2>
  56       <title>New CGI implementation</title>
  57
  58       <p>For a long time, the CGI implementation by Jean-Christophe Filliatre
  59 has been the only freely available module that implemented the CGI interface
  60 (it also based on code by Daniel de Rauglaudre). It worked well, but it did not
  61 support file uploads because this requires a parser for MIME messages.</p>
  62       <p>The main goal of Netstring is to realize such uploads, and because of
  63 this it contains an almost complete parser for MIME messages.</p>
  64       <p>The new CGI implementation provides the same functions than the old
  65 one, and some extensions. If you call Cgi.parse_args(), you get the CGI
  66 parameters as before, but as already explained this works also if the
  67 parameters are encaspulated as MIME message. In the HTML code, you can select
  68 the MIME format by using
  69 <code><![CDATA[
  70 <form action="..." method="post" enctype="multipart/form-data">
  71 ...
  72 </form>
  73 ]]>
  74 </code>
  75 - this "enctype" attribute forces the browser to send the form parameters
  76 as multipart MIME message (Note: You can neither send the parameters of a
  77 conventional hyperlink as MIME message nor the form parameters if the
  78 "method" is "get"). In many browsers only this particular encoding enables
  79 the file upload elements, you cannot perform file uploads with other encodings.
  80 </p>
  81
  82       <p>As MIME messages can transport MIME types, filename, and other
  83 additional properties, it is also possible to get these using the enhanced
  84 interface. After calling
  85 <code><![CDATA[
  86 Cgi.parse_arguments config
  87 ]]></code>
  88 you can get all available information about a certain parameter by invoking
  89 <code><![CDATA[
  90 let param = Cgi.argument "name"
  91 ]]></code>
  92 - where "param" has the type "argument". There are several accessor functions
  93 to extract the various aspects of arguments (name, filename, value by string,
  94 value by temporary file, MIME type, MIME header) from "argument" values.
  95 </p>
  96
  97     </sect2>
  98
  99
 100     <sect2>
 101       <title>Base64, and other encodings</title>
 102
 103       <p>Netstring is also the successor of the Base64 package. It provides a
 104 Base64 compatible interface, and an enhanced API. The latter is contained in
 105 the Netencoding module which also offers implementations of the "quoted
 106 printable", "Q", and "URL" encodings. Please see netencoding.mli for
 107 details.</p>
 108
 109     </sect2>
 110
 111
 112     <sect2>
 113       <title>The MIME scanner functions</title>
 114
 115       <p>In the Mimestring module you can find several functions scanning parts
 116 of MIME messages. These functions already cover most aspects of MIME messages:
 117 Scanning of headers, analysis of structured header entries, and scanning of
 118 multipart bodies. Of course, a full-featured MIME scanner would require some
 119 more functions, especially concrete parsers for frequent structures
 120 (mail addresses or date strings).
 121 </p>
 122       <p>Please see the file mimestring.mli for details.</p>
 123     </sect2>
 124
 125
 126     <sect2>
 127       <title>The HTML parser</title>
 128
 129       <p>The HTML parser should be able to read every HTML file; whether it is
 130 correct or not. The parser tries to recover from parsing errors as much as
 131 possible.
 132 </p>
 133       <p>The parser returns the HTML term as conventional recursive value
 134 (i.e. no object-oriented design).</p>
 135       <p>The parser depends a bit on knowledge about the HTML version; mainly
 136 because it needs to know the tags that are always empty. It may be necessary
 137 that you must adjust this configuration before the parser works well enough for
 138 your purpose.
 139 </p>
 140       <p>Please see the Nethtml module for details.</p>
 141     </sect2>
 142
 143     <sect2>
 144       <title>The abstract data type URL</title>
 145       <p>The module Neturl contains support for URL parsing and processing.
 146 The implementation follows strictly the standards RFC 1738 and RFC 1808.
 147 URLs can be parsed, and several accessor functions allow the user to
 148 get components of parsed URLs, or to change components. Modifying URLs
 149 is safe; it is impossible to create a URL that does not have a valid
 150 string representation.</p>
 151
 152       <p>Both absolute and relative URLs are supported. It is possible to
 153 apply a relative URL to a base URL in order to get the corresponding
 154 absolute URL.</p>
 155     </sect2>
 156
 157     <sect2>
 158       <title>Conversion between character sets and encodings</title>
 159       <p>The module Netconversion converts strings from one characters set
 160 to another. It is Unicode-based, and there are conversion tables for more than
 161 50 encodings.</p>
 162     </sect2>
 163
 164   </sect1>
 165
 166   <sect1>
 167     <title>Author, Copying</title>
 168     <p>
 169 <em>Netstring</em> has been written by &person.gps;. You may copy it as you like,
 170 you may use it even for commercial purposes as long as the license conditions
 171 are respected, see the file LICENSE coming with the distribution. It allows
 172 almost everything.
 173 </p>
 174   </sect1>
 175
 176   <sect1>
 177     <title>History</title>
 178
 179     <ul>
 180       <li><p><em>Changed in 0.9.3:</em> Fixed a bug in the "install" rule of
 181 the Makefile.</p>
 182       </li>
 183       <li><p><em>Changed in 0.9.2:</em> New format for the conversion tables
 184 which are now much smaller.</p>
 185       </li>
 186       <li><p><em>Changed in 0.9.1:</em> Updated the Makefile such that
 187 (native-code) compilation of netmappings.ml becomes possible.
 188 </p>
 189       </li>
 190       <li><p><em>Changed in 0.9:</em> Extended Mimestring module: It can
 191 now process RFC-2047 messages.</p>
 192         <p>New Netconversion module which converts strings between character
 193 encodings.</p>
 194       </li>
 195       <li><p><em>Changed in 0.8.1:</em> Added the component
 196 url_accepts_8bits to Neturl.url_syntax. This helps processing URLs which
 197 intentionally contain bytes >= 0x80.</p>
 198         <p>Fixed a bug: Every URL containing a 'j' was malformed!</p>
 199       </li>
 200       <li><p><em>Changed in 0.8:</em> Added the module Neturl which
 201 provides the abstract data types of URLs.</p>
 202         <p>The whole package is now thread-safe.</p>
 203         <p>Added printers for the various opaque data types.</p>
 204         <p>Added labels to function arguments where appropriate. The
 205 following functions changed their signatures significantly:
 206 Cgi.mk_memory_arg, Cgi.mk_file_arg.</p>
 207       </li>
 208       <li><p><em>Changed in 0.7:</em> Added workarounds for frequent
 209 browser bugs. Some functions take now an additional argument
 210 specifying which workarounds are enabled.</p>
 211       </li>
 212       <li><p><em>Changed in 0.6.1:</em> Updated URLs in documentation.</p>
 213       </li>
 214
 215       <li><p><em>Changed in 0.6:</em> The file upload has been re-implemented
 216 to support large files; the file is now read block by block and the blocks can
 217 be collected either in memory or in a temporary file.<br/>
 218 Furthermore, the CGI API has been revised. There is now an opaque data type
 219 "argument" that hides all implementation details and that is extensible (if
 220 necessary, it is possible to add features without breaking the interface
 221 again).<br/>
 222 The CGI argument parser can be configured; currently it is possible to
 223 limit the size of uploaded data, to control by which method arguments are
 224 processed, and to set up where temporary files are created.<br/>
 225 The other parts of the package that have nothing to do with CGI remain
 226 unchanged.
 227 </p>
 228       </li>
 229
 230       <li><p><em>Changed in 0.5.1:</em> A mistake in the documentation has
 231 been corrected.</p>
 232       </li>
 233
 234       <li><p><em>Initial version 0.5:</em>
 235 The Netstring package wants to be the successor of the Base64-0.2 and
 236 the Cgi-0.3 packages. The sum of both numbers is 0.5, and because of this,
 237 the first version number is 0.5.
 238 </p>
 239       </li>
 240     </ul>
 241   </sect1>
 242
 243 </readme>
 244