source: project/z3/doc.scm @ 4232

Last change on this file since 4232 was 4232, checked in by felix winkelmann, 13 years ago

various fixes, alexpander update

File size: 7.3 KB
Line 
1(use eggdoc)
2
3(define license
4"Copyright (c) 2005-2007 Oskar Schirmer.  All rights reserved.
5
6Permission is hereby granted, free of charge, to any person obtaining a
7copy of this software and associated documentation files (the Software),
8to deal in the Software without restriction, including without limitation
9the rights to use, copy, modify, merge, publish, distribute, sublicense,
10and/or sell copies of the Software, and to permit persons to whom the
11Software is furnished to do so, subject to the following conditions:
12
13The above copyright notice and this permission notice shall be included
14in all copies or substantial portions of the Software.
15
16THE SOFTWARE IS PROVIDED ASIS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
19THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
20OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
21ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
22OTHER DEALINGS IN THE SOFTWARE.")
23
24(define doc
25  `((eggdoc:begin
26     (name "z3")
27     (description (p "A gzip (RFC1951 + RFC1952) compression and decompression library"))
28     
29     (author "Oskar Schirmer and felix winkelmann")
30
31     (history
32      (version "1.36" "Should compile now on Windows with mingw")
33      (version "1.35" "Fixed bug in " (tt "z3:encode-buffer") " [reported by Mario Domenech Goulart]")
34      (version "1.34" "Added whole-buffer encoding/decoding")
35      (version "1.33" "Fixed setup script and meta file [Thanks to Peter Busser]")
36      (version "1.32" "Fixed bug in z3lib code, related to 64-bit architectures")
37      (version "1.31" "Fixed bug in " (tt "z3:encode"))
38      (version "0.9" "Initial release") )
39
40     (usage)
41     (download "z3.egg")
42
43     (documentation
44      (p "Provides functions to read and write compressed data using the gzip algorithm."
45         " This extension includes code from Oskar Schirmers excellent " 
46         (a (@ (href "http://scara.com/~schirmer/o/z3lib/")) "z3lib") "library.")
47      (p "Errors occurring in inflation/deflation procedures will result in a composite"
48         " condition of the kinds " (tt "exn") " and " (tt "z3") ".")
49
50     (subsection
51      "Raw data interface"
52      (group
53       (procedure "(z3:encode-init #!key buffer buffer-size tellwhen thrmin thrmax initialgrant preferlonger)"
54                  (p "Initializes compression of data into a memory buffer. Various keyword arguments can be supplied"
55                     " to control compression:")
56                  (dl (dt "buffer") (dd "The target buffer for the compressed data")
57                      (dt "buffer-size") (dd "maximal size of the compressed data")
58                      (dt "tellwhen") (dd "Frequency for code size estimation (0 for none, i.e. full block usage)")
59                      (dt "thrmin, thrmax") (dd "Threshold for block close decision")
60                      (dt "initialgrant") (dd "For threshold comparison, all but the first slice are asumed to be "
61                                              "incremented by this value to roughly compensate RFC1951 block dynamic "
62                                              "table size") 
63                      (dt "preferlonger") (dd "When  non-zero,  the  compressor will try to find a longer match at "
64                                              " n+1 and prefer it over a previous match at n") )
65                  (p "Returns a z3 handle.") )
66       (procedure "(z3:encode Z3HANDLE RECEIVER DATA [LENGTH])"
67                  (p "Encode data (a string) into a memory buffer and returns the number of bytes written. If less"
68                     " data has been commpressed than given in the call, invoke " (tt "z3:encode") " repeatedly with"
69                     " the remaining data. Returns " (tt "#f") " when finished. Each time some compressed data is"
70                     " available, the one-argument procedure " (tt "RECEIVER") " is called with a string containing"
71                     " a chunk of compressed data.") )
72       (procedure "(z3:decode-init)"
73                  (p "Initialize an in-memory decompression and return a z3 handle for it.") )
74       (procedure "(z3:decode Z3HANDLE RECEIVER BUFFER [LENGTH])"
75                  (p "Decode the compressed data in " (tt "BUFFER") " (a string) and return the number of"
76                     " bytes decompressed.") )
77       (procedure "(z3:handle? X)"
78                  (p "Returns " (tt "#t") " if " (tt "X") " is a z3 handle or " (tt "#f") " otherwise.") ) ) )
79
80     (subsection
81      "Buffer interface"
82      (grooup
83       (procedure "(z3:encode-buffer STRING [START [END [DESTINATION]]])"
84                  (p "Encodes the data in " (tt "STRING") " with optional start- and end-positions."
85                     " If " (tt "DESTINATION") " is given, then the compressed data will be stored in"
86                     " that argument (which should be a string of sufficient size) and " (tt "z3:encode-buffer")
87                     " returns the length of the compressed data. If no destination is given then a freshly allocated"
88                     " string is returned that contains the compressed data.") )
89       (procedure "(z3:decode-buffer STRING [START [END]])"
90                  (p "Decodes the compressed data in " (tt "STRING") " and returns the uncompressed"
91                     " data. Optional start- and end-position may be given.") ) ) )
92
93     (subsection 
94      "File-system interface"
95      (group
96       (procedure "(z3:encode-file FILENO #!key level filename comment ostype extra)"
97                  (p "Open a compressed file (specified by the file-descriptor in " (tt "FILENO") ") for encoded data. "
98                     "The keyword arguments have the following meaning:")
99                  (dl (dt "level") 
100                      (dd "Desired compression-level in the range 1 .. 9, or 0 for selecting the default compression level") 
101                      (dt "filename")
102                      (dd "The name of the file to compress, will be included in the gzip-file header")
103                      (dt "comment")
104                      (dd "An arbitrary comment")
105                      (dt "ostype")
106                      (dd "Operating system indicator byte (defaults to -1)")
107                      (dt "extra")
108                      (dd "Extra data to be encoded in the header") )
109                  (p "Returns a z3 file-handle.") )                                   
110       (procedure "(z3:write-encoded Z3FHANDLE DATA [LENGTH])"
111                  (p "Writes " (tt "DATA") " (a string) into a compressed file, optionally limited in length."
112                     " Before a file has been encoded completely, this procedure must be called once more with "
113                     (tt "DATA") " being " (tt "#f") " to indicate that the compression process is finished.") )
114       (procedure "(z3:decode-file FILENO)"
115                  (p "Returns a z3 file-handle for reading the file designated by the file-descriptor " (tt "FILENO") ".") )
116       (procedure "(z3:read-decoded Z3FHANDLE [LENGTH])"
117                  (p "Reads a chunk of decoded data from a compressed file. The length of the chunk can be given as"
118                     " an optional argument and defaults to 4096 bytes. Returns a string or the end-of-file object.") )
119       (procedure "(z3:file-handle? X)"
120                  (p "Returns " (tt "#t") " if " (tt "X") " is a z3 file handle or " (tt "#f") " otherwise.") )
121       (procedure "(z3:file-handle-fileno Z3FHANDLE)"
122                  (p "Returns the file-descriptor associated with a z3 file-handle.") ) ) )
123
124     (subsection
125      "Port interface"
126      (group
127       (procedure "(z3:open-compressed-input-file FILENAME)"
128                  (p "Opens a compressed input file and returns a port that automatically"
129                     " decompresses the data as it is read.") )
130       (procedure "(z3:open-compressed-output-file FILENAME #!key level comment ostype extra)"
131                  (p "Creates a compressed file and returns an output-port. The keyword arguments have the same"
132                     " meaning as for the " (tt "z3:encode-file") " procedure.") ) ) ) ))
133
134     (section "License" (pre ,license))))
135
136(eggdoc->html doc)
137
Note: See TracBrowser for help on using the repository browser.