minor code cleanup, update lots of documentation

ChangeLog

@@ -1,3 +1,14 @@
+2004-11-12  Albert Chu  <[email protected]>
+
+	* README: Updated with better descriptions.
+
+	* TUTORIAL: Fixed wording in a few places.
+
+	* genders.spec.in: Updated description.
+
+	* src/libgenders/genders_query.y (_calc_complement, _calc_query):
+	Move destroying of hostlist from _calc_complement to _calc_query.
+
 2004-11-10  Albert Chu  <[email protected]>
 
 	* src/libgenders/genders_query.y (_calc_query): Handle NULL query

README

@@ -1,35 +1,42 @@
-Genders is a static file cluster configuration database.  This package
-includes a number of libraries useful for parsing a genders database
-in C and Perl programs.  It includes:
+Genders is a static cluster configuration database used for cluster
+configuration management.  It is used by a variety of tools and
+scripts for management of large clusters.  The genders database is
+typically replicated on every node of the cluster. It describes the
+layout and configuration of the cluster so that tools and scripts can
+sense the variations of cluster nodes. By abstracting this information
+into a plain text file, it becomes possible to change the
+configuration of a cluster by modifying only one file.
+
+This package includes:
 
 * libgenders    
-  - A C library which can be linked with -lgenders.  See
+  - A C library for parsing and querying a genders database.  See
     libgenders(3).
 
 * Libgenders.pm
-  - A Perl module developed with Perl Extensions that accesses
-    the C library.  Perl extensions is limited and provides
-    a very strange Perl API.  It is therefore recommended most users
-    use Genders.pm.  See Libgenders(3).
+  - A Perl module developed with Perl Extensions that takes advantage
+    of the already available C library.  Perl extensions is limited
+    and provides an unorthodox Perl API.  It is therefore recommended
+    that users use Genders.pm.  See Libgenders(3).
 
 * Genders.pm
-  - A Perl module that interfaces with Libgenders.pm, hiding away
-    the yuckiness of Libgenders.pm.  See Genders(3).
+  - A Perl module that interfaces with Libgenders.pm, hiding away the
+    ugliness of Libgenders.pm.  See Genders(3).
 
 * nodeattr
-  - A command that parses and outputs information from a genders 
-    database.  See nodeattr(1).
+  - A genders query tool that that parses and outputs information from
+    a genders database.  See nodeattr(1).
 
 * gendlib.pl
-  - Genders Perl API for backwards compatability.  For the most 
-    part used exclusively on site at Lawrence Livermore National 
-    Laboratories.  Probably of no use to outside clusters.  See
+  - Genders Perl API for backwards compatability.  For the most part,
+    this is used exclusively at Lawrence Livermore National
+    Laboratory.  This is probably of no use to anyone else.  See
     gendlib(3).
 
-Comments, patches, fixes, suggestions are always welcome.
+Comments, patches, fixes, suggestions are always welcome.  Please read
+DISCLAIMER and COPYING for copyright and license information.
 
-Please read DISCLAIMER and COPYING for copyright and license
-information.
+For a thorough introduction to Genders, please read the TUTORIAL.
 
 Albert Chu
 [email protected]

TODO

@@ -5,7 +5,8 @@
   o possibly add functionality to genders_parse()  
 - Genders comparison of two files.  Via nodeattr??  
   - Via new function in genders?\
