editoral. expand and complete

diff --git a/incore.lsp.8.adoc b/incore.lsp.8.adoc
index 90d2864e309f6aeb3c574d9179d8c9223d37e913..e7acf946e2ad25860b3884fad7afae86732b09ec 100644 (file)
--- a/incore.lsp.8.adoc
+++ b/incore.lsp.8.adoc
@@ -4,17 +4,18 @@
 
 == NAME
 
-incore.lsp - module for wrapping newlisp's load and read-file
-functions to handle both in-core and external "ar" or "tar" archives
-as local files.
+incore.lsp - a newlisp module for application embedding.
 
 == SYNOPSIS
 
-_embedding directive in Makefile_
+Use case: _normal module loading_::
+
+(*load "incore.lsp"*)
+
+Use case: _as embedding directive in Makefile_::
 
-[pass]
 ----
-_binary_: _main.lsp_ _other.lsp*_
+_binary_: _main.lsp_ _other.lsp_*
        newlisp -x incore.lsp $@
        chmod a+x $@
        echo 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' >> $@
@@ -23,48 +24,91 @@ _binary_: _main.lsp_ _other.lsp*_
        done >> $@
 ----
 
+Use case: _indirectly with packnl_::
+
+*packnl* *-w* _binary_ _main.lsp_ _member-option_* +
+
+
 == DESCRIPTION
 
-*incore.lsp* is a newlisp module intended to be used for application
-embedding into self-contained script collections.
+*incore.lsp* is a newlisp module for application embedding into
+self-contained script collections including both an in-core archive
+and optionally external archives in _ar_ or _tar_ formats.
+
+The first use case illustrates loading the module in a running script.
+When the module is loaded it installs an _archives_ hashtable and an
+_archive_ context for handling an in-core archive, and then it wraps
+newlisp's _load_, _read-file_ and _file?_ functions to first use the
+_archives_ hashtable before looking at the external filesystem.
+
+The second use case shows an example of a _Makefile_ fragment that
+makes an embedding with *incore.lsp* extended with an in-core archive
+following the divide line of 40 "x" characters. The resulting _binary_
+will contain all the mentioned newlisp scripts ( _main.lsp_ and all
+_other.lsp_) as an in-core archive appended to the embedding of
+*incore.lsp*. As a result when the binary is executed the _main.lsp_
+script will be loaded and thus executed as the application script
+while all _other.lsp_ scripts are availble to it for _load_ and
+_read-file_.
+
+The third use case presents how the _packnl_ utility is used to achive
+the same embedding as the second use case, though with the addition of
+referring to scripts within _ar_ aor _tar_ archive files.
+
+=== incore.lsp API
+
+*core:core*::
+
+This is a data reference functor that gets set up by reading
+"/proc/self/exe". This is only useful for an embedded binary where it
+will contain application's inc-core archive. Any other use case will
+need to redefine *core:core* for its in-core archive, if any.
 
-*incore.lsp* is the main scripting that locates application scripts
-appended to the running binary and sets these up as in-core archive
-files. It wraps the newlisp functions +load+, +read-file+ and +file?+
-so as to locate local files via the archives paths first. It will thus
-locate any self-contained files first, before trying to find them as
-external files.
+(*archives* _FILENAME_ _ARCHIVE_)::
 
-When the binary has files appended, the very first file is processed
-as the application main script.
+This is a hashtable mapping _FILENAME_ to containing _ARCHIVE_. The
+_ARCHIVE_ argument is either a pathname for an external _ar_ or _tar_
+archive or a list of two numbers (offset and length) for an in-core
+data slice.
 
-=== newlisp API
+(*archive* _ARCHIVE_)::
 
-(*archives*)::
+The _archive_ context is a namespace to for the functions implementing
+archive access of files. The "default function" installs the members
+of the given _ARCHIVE_ into the *archives* hashtable.
 
-*archives* is a hashtable of known "local" files associated with
-archiving details. These local files are associate with in-core access
-details or with external archive pathname, which is an external
-directory path, and +ar+ archive file (ending with ".a") or a +tar+
-archive file (detemined via the +file+ command).
+*archive:main*::
 
-(*archive* _PATH_)::
+This variable is assigned during module loading to identify the name
+of the first in-core member. In the embedded use case this will be the
+"main script" to load automatically. In that case the application will
+exit after the main script has been loaded (unless it ends with _reset_
+function call).
 
-*archive* is a context for the archive handling support functions,
-including the "context function" to register archive accesible files
-with the given _PATH_ as an external archive path. The given path is
-processed and all content files are added to the *archives* hashtable
-with the given access path. Note that the any current access
-assignment will be overwritten.
-+
-.Loading from known tar archive file.
+(*archive:tar-able* _PATHNAME_)::
+
+This function uses the Unix _file_ command to recognize the given
+_PATHNAME_ as naming a _tar_ file. (An _ar_ archive is recognized
+simply by the _PATHNAME_ ending with ".a")
+
+(*archive:get-stdout* _COMMAND_)::
+
+This function executes the given shell _COMMAND_ and captures its
+standard output into a newlisp binary data block.
+
+(*archive:get* _PATH_ _FILENAME_)::
+
+This function reads the _FILENAME_ from the _PATH_, which is a
+directory, and _ar_ file or a _tar_ file.
+
+== EXAMPLE
+
+Note that *incore.lsp* is the embedding used by _packnl_.
+
+.Loading a file from an imagined compressed tar file.
 ====
-----
-(archive "/usr/share/myapp/utilities-version-2.5.tgz")
+(archive "/usr/share/myapp/utilities-version-2.5.tgz") +
 (load "framework.lsp")
-----
-This example illustrates how to make the files of a tar archive file
-available for loading as if local files.
 ====
 
 == SEE ALSO