Improve man pages.
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 ,
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 ,
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 ,
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.
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 ,
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 ,
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 ,
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 ,
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.
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 ,
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 ,
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 ,
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 ,
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 ,
