Improve man pages.

TODO

diff --git a/TODO b/TODO
index 190867c..2a50f5d 100644
--- a/TODO
+++ b/TODO
@@ -145,7 +145,7 @@
 * read two zip entries interleaved
 
 
-
+- zip_source_file: don't allow write if start/len specify a part of the file
 
 D re-implement fix for OS X sandboxing (zip_archive_set_tempdir).
 
@@ -157,6 +157,7 @@
 - document ZIP_RDONLY
 - keep error codes in man pages in sync
 - document new functions
+- document error codes in new man pageses
 - document deprecations
 ** int zip_error_get_sys_type(int); /* use zip_error_system_type */
 ** void zip_error_get(zip_t *, int *, int *); /* use zip_get_error, zip_error_code_zip / zip_error_code_system */

man/zip_source_begin_write.mdoc

diff --git a/man/zip_source_begin_write.mdoc b/man/zip_source_begin_write.mdoc
index 057194c..ba78e0d 100644
--- a/man/zip_source_begin_write.mdoc
+++ b/man/zip_source_begin_write.mdoc
@@ -40,18 +40,18 @@
 .Sh SYNOPSIS
 .In zip.h
 .Ft int
-.Fn zip_source_begin_write "zip_source_t *zs"
+.Fn zip_source_begin_write "zip_source_t *source"
 .Sh DESCRIPTION
 The function
 .Fn zip_source_begin_write
-prepares the zip_source
-.Fa zs
+prepares
+.Fa source
 for writing.
 Usually this involves creating temporary files or allocating buffers.
 .Sh RETURN VALUES
 Upon successful completion 0 is returned.
 Otherwise, \-1 is returned and the error information in
-.Ar zs
+.Ar source
 is set to indicate the error.
 .Sh SEE ALSO
 .Xr libzip 3 ,

man/zip_source_close.mdoc

diff --git a/man/zip_source_close.mdoc b/man/zip_source_close.mdoc
index 5890b0b..0355d3e 100644
--- a/man/zip_source_close.mdoc
+++ b/man/zip_source_close.mdoc
@@ -40,17 +40,17 @@
 .Sh SYNOPSIS
 .In zip.h
 .Ft int
-.Fn zip_source_close "zip_source_t *zs"
+.Fn zip_source_close "zip_source_t *source"
 .Sh DESCRIPTION
 The function
 .Fn zip_source_close
-closes the zip_source
-.Fa zs
-which was open for reading.
+closes
+.Fa source ,
+indicating that no more data will be read.
 .Sh RETURN VALUES
 Upon successful completion 0 is returned.
 Otherwise, \-1 is returned and the error information in
-.Ar zs
+.Ar source
 is set to indicate the error.
 .Sh SEE ALSO
 .Xr libzip 3 ,

man/zip_source_commit_write.mdoc

diff --git a/man/zip_source_commit_write.mdoc b/man/zip_source_commit_write.mdoc
index 22c8513..0fe189a 100644
--- a/man/zip_source_commit_write.mdoc
+++ b/man/zip_source_commit_write.mdoc
@@ -40,18 +40,17 @@
 .Sh SYNOPSIS
 .In zip.h
 .Ft int
-.Fn zip_source_commit_write "zip_source_t *zs"
+.Fn zip_source_commit_write "zip_source_t *source"
 .Sh DESCRIPTION
 The function
 .Fn zip_source_commit_write
-finishes writing data to the zip source
-.Fa zs .
-Usually this involves flushing buffers, replacing original files with
-temporary files or cleaning up buffers.
+finishes writing data to
+.Fa source
+and replaces the original with the newly written data.
 .Sh RETURN VALUES
 Upon successful completion 0 is returned.
 Otherwise, \-1 is returned and the error information in
-.Ar zs
+.Ar source
 is set to indicate the error.
 .Sh SEE ALSO
 .Xr libzip 3 ,

man/zip_source_is_deleted.mdoc

diff --git a/man/zip_source_is_deleted.mdoc b/man/zip_source_is_deleted.mdoc
index 7a174fc..0399b9a 100644
--- a/man/zip_source_is_deleted.mdoc
+++ b/man/zip_source_is_deleted.mdoc
@@ -40,12 +40,12 @@
 .Sh SYNOPSIS
 .In zip.h
 .Ft int
