archive_write.3: narrative moved from libarchive.3, edited

SVN-Revision: 3101

diff --git a/libarchive/archive_write.3 b/libarchive/archive_write.3
index f3d35f9cb544df33e958ce3402154b387d45a4c8..f5eb0529a0ae7a1cadb19a0cbbcd32b16f92e191 100644 (file)
--- a/libarchive/archive_write.3
+++ b/libarchive/archive_write.3
@@ -43,36 +43,79 @@ close the archive and release all resources.
 .Ss Create archive object
 See
 .Xr archive_write_new 3 .
+.Pp
+To write an archive, you must first obtain an initialized
+.Tn struct archive
+object from
+.Fn archive_write_new .
 .\"
-.Ss Enable filters and formats
+.Ss Enable filters and formats, configure block size and padding
 See
-.Xr archive_write_filter 3
+.Xr archive_write_filter 3 ,
+.Xr archive_write_format 3
+and
+.Xr archive_write_blocksize 3 .
+.Pp
+You can then modify this object for the desired operations with the
+various
+.Fn archive_write_set_XXX
+functions.
+In particular, you will need to invoke appropriate
+.Fn archive_write_add_XXX
 and
-.Xr archive_write_format 3 .
+.Fn archive_write_set_XXX
+functions to enable the corresponding compression and format
+support.
 .\"
-.Ss Configure block size and padding
+.Ss Set options
 See
-.Xr archive_write_blocksize 3 .
+.Xr archive_read_set_options 3 .
 .\"
 .Ss Open archive
 See
 .Xr archive_write_open 3 .
+.Pp
+Once you have prepared the
+.Tn struct archive
+object, you call
+.Fn archive_write_open
+to actually open the archive and prepare it for writing.
+There are several variants of this function;
+the most basic expects you to provide pointers to several
+functions that can provide blocks of bytes from the archive.
+There are convenience forms that allow you to
+specify a filename, file descriptor,
+.Ft "FILE *"
+object, or a block of memory from which to write the archive data.
 .\"
 .Ss Produce archive
 See
 .Xr archive_write_header 3
 and
 .Xr archive_write_data 3 .
+.Pp
+Individual archive entries are written in a three-step
+process:
+You first initialize a
+.Tn struct archive_entry
+structure with information about the new entry.
+At a minimum, you should set the pathname of the
+entry and provide a
+.Va struct stat
+with a valid
+.Va st_mode
+field, which specifies the type of object and
+.Va st_size
+field, which specifies the size of the data portion of the object.
 .\"
 .Ss Release resources
 See
 .Xr archive_write_free 3 .
 .Pp
-More information about the
-.Va struct archive
-object and the overall design of the library can be found in the
-.Xr libarchive 3
-overview.
+After all entries have been written, use the
+.Fn archive_write_free
+function to release all resources.
+.\"
 .Sh EXAMPLE
 The following sketch illustrates basic usage of the library.
 In this example,

diff --git a/libarchive/libarchive.3 b/libarchive/libarchive.3
index 692ee317491fb114b7e816b9a68a2021ff5b44ce..02bee81d0215925ce7b53f87e3a153d851e2bbe2 100644 (file)
--- a/libarchive/libarchive.3
+++ b/libarchive/libarchive.3
@@ -120,48 +120,9 @@ See
 .Xr libarchive_read 3 .
 .\"
 .Sh WRITING AN ARCHIVE
-You use a similar process to write an archive.
-The
-.Fn archive_write_new
-function creates an archive object useful for writing,
-the various
-.Fn archive_write_set_XXX
-functions are used to set parameters for writing the archive, and
-.Fn archive_write_open
-completes the setup and opens the archive for writing.
-.Pp
-Individual archive entries are written in a three-step
-process:
-You first initialize a
-.Tn struct archive_entry
-structure with information about the new entry.
-At a minimum, you should set the pathname of the
-entry and provide a
-.Va struct stat
-with a valid
-.Va st_mode
-field, which specifies the type of object and
-.Va st_size
-field, which specifies the size of the data portion of the object.
-The
-.Fn archive_write_header
-function actually writes the header data to the archive.
-You can then use
-.Fn archive_write_data
-to write the actual data.
-.Pp
-After all entries have been written, use the
-.Fn archive_write_finish
-function to release all resources.
-(Note:
-.Fn archive_write_finish
-is deprecated in Libarchive 3.0; please use
-.Fn archive_write_free
-instead.)
-.Pp
-The
-.Xr archive_write 3
-manual page provides more detailed calling information for this API.
+See
+.Xr libarchive_write 3 .
+.\"
 .Sh WRITING ENTRIES TO DISK
 The
 .Xr archive_write_disk 3