X-Git-Url: https://git.rrq.au/?a=blobdiff_plain;f=README.adoc;h=f785ab6628d769176f2494a904256b4a68ff2b69;hb=7005e3b7c3143f6071393cd576cadb89c51d486d;hp=656dcf91b961ed50e13ce639c9cc2184f0441aa3;hpb=3dcbdf45070be29c4dec5217bcb141d8ee96ac47;p=rrq%2Fnewlisp%2Fpacknl.git

diff --git a/README.adoc b/README.adoc
index 656dcf9..f785ab6 100644
--- 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 )*
+= The packnl Project
+:author: Ralph Ronnquist
+:revdate: Sun, 30 Apr 2023 23:56:02 +1000
+
+*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.
@@ -21,16 +30,35 @@ binary.
 
 * The *-A* option is used for including all members of an +ar+ style
 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.
+