-.Fn zip_source_is_deleted "zip_source_t *zs"
+.Fn zip_source_is_deleted "zip_source_t *source"
 .Sh DESCRIPTION
 The function
 .Fn zip_source_is_deleted
-returns if the zip_source was deleted.
-This can for example happen every entry is removed from a zip archive.
+returns whether the zip_source was deleted.
+This can for example happen when all entries are removed from a zip archive.
 .Sh RETURN VALUES
 .Fn zip_source_is_deleted
 returns 1 if the zip_source is deleted and 0 otherwise.

man/zip_source_open.mdoc

diff --git a/man/zip_source_open.mdoc b/man/zip_source_open.mdoc
index fe70487..4bd5c60 100644
--- a/man/zip_source_open.mdoc
+++ b/man/zip_source_open.mdoc
@@ -40,17 +40,17 @@
 .Sh SYNOPSIS
 .In zip.h
 .Ft int
-.Fn zip_source_open "zip_source_t *zs"
+.Fn zip_source_open "zip_source_t *source"
 .Sh DESCRIPTION
 The function
 .Fn zip_source_open
-opens the zip_source
-.Fa zs
+opens
+.Fa source
 for reading.
 .Sh RETURN VALUES
 Upon successful completion 0 is returned.
 Otherwise, \-1 is returned and the error information in
-.Ar zs
+.Ar source
 is set to indicate the error.
 .Sh SEE ALSO
 .Xr libzip 3 ,

man/zip_source_read.mdoc

diff --git a/man/zip_source_read.mdoc b/man/zip_source_read.mdoc
index 50cf174..c9a29b9 100644
--- a/man/zip_source_read.mdoc
+++ b/man/zip_source_read.mdoc
@@ -40,20 +40,26 @@
 .Sh SYNOPSIS
 .In zip.h
 .Ft zip_int64_t
-.Fn zip_source_read "zip_source_t *zs" "void *data" "zip_uint64_t len"
+.Fn zip_source_read "zip_source_t *source" "void *data" "zip_uint64_t len"
 .Sh DESCRIPTION
 The function
 .Fn zip_source_read
 reads up to
 .Ar len
-bytes of data from the zip source
-.Ar zs
-at the current read offset and writes them to the buffer
+bytes of data from
+.Ar source
+at the current read offset into the buffer
 .Ar data .
+.Pp
+The zip source
+.Ar source
+has to be opened for reading by calling
+.Xr zip_source_open 3
+first.
 .Sh RETURN VALUES
 Upon successful completion the number of bytes read is returned.
 Otherwise, \-1 is returned and the error information in
-.Ar zs
+.Ar source
 is set to indicate the error.
 .Sh SEE ALSO
 .Xr libzip 3 ,

man/zip_source_rollback_write.mdoc

diff --git a/man/zip_source_rollback_write.mdoc b/man/zip_source_rollback_write.mdoc
index cd5142c..47079ca 100644
--- a/man/zip_source_rollback_write.mdoc
+++ b/man/zip_source_rollback_write.mdoc
@@ -40,17 +40,20 @@
 .Sh SYNOPSIS
 .In zip.h
 .Ft int
-.Fn zip_source_rollback_write "zip_source_t *zs"
+.Fn zip_source_rollback_write "zip_source_t *source"
 .Sh DESCRIPTION
 The function
 .Fn zip_source_rollback_write
-reverts changes written to the zip source
-.Fa zs .
-Usually this removes temporary files or freeing buffers.
+reverts changes written to
+.Fa source ,
+restoring the data before 
+.Xr zip_source_begin_write 3
+was called.
+Usually this removes temporary files or frees buffers.
 .Sh RETURN VALUES
 Upon successful completion 0 is returned.
 Otherwise, \-1 is returned and the error information in
-.Ar zs
+.Ar source
 is set to indicate the error.
 .Sh SEE ALSO
 .Xr libzip 3 ,

man/zip_source_seek.mdoc

