Added man pages for the archives.

diff --git a/lsp-dbus.a.8.adoc b/lsp-dbus.a.8.adoc
new file mode 100644 (file)
index 0000000..1fe8729
--- /dev/null
+++ b/lsp-dbus.a.8.adoc
@@ -0,0 +1,130 @@
+= lsp-dbus.a(8)
+:doctype: manpage
+:revdate: {sys:date "+%Y-%m-%d %H:%M:%S"}
+
+== NAME
+
+lsp-dbus.a - Dbus API for newlisp.
+
+== SYNOPSIS
+
+.With packnl
+packnl _main.lsp_ *-A lsp-misc.a* *-A lsp-dbus.a*
+
+
+.With incore.lsp
+(load "incore.lsp") +
+(archive "lsp-misc.a") +
+(archive "lsp-utils.a") +
+(load "lsp-dbus.lsp")
+
+== DESCRIPTION
+
+*lsp-dbus.a* implements a newlisp API for Dbus. The module includes a
+context *DbusConnection* implementing the connection/authorization
+level and a context *Dbus* that implements the "object modelling"
+level. The software is divided into a couple of different source files
+that are packed together int a _ar_ archive. It also depends on +foop+
+and +prog1+ from +lsp-misc.a+.
+
+=== Essential API
+
+On loading::
+
+The main file, +lsp-dbus.lsp+, includes connection setup and client
+registration as part of its loading. Currently it connects on the
+system bus only. It also installs the funcion +main-loop+ as
++prompt-event+ function for processing any unsolicited messages from
+dbus (so called "signals").
+
+(Dbus _PATH_ [_DESTINATION_])::
+
+The context +Dbus+ is used for identifying remote services which by
+default have coinsiding path _PATH_ and _DESTINATION_ (aka bus name).
+The resulting FOOP object provides a channel for invoking methods.
+
+(:invoke _OBJECT_ _METHOD_ _ARGUMENTS_ _FLAGS_):: The +:invoke+ method
+performs a Dbus +METHOD_CALL+ handshake for the gven _OBJECT_ using
+the given _METHOD_, _ARGUMENTS_and message _FLAGS_, while also polling
+s.c. signal messages from Dbus. The _METHOD_ is given as a string
+composed as "_path_:_interface_._name_(_signature_)", although the
+_path_ and _interface_ parts are optional. If without explicit _path_,
+the _OBJECT_ path is used. If without explicit interface, the method
+will be looked up across all interfaces of the destination path.
++
+The given _ARGUMENTS_ is a list structure that must correspond to the
+given signature. See the MARSHALLING below.
++
+The optional _FLAGS_ is either a bit mask or a list of applicable
+method call flags as Dbus symbols. See METHOD_CALL flags below.
++
+.invoke usage examples
+(:invoke Dbus:ROOT "RequestName(su)" '("my.client" 0))
++
+(:invoke Dbus:ROOT "GetNameOwner(s)" '("org.bluez" 0))
++
+(setf BT (Dbus "/org/bluez")) +
+(:invoke BT "/:org.freedesktop.ObjectManager.GetManagedObjects()") +
+; Note that "org.bluez" here provides the "GetManagedObjects()" +
+; method on the root path, "/", rather than its own path +
+; "/org/bluez".
++
+While this process is waiting for the +METHOD_CALL+ reply it may
+receive signal messsages from +dbus+. These will be added to the list
+of "pending callbacks" that is processed via the +process-all-pending+
+function, either via an explicit call following the handshake or
+"automagically" as part of the +main-loop+ function that gets
+installed as as +prompt-event+ function.
+
+(Dbus:process-all-pending)::
+
+The +process-all-pending+ function processes all pending signal
+messages by invoking their associated handler functions.
+
+(prompt-event Dbus:main-loop)::
+
+The +main-loop+ function is set up as +prompt-event+ function for a
++net-select+ on both stdin and the dbus socket as well as to process
+all pending signal messages. Any input from dbus, which are signal
+messages, are added to the pending list, which also is processed one
+message at a time until empty.
++
+Note that newlisp uses readline for input but that this is not
+activated in +main-loop+. Therefore line editing is not available
+immediately. However the operator may use ^D to leave the main-loop
+and enter the "normal" command line input state for a single line
+input (with line editing), or an initial newline for multi-line input
+that is "submitted" by means of two newlines.
+
+(Dbus:handler _KEY_ _HANDLER_):: This function registers a handler
+callback for a key that is a string composed as
+"path:interface.member(signature)". The handler function takes a
+single argument, which is the list of unmarshalled actual call
+arguments.
+
+=== MARSHALLING
+
+dbus documentation uses the terms "marshalling" and "unmarshalling"
+for the translations of data from/to program data to/from dbus message
+bytes. The data in newlisp mapped straight-forwardly with the special
+note that both "struct" and "array" are held as lists in newlisp. To
+that end, the data for the variant type signature must be wrapped into
+an extra list of the format _(signature value)_ with explcit dbus
+signature string. However, such wrapping does not take place upon
+unmarshalling.
+
+=== METHOD_CALL FLAGS
+
+As per dbus documentation, there are three +METHOD_call+ flags:
++Dbus:NO_REPLY_EXPECTED+, +Dbus:NO_AUTO_START+ and
++Dbus:ALLOW_INTERACTIVE_AUTHORIZATION. Each of these correspond to a
+bit position in the _FLAGS_ mask and they are combined with bit-OR.
+Refer to dbus docuemntation for further details.
+
+== SEE ALSO
+
+*newlisp*, *packnl*, *incore.lsp*
+
+== AUTHOR
+
+Ralph Ronnquist <ralph.ronnquist@gmail.com>

diff --git a/lsp-misc.a.8.adoc b/lsp-misc.a.8.adoc
new file mode 100644 (file)
index 0000000..5dd0b04
--- /dev/null
+++ b/lsp-misc.a.8.adoc
@@ -0,0 +1,103 @@
+= lsp-misc.a(8)
+:doctype: manpage
+:revdate: {sys:date "+%Y-%m-%d %H:%M:%S"}
+
+== NAME
+
+lsp-misc.a - Misceallaneous useful functions.
+
+== SYNOPSIS
+
+.With packnl (example)
+packnl _main.lsp_ *-A lsp-misc.a*
+
+
+.With incore.lsp
+(load "incore.lsp") +
+(archive "lsp-misc.a") +
+(load "misc.lsp")
+
+== DESCRIPTION
+
+*lsp-misc.a* provides a few global utility functions.
+
+=== misc.lsp API
+
+(prog1 [_term_]*)::
+
+The *prog1* function is like a *begin* function except that it returns
+the value of the first term rather than the last.
+
+(die [_N_ [_term_]])::
+
+The *die* function printes to stderr the join of term values as
+strings with space separation, and if _N_ is a number, then the
+function exits the program with that return code.
++
+.Example of stderr logging
+(die nil 'This "is" 'printed "to stderr")
+
+(octal-byte _B_)::
+Print binary byte as octal or as ASCII character [32-126].
+
+(octals-string _S_)::
+Print string as a succesion of +octal-byte+.
+
+(human-byte _B_)::
+Return byte code as printable (string) or as code (number).
+
+(human-bytes _BL_)::
+
+Return a list of human-byte elements from a list of byte codes but
+also joining consecutive string elements to form packed strings.
+
+=== foop.lsp API
+
+This newlisp module provides Functional Object-Oriented Programming
+(FOOP) modelling support.
+
+FOOP is an abstraction overlay using the newlisp context notion as a
+simile to the _class_ notion in genuine object-oriented programming
+languages. This is set out in newlisp by means of the representation
+principle that an instance of a FOOP "class" (i.e. context) is a list
+headed by the context itself, and followed by the "member values".
+
+FOOP further includes by the "method invocation" syntax where a
+function is preceded by ':' and then followed by the instance
+concerned before actual function arguments. That instance is then
+stoved away as implicitly available via the (self) function, and the
+member values accessible via index, e.g. the term (self 3) refers to
+the third member of the instance. The self references are
+destructively assignable with setf.
+
+This modelling support adds member name declaration together with
+automatic getter and setter defintions. The (FOOP ...) term is used
+for declaring member names in order. For example:
+
+(FOOP [_name_])::
+
+*FOOP* is like a language extension to declare the field names of a
+FOOP class, and thereby gain "get" and "set" functions generated with
+the respective naming formats (:%name obj) and (:!name obj value).
+
+.illustration 
+----
+(context 'MAIN:EX)
+(FOOP here there more)
+(define (EX HERE THERE MORE) (list (context) HERE THERE MORE))
+
+(context MAIN)
+(setf A (EX 1 2 3))
+--> A = (EX 1 2 3)
+(:!there A 4)
+--> A = (EX 1 4 3)
+----
+
+
+== SEE ALSO
+
+*newlisp*
+
+== AUTHOR
+
+Ralph Ronnquist <ralph.ronnquist@gmail.com>