Allow for smaller newlisp binary

[rrq/newlisp/packnl.git] / packnl.8.adoc

diff --git a/packnl.8.adoc b/packnl.8.adoc
index 22abdc8a0e1681c10fcdba101017bac445deb084..c3574f813e7fe48564b3df9cd8f3e94503886b69 100644 (file)
--- a/packnl.8.adoc
+++ b/packnl.8.adoc
@@ -1,56 +1,45 @@
-packnl(8)
-=========
+= packnl(8)
 :doctype: manpage
 :revdate: {sys:date "+%Y-%m-%d %H:%M:%S"}
 :COLON: :
 :EQUALS: =
 :NEWLINE: \n
 
-NAME
-----
-packnl - Pack newlisp scripts into an embedded binary.
-
-SYNOPSIS
---------
+== NAME
 
-*packnl* -w _binary_ _member-option_*
+packnl - Pack newlisp scripts into an embedded binary.
 
-*packnl* -u _binary_ _path_
+== SYNOPSIS
 
-*packnl* -t _binary_
+*packnl* *-w* _binary_ _main.lsp_ _member-option_* +
+*packnl* *-u* _binary_ _path_ +
+*packnl* *-t* _binary_
 
-DESCRIPTION
------------
+== DESCRIPTION
 
 *packnl* is a utility to pack a newlisp application into a binary
 using the embedding feature of newlisp. Such a packed binary will have
-the special +incore.lsp+ as embedded script, and it is then extended
-with the given application files in a "simple archive" format.
-
-The first application script is "main script" and it is loaded
-automatically. Additional application scripts and files are set up to
-be available as overriding filenames for the +load+, +read-file+ and
-+file?+ functions.
+the special +incore.lsp+ as embedded script and then contain the given
+application files in a "simple archive" format after an easily
+recognizable divider line of 40 "x" characters.
 
-E.g., where the running script has the expression "(load _file_)" then
-_file_ is first looked up as being an embedded member (script), and
-only secondarily looked up in the filesystem.
+The first application file is used as "main script" the gets loaded
+when running the binary. Any additional application files are set up
+as an in-core archive to be available as overriding filenames in the
++load+, +read-file+ and +file?+ functions. I.e. where the running
+script has the expression "(load _file_)" then _file_ pathname is
+first looked up in the in-core archive and only secondarily looked up
+in the filesystem.
 
+== OPTIONS
 
-OPTIONS
--------
-
-Command Options
-~~~~~~~~~~~~~~~
+=== Command Options
 
 *-w* _binary_ _members_::
 
 The *-w* command option is used for writing an embedded newlisp binary
 with the nominated scripts. The subseqent arguments nominate the
-scripts to include, and optionally nominate +ar+ style libraries of
-scripts to include from, or include a library in full, as well as
-optionally change the input directory for resolving subsequent script
-names. See *Member Options* below.
+scripts to include in order. See *Member Options* below.
 
 *-u* _binary_ _path_::
 
@@ -62,12 +51,11 @@ the nominated directory.
 The *-t* command option is used for enlisting then names of the
 included members of an embedded binary.
 
-Member Otions
-~~~~~~~~~~~~~
+=== Member Otions
 
-*_member_*::
+_member_::
 
-All member arguments other than the options below are undestood to
+Member arguments other than the options below are undestood to
 nominate scripts to embed with file names as given.
 
 *-a* _library_::
@@ -87,12 +75,16 @@ The *-C* option changes the working directory for the program so that
 subsequent relative pathnames (file members and libraries) are found
 relative that working directory.
 
-SEE ALSO
---------
+== NOTES
+
+Note that _ar_ typically adds members using their basenames. With
++packnl+ packaging the added modules would thus be loaded by
+basenames.
+
+== SEE ALSO
 
 *newlisp*, *ar*
 
-AUTHOR
-------
+== AUTHOR
 
 Ralph Ronnquist <ralph.ronnquist@gmail.com>