diff --git a/man/zip_source_seek.mdoc b/man/zip_source_seek.mdoc
index 9caf0aa..f6c3881 100644
--- a/man/zip_source_seek.mdoc
+++ b/man/zip_source_seek.mdoc
@@ -40,15 +40,12 @@
 .Sh SYNOPSIS
 .In zip.h
 .Ft int
-.Fn zip_source_seek "zip_source_t *zs" "zip_int64_t offset" "int whence"
+.Fn zip_source_seek "zip_source_t *source" "zip_int64_t offset" "int whence"
 .Sh DESCRIPTION
 The function
 .Fn zip_source_seek
-sets the current read offset for the zip source
-.Fa zs
-to
-.Ar offset
-bytes.
+sets the current read offset for
+.Fa source .
 Just like in
 .Xr fseek 3 ,
 depending on the
@@ -60,14 +57,14 @@
 .It Dv SEEK_SET
 start of file
 .It Dv SEEK_CUR
-current position in file
+current read offset in file
 .It Dv SEEK_END
 end of file
 .El
 .Sh RETURN VALUES
 Upon successful completion 0 is returned.
 Otherwise, \-1 is returned and the error information in
-.Ar zs
+.Ar source
 is set to indicate the error.
 .Sh SEE ALSO
 .Xr libzip 3 ,

man/zip_source_seek_compute_offset.mdoc

diff --git a/man/zip_source_seek_compute_offset.mdoc b/man/zip_source_seek_compute_offset.mdoc
index 66e5c32..5dfe781 100644
--- a/man/zip_source_seek_compute_offset.mdoc
+++ b/man/zip_source_seek_compute_offset.mdoc
@@ -53,7 +53,7 @@
 are the arguments to the source callback,
 .Ar offset
 is the current offset and
-.Ar length
+Ar length
 is the length of the source data or, for
 .Dv ZIP_SOURCE_SEEK_WRITE ,
 the amount of data written.

man/zip_source_seek_write.mdoc

diff --git a/man/zip_source_seek_write.mdoc b/man/zip_source_seek_write.mdoc
index 6569653..720f75a 100644
--- a/man/zip_source_seek_write.mdoc
+++ b/man/zip_source_seek_write.mdoc
@@ -40,15 +40,12 @@
 .Sh SYNOPSIS
 .In zip.h
 .Ft int
-.Fn zip_source_seek_write "zip_source_t *zs" "zip_int64_t offset" "int whence"
+.Fn zip_source_seek_write "zip_source_t *source" "zip_int64_t offset" "int whence"
 .Sh DESCRIPTION
 The function
 .Fn zip_source_seek_write
-sets the current write offset for the zip source
-.Fa zs
-to
-.Ar offset
-bytes.
+sets the current write offset for
+.Fa source .
 Just like in
 .Xr fseek 3 ,
 depending on the
@@ -60,14 +57,14 @@
 .It Dv SEEK_SET
 start of file
 .It Dv SEEK_CUR
-current position in file
+current write offset in file
 .It Dv SEEK_END
 end of file
 .El
 .Sh RETURN VALUES
 Upon successful completion 0 is returned.
 Otherwise, \-1 is returned and the error information in
-.Ar zs
+.Ar source
 is set to indicate the error.
 .Sh SEE ALSO
 .Xr libzip 3 ,

man/zip_source_stat.mdoc

diff --git a/man/zip_source_stat.mdoc b/man/zip_source_stat.mdoc
index 08143b8..cb68b73 100644
--- a/man/zip_source_stat.mdoc
+++ b/man/zip_source_stat.mdoc
@@ -40,12 +40,12 @@
 .Sh SYNOPSIS
 .In zip.h
 .Ft int
-.Fn zip_source_stat "zip_source_t *zs" "zip_stat_t *sb"
+.Fn zip_source_stat "zip_source_t *source" "zip_stat_t *sb"
 .Sh DESCRIPTION
 The
 .Fn zip_source_stat
 function obtains information about the zip source
-.Ar zs
+.Ar source
 .Pp
 The
 .Ar sb
@@ -68,7 +68,9 @@
 .Ed
 The structure pointed to by
 .Ar sb
-must be allocated before calling
+must be initialized with
+.Fn zip_stat_init 3
+before calling
 .Fn zip_source_stat .
 .Pp
 The
@@ -108,7 +110,7 @@
 .Sh RETURN VALUES
 Upon successful completion 0 is returned.
 Otherwise, \-1 is returned and the error information in
-.Ar zs
+.Ar source
 is set to indicate the error.
 .Sh SEE ALSO
 .Xr libzip 3 ,

man/zip_source_tell.mdoc

diff --git a/man/zip_source_tell.mdoc b/man/zip_source_tell.mdoc
index 83d1ae4..b26122c 100644
--- a/man/zip_source_tell.mdoc
+++ b/man/zip_source_tell.mdoc
@@ -40,24 +40,24 @@
 .Sh SYNOPSIS
 .In zip.h
 .Ft zip_int64_t
-.Fn zip_source_tell "zip_source_t *zs"
+.Fn zip_source_tell "zip_source_t *source"
 .Sh DESCRIPTION
 The function
 .Fn zip_source_tell
-returns the current read offset (relative to the start of the file)
-for the zip source
-.Fa zs .
+returns the current read offset
+for
+.Fa source .
 The return value can be passed to
 .Xr zip_source_seek 3
 with
 .Ar whence
 set to
 .Dv SEEK_SET
-to return to the same location in the file.
+to return to the same location in the source.
 .Sh RETURN VALUES
 Upon successful completion the current read offset is returned.
 Otherwise, \-1 is returned and the error information in
-.Ar zs
+.Ar source
 is set to indicate the error.
 .Sh SEE ALSO
 .Xr libzip 3 ,

man/zip_source_tell_write.mdoc

diff --git a/man/zip_source_tell_write.mdoc b/man/zip_source_tell_write.mdoc
index 17121e0..0bc6783 100644
--- a/man/zip_source_tell_write.mdoc
+++ b/man/zip_source_tell_write.mdoc
@@ -40,24 +40,24 @@
 .Sh SYNOPSIS
 .In zip.h
 .Ft zip_int64_t
-.Fn zip_source_tell_write "zip_source_t *zs"
+.Fn zip_source_tell_write "zip_source_t *source"
 .Sh DESCRIPTION
 The function
 .Fn zip_source_tell_write
-returns the current write offset (relative to the start of the file)
-for the zip source
-.Fa zs .
+returns the current write offset
+for
+.Fa source .
 The return value can be passed to
 .Xr zip_source_seek_write 3
 with
 .Ar whence
 set to
 .Dv SEEK_SET
-to return to the same location in the file.
+to return to the same location in the source.
 .Sh RETURN VALUES
 Upon successful completion the current write offset is returned.
 Otherwise, \-1 is returned and the error information in
-.Ar zs
+.Ar source
 is set to indicate the error.
 .Sh SEE ALSO
 .Xr libzip 3 ,

man/zip_source_write.mdoc

diff --git a/man/zip_source_write.mdoc b/man/zip_source_write.mdoc
index c9a1a71..b7e7962 100644
--- a/man/zip_source_write.mdoc
+++ b/man/zip_source_write.mdoc
@@ -40,27 +40,27 @@
 .Sh SYNOPSIS
 .In zip.h
 .Ft zip_int64_t
-.Fn zip_source_write "zip_source_t *zs" "const void *data" "zip_uint64_t len"
+.Fn zip_source_write "zip_source_t *source" "const void *data" "zip_uint64_t len"
 .Sh DESCRIPTION
 The function
 .Fn zip_source_write
 writes
 .Ar len
-bytes of data from the buffer
+bytes from the buffer
 .Ar data
 to the zip source
-.Ar zs
+.Ar source
 at the current write offset.
 .Pp
 The zip source
-.Ar zs
-has to be prepared for this by calling
+.Ar source
+has to be prepared for writing by calling
 .Xr zip_source_begin_write 3
 first.
 .Sh RETURN VALUES
 Upon successful completion the number of bytes written is returned.
 Otherwise, \-1 is returned and the error information in
-.Ar zs
+.Ar source
 is set to indicate the error.
 .Sh SEE ALSO
 .Xr libzip 3 ,