-- Somehow make distcheck work with perlxs.
+- Somehow make distcheck work with perlxs.  Or is this even possible b/c
+  uninstall is not supported by perlxs, sigh :-(
 - Allow attribute values to be overwritten instead of causing errors
   by some flag option of some sort.
   o i.e. 
@@ -14,3 +15,5 @@
     g,h,i               printer=bar
 - Rework to allow multiple hashed attrval mappings?
 - Have genders_getnodes() return nodes in sorted order?
+- Clean things up in general, library state is currently in 
+  a state with multiple hacks placed on top of other hacks.

TUTORIAL

@@ -122,14 +122,13 @@ Nodeattr can usually be found in /usr/bin (Linux RPM) or /admin/scripts
 
 Programming with Genders
 
-Three different APIs have been developed that allow programmers to
-programmatically parse the genders file.  "libgenders" is a C API which
-can be linked by including genders.h and linking the library libgenders.
-"Libgenders" is a Perl extensions interface directly to the C API (with
-minor changes for the inherent differences between C and Perl). "Genders"
-is another Perl API, but offers a more traditional Perl API than
-"Libgenders."  The reader can learn more about these libraries by reading
-the manpages libgenders(3), Libgenders(3), and Genders(3).
+Three different APIs have been developed that allow programmers to parse 
+and query the genders file.  "libgenders" is a C API which can be linked
+by including genders.h and linking the library libgenders. "Libgenders" 
+is a Perl module developed with Perl extensions.  "Genders" is another
+Perl modules, but offers a more traditional Perl API than "Libgenders."
+The reader can learn more about these libraries by reading the manpages
+libgenders(3), Libgenders(3), and Genders(3).
 
 Example: Rc Script
 
@@ -239,7 +238,7 @@ in the cluster.  It then adds them to the NMAP database used by NQS:
 
      #!/usr/bin/perl
      #
-     # $Id: TUTORIAL,v 1.8 2004-04-14 20:58:41 achu Exp $
+     # $Id: TUTORIAL,v 1.9 2004-11-13 19:58:09 achu Exp $
      # $Source: /g/g0/achu/temp/genders-cvsbackup-full/genders/TUTORIAL,v $
      #
 
@@ -284,5 +283,5 @@ Names for other network interfaces on the same node do not appear in the
 genders file.
 
   ------------------------------------------------------------------------
-$Id: TUTORIAL,v 1.8 2004-04-14 20:58:41 achu Exp $
+$Id: TUTORIAL,v 1.9 2004-11-13 19:58:09 achu Exp $
 $Source: /g/g0/achu/temp/genders-cvsbackup-full/genders/TUTORIAL,v $

genders.spec.in

@@ -9,7 +9,14 @@ Prereq: perl
 BuildRoot: %{_tmppath}/%{name}-%{version}-%{release}
 
 %description
-Genders is a static cluster configuration database.  
+Genders is a static cluster configuration database used for cluster
+configuration management.  It is used by a variety of tools and
+scripts for management of large clusters.  The genders database is
+typically replicated on every node of the cluster. It describes the
+layout and configuration of the cluster so that tools and scripts can
+sense the variations of cluster nodes. By abstracting this information
+into a plain text file, it becomes possible to change the
+configuration of a cluster by modifying only one file.
 
 %package compat
 Summary: compatability library 

src/libgenders/genders_query.y

@@ -1,6 +1,6 @@
 %{
 /*****************************************************************************\
- *  $Id: genders_query.y,v 1.15 2004-11-11 00:04:21 achu Exp $
+ *  $Id: genders_query.y,v 1.16 2004-11-13 19:58:09 achu Exp $
  *****************************************************************************
  *  Copyright (C) 2001-2003 The Regents of the University of California.
  *  Produced at Lawrence Livermore National Laboratory (cf, DISCLAIMER).
@@ -354,7 +354,6 @@ _calc_complement(genders_t handle, hostlist_t h)
 
   genders_nodelist_destroy(handle, nodes);
   hostlist_uniq(ch);
-  hostlist_destroy(h);
   return ch;
  cleanup:
   genders_nodelist_destroy(handle, nodes);
@@ -405,12 +404,8 @@ _calc_query(genders_t handle, struct genders_treenode *t)
   if (t->complement) {
     hostlist_t temp;
     temp = _calc_complement(handle, h);
-    if (!temp) {
-      hostlist_destroy(h);
-      h = NULL;
-    }
-    else
-      h = temp;
+    hostlist_destroy(h);
+    h = temp;
   }
   return h;
 }