updated documentation

diff --git a/README.adoc b/README.adoc
index 6394f2f5ac952185eb415f91cdd5847b04c42620..8756dee3da829d806e43a1797204390cc6839b9f 100644 (file)
--- a/README.adoc
+++ b/README.adoc
@@ -1,16 +1,25 @@
 The packnl Project
 ==================
 
-*packnl* is a command to pack a newlisp application into a binary
-using the embedding feature of newlisp. Such a packed binary will have
-+incore.lsp+ as embedded script, and then extended with the
-application files in a "simple archive" format. The first application
-file is used as "main script" that is loaded automatically. The
-remaining application files are set up to be available as overriding
-members for the +load+, +read-file+ and +file?+ functions.
-
-.packnl -w binary ( file | -a name | -A name | -C path )*
+*packnl* is a tool for "packing" a newlisp application into an
+executable by using the embedding feature of newlisp. Such a packed
+binary will have +incore.lsp+ as its embedded script, and then it is
+extended with the application files in a "simple archive" format. In
+short, the executable is a newlisp interpreter packed together with
+the application scripts into a single binary file.
+
+The packed appplication uses the first application file as its "main
+script", which is loaded and executed automatically. Other application
+files are available for the +load+, +read-file+ and +file?+ functions.
+
+Usage Examples
+--------------
+
+.Writing a packed binary
 ====
+----
+    packnl -w binary ( file | -a name | -A name | -C path )*
+----
 This commandline form is used for preparing a binary with the given
 files. The nominated files will be appended to the binary in the given
 order.
@@ -25,14 +34,32 @@ archive.
 * The *-C* option is used for changing (input) directory as given.
 ====
 
-.packnl -t binary
+.Listing a packed binary
 ====
+----
+    packnl -t binary
+----
 This commandline form is used for reviewing a packed binary as a list
 of its included members.
 ====
 
-.packnl -u binary directory
+.Unpack a packed binary
 ====
+----
+    packnl -u binary directory
+----
 This commandline form is used for unpacking a packed binary into a
 given target directory.
 ====
+
+Packed Binary Format
+--------------------
+
+A packed binary is essentially a concatenation of an embedded newlisp
+executable (together with its embedded script) and an archive file in
+"ar" format. The latter is a concatenation of the files included where
+each has a 2-line preamble consisting of the pathname in one line,
+then the content byte size as a 10-base number in ascii. Please review
+the Makefile which creates *packnl* as a conformant packed binary
+using plain *sh* commands.
+