zmodload command-line switches and doc organization

["Bart Schaefer" <schaefer@xxxxxxxxxxxxxxxx>]

I'd like to suggest some changes to the options to zmodload.  Below is
formatted text of the reorganized info documentation.  The idea was to
add a -b option (for "builtin") to go with the relatively new -c and -p
options, and then to make -a consistently mean "autoload" as -u means
un(load/define/whatever).  So instead of -a/-c/-p and -au/-cu/-pu, we
have -ab/-ac/-ap mirrored by -ub/-uc/-up.  (I left -a and -au because
they've been around for so long, but changed -L to not generate them.)

It's a three-line deletion in my patched modules.c plus a few characters
knocked out of the doc to make it -b/-c/-p and -ub/-uc/-up, if that's
preferable; however, my thought was that we could make -b/-c/-p (with
neither -a nor -u) perform a listing function, e.g.

     zmodload -b [ -L ] BUILTIN ...
           For each BUILTIN, list the module from which it was loaded
	   (if any).  With -L, list in the form of zmodload commands.

Similarly for -c and -p.  However, I haven't implemented that yet.

No patch yet, I want reaction to the proposed change before I send one.
Independent of the change in switches, what do you think of the doc
layout?

==========

zmodload [ -dL ] [ ... ]
zmodload [ -a [ -bcp [ -I ] ] ] [ -i ] ...
zmodload -u [ -bcdp [ -I ] ] [ -i ] ...
     zmodload performs operations relating to zsh's loadable modules.
     This feature is not available on all operating systems, or on all
     installations on a particular operating system.

     Without arguments all currently loaded binary modules are printed.
     The -L option causes this list to be in the form of a series of
     zmodload commands.

    zmodload [ -i ] NAME ...
    zmodload -u [ -i ] NAME ...
          In the simplest case, zmodload loads a binary module.  The
          module must be in a file with a name consisting of the
          specified NAME followed by a standard suffix, usually
          ".so".  If this can't be found, the NAME is tried without
          the suffix.  If the module to be loaded is already loaded and
          the -i option is given, the duplicate module is ignored.
          Otherwise zmodload prints an error message.

          The NAMEd module is searched for in the same way a command
          is, using $module_path instead of $path.  If NAME
          contains a "/", it will be used as-is, and a path search
          will be performed otherwise.  This behaviour can be modified
          by the PATH_DIRS option.

          With -u, zmodload unloads modules.  The same NAME must be
          given that was given when the module was loaded, but it is not
          necessary for the module to exist in the filesystem.  The
          -i option suppresses the error if the module is already
          unloaded (or was never loaded).

          Each module has a boot and a cleanup function.  The module
          will not be loaded if its boot function fails.  Similarly a
          module can only be unloaded if its cleanup function runs
          successfully.

    zmodload -d [ -L ] [ NAME ]
    zmodload -d NAME DEP ...
    zmodload -ud NAME [ DEP ... ]
          The -d option can be used to specify module dependencies.
          This operation is idempotent regardless of the -i option.
          The modules named in the second and subsequent arguments will
          be loaded before the module named in the first argument.

          With -d and one argument, all dependencies for that module
          are listed.  With -d and no arguments, all module
          dependencies are listed.  This listing is by default in a
          Makefile-like format.  The -L option changes this format to
          a list of zmodload -d commands.

          If -d and -u are both used, dependencies are removed.
          This operation is idempotent regardless of the -i option.
          If only one argument is given, all dependencies for that
          module are removed.

    zmodload -ab [ -L ]
    zmodload -ab [ -i ] NAME [ BUILTIN ... ]
    zmodload -ub [ -i ] BUILTIN ...
          The -ab option defines autoloaded builtins.  It defines the
          specified BUILTINs.  When any of those builtins is called,
          the module specified in the first argument is loaded.  If
          only the NAME is given, one builtin is defined, with the same
          name as the module.  -i suppresses the error if the builtin
          is already defined or autoloaded, regardless of which module
          it came from.

          With -ab and no arguments, all autoloaded builtins are
          listed, with the module name (if different) shown in
          parentheses after the builtin name.  The -L option changes
          this format to a list of zmodload -a commands.

          If -b is used together with the -u option, it removes
          builtins defined with zmodload -ab.  This is only possible
          if the builtin is not yet loaded.  -i suppresses the error
          if the builtin is already removed (or never existed).

    zmodload -ac [ -IL ]
    zmodload -ac [ -iI ] NAME [ COND ... ]
    zmodload -uc [ -iI ] COND ...
          The -ac option is used to define autoloaded condition
          codes. The COND strings give the names of the conditions
          defined by the module. The optional -I option is used to
          define infix condition names. Without this option prefix
          condition names are defined.

          If given no condition names, all defined names are listed (as
          a series of zmodload commands if the -L option is given).

          The -uc option removes definitions for autoloaded
          conditions.

    zmodload -ap [ -L ]
    zmodload -ap [ -i ] NAME [ PARAMETER ... ]
    zmodload -up [ -i ] PARAMETER ...
          The -p option is like the -b and -c options, but makes
          zmodload work on autoloaded parameters instead.

    zmodload -a [ -L ]
    zmodload -a [ -i ] NAME [ BUILTIN ... ]
    zmodload -ua [ -i ] BUILTIN ...
          Equivalent to -ab and -ub.


-- 
Bart Schaefer                                 Brass Lantern Enterprises
http://www.well.com/user/barts              http://www.brasslantern.com