Various manual fixes.

[mLib] / README

diff --git a/README b/README
index aabf1780bccf3a8c8cdda72b4ddb4a8fa0848ad2..e64fd10ebdf77431c675df5b6b846dfa0f11a418 100644 (file)
--- a/README
+++ b/README
@@ -4,13 +4,20 @@ mLib
 Overview
 
        mLib is a collection of bits of code I've found handy in various
 Overview
 
        mLib is a collection of bits of code I've found handy in various

-       programs.  With a few very minor exceptions, the routines are
-       highly portable, and mostly strictly conformant.
+       programs.  Once upon a time, almost all of the code was nearly-
+       strictly conforming C.  Since then, a big pile of Unix-specific
+       code's been added, with a particularly strong networking
+       emphasis.  The Unix-specific code is targetted at sensible
+       POSIX-conforming systems, and should port easily.

 
        My programming style is probably what you'd describe as
        `unconventional'.  I'm skeptical about object-orientation, and
        not a huge fan of over-hiding information of any kind.  The
 
        My programming style is probably what you'd describe as
        `unconventional'.  I'm skeptical about object-orientation, and
        not a huge fan of over-hiding information of any kind.  The

-       structure and interface of the library reflects these views.
+       structure and interface of the library reflects these views.  On
+       the other hand, I like documentation quite a lot.
+
+
+Documentation

 
        There is now a (hopefully fairly good) set of manual pages for
        mLib.  The manual isn't installed by default since it takes a
 
        There is now a (hopefully fairly good) set of manual pages for
        mLib.  The manual isn't installed by default since it takes a


@@ -21,6 +28,18 @@ Overview
 
        (after everything else is built, obviously).
 
 
        (after everything else is built, obviously).
 

+       There's also documentation in the header files.  The header file
+       comments were, in general, written at the same time as the code.
+       This has the disadvantage that they focus at a fairly low level,
+       and use terminology relating to the implementation rather than
+       the interface.
+
+       The header file comments can be handy for quick browsing.
+       However, the manual pages are considered the authoritative
+       source of information about the programming interface.  If you
+       have to look at the source code, it usually means that my
+       documentation or interface design is wrong.
+

 
 Quick tour
 
 
 Quick tour
 


@@ -37,7 +56,7 @@ Quick tour
            for C.
 
          * `alloc.h' declares some thin veneers over `malloc' and
            for C.
 
          * `alloc.h' declares some thin veneers over `malloc' and

-           `free' which raise exceptions for out-of-memory conditions,
+           friends which raise exceptions for out-of-memory conditions,

            so you don't have to bother trapping these in main code.
 
        Above this are the memory tracking system, the suballocator, and
            so you don't have to bother trapping these in main code.
 
        Above this are the memory tracking system, the suballocator, and


@@ -49,7 +68,9 @@ Quick tour
            with information about who allocated them, and keeps track
            of the memory allocated so far.  Most of the time, you don't
            bother compiling this in, and you don't need to care about
            with information about who allocated them, and keeps track
            of the memory allocated so far.  Most of the time, you don't
            bother compiling this in, and you don't need to care about

-           it at all.
+           it at all.  [This may be withdrawn in a later release.  Too
+           much code in mLib doesn't support it properly, and it's not
+           being maintained or documented very well.]

 
          * `sub.h' provides an allocation mechanism for small,
            known-size blocks.  It fetches big chunks from an underlying
 
          * `sub.h' provides an allocation mechanism for small,
            known-size blocks.  It fetches big chunks from an underlying


@@ -65,6 +86,12 @@ Quick tour
            function), and permits arbitrary data blocks in both the
            keys and values.  It seems fairly quick.
 
            function), and permits arbitrary data blocks in both the
            keys and values.  It seems fairly quick.
 

+         * `hash.h' provides the underpinnings of the `sym' hashtable.
+           It's a completely generic hashtable skeleton.  It provides
+           the basics like rehashing when the table is full and so on.
+           It needs a fair bit of work to turn into a usable data
+           structure, though, which is what `sym' is for.
+

          * `dstr.h' provides a dynamically sized string type.  In the
            rather paltry tests I've run, it seemed faster than
            libstdc++'s string type, but I shouldn't read too much into
          * `dstr.h' provides a dynamically sized string type.  In the
            rather paltry tests I've run, it seemed faster than
            libstdc++'s string type, but I shouldn't read too much into


@@ -73,12 +100,11 @@ Quick tour
            string looks sane before you start expecting any of the
            functions or macros to work.
 
            string looks sane before you start expecting any of the
            functions or macros to work.
 

-         * `dynarray.h' is a big nasty macro which defines functions
-           capable of dealing with dynamically-sized arrays of
-           arbitrary types.  (You build a new set of functions for each
-           type.  Think of it as a hacky C++ template-a-like.)  The
-           arrays are sparse, but not ever-so efficient in terms of
-           look-up time.
+         * `darray.h' implements dynamically growing arrays which can be
+           extended at both ends, a bit like Perl's.  It replaces the
+           old `dynarray.h' which wasn't very good.  However, `darray's
+           arrays are not sparse.  Maybe a good sparse array module
+           will be added later.

 
        At the same conceptual level, there's some code for handling
        multiplexed I/O.  Although the core is named `sel', and it uses
 
        At the same conceptual level, there's some code for handling
        multiplexed I/O.  Although the core is named `sel', and it uses


@@ -108,10 +134,35 @@ Quick tour
            connect, and adds itself to the select system.  When the
            connect completes, you get given the file descriptor.
 
            connect, and adds itself to the select system.  When the
            connect completes, you get given the file descriptor.
 

+         * `ident.h' is an RFC931 (identd) client.
+
+         * `bres.h' is a background name resolver.  It keeps a pool of
+           resolver processes to answer queries.
+
+         * `sig.h' traps signals and dispatches them through the
+           event-driven `sel' system.
+

        Then there's a bunch of other stuff.
 
        Then there's a bunch of other stuff.
 

+         * `base32.h' does Base32 encoding and decoding.    This is a
+           mad thing one needs for sha1 URNs.
+
+         * `base64.h' does Base64 encoding and decoding.
+
+         * `bits.h' provides some portable bit manipulation macros.
+

          * `crc32.h' declares the 32-bit CRC used by `sym'.
 
          * `crc32.h' declares the 32-bit CRC used by `sym'.
 

+         * `env.h' provides some routines for handling environment
+           variables in a hashtable.
+
+         * `fdflags.h' encapsulates some traditional little dances with
+           fcntl when playing with nonblocking files.
+
+         * `hex.h' does hex encoding and decoding.
+
+         * `lock.h' does fcntl-style locking with a timeout.
+

          * `quis.h' works out the program name from the value of
            `argv[0]' and puts it in a variable for everything else to
            find.
          * `quis.h' works out the program name from the value of
            `argv[0]' and puts it in a variable for everything else to
            find.


@@ -119,6 +170,9 @@ Quick tour
          * `report.h' reports fatal and nonfatal errors in the standard
            Unixy way.
 
          * `report.h' reports fatal and nonfatal errors in the standard
            Unixy way.
 

+         * `str.h' provides some occasionally useful string-
+           manipulation toys.
+

          * `trace.h' provides a simple tracing facility, which can be
            turned on and off both at compile- and run-time.
 
          * `trace.h' provides a simple tracing facility, which can be
            turned on and off both at compile- and run-time.
 


@@ -128,11 +182,16 @@ Quick tour
            results.  It's particularly handy with cryptographic
            algorithms, I find.
 
            results.  It's particularly handy with cryptographic
            algorithms, I find.
 

+         * `unihash.h' provides universal hashing.  This is useful in
+           hash tables for preventing uneven loading even in the
+           presence of a malicious person choosing the hash keys.

 
 

-Future directions
-
-       I'm going to write some manual pages.  Promise.
+         * `url.h' does url-encoding, which armours mostly-textual
+           name/value pairs so they contain no whitespace characters.

 
 

+-- [mdw]

 
 

-                                                               Mark Wooding
-                                                               mdw@nsict.org
+\f
+Local variables:
+mode: text
+End: