Changeset 5965 for trunk/glueforge/glueforge.in

Timestamp:

Jan 10, 2006, 4:39:16 PM (21 years ago)

Author:

jhoblitt

Message:

doc update
2006 copyright update

File:

• trunk/glueforge/glueforge.in (modified) (10 diffs)

trunk/glueforge/glueforge.in

@@ -1 +1 @@
 #!/usr/bin/env perl
 
-# Copyright (C) 2005  Joshua Hoblitt
+# Copyright (C) 2005-2006  Joshua Hoblitt
 #
-# $Id: glueforge.in,v 1.41 2006-01-11 02:06:24 jhoblitt Exp $
+# $Id: glueforge.in,v 1.42 2006-01-11 02:39:16 jhoblitt Exp $
 
 use strict;
@@ -297 +297 @@
 =head1 NAME
 
-@PACKAGE_NAME@ - auto-generate 'meta' database bindings
+@PACKAGE_NAME@ - auto-generate Pan-STARRS IPP 'meta' database bindings
 
 =head1 SYNOPSIS
@@ -305 +305 @@
 =head1 DESCRIPTION
 
-This program generates a set of database table specific bindings in the ANSI C
-language.  The code generated is largely just wrapper functions around the
-C<pslib> C<DB> API.  A simple table description is read in and a directory
-containing a complete, distributable software package is created.
+This program generates a set of database table format specific bindings in the
+ANSI C language.  The code generated is largely just wrapper functions around
+the C<pslib> C<psDB> API.  Table information is read in from a configuration
+file in the pslib C<MetadataConfig> format.  A complete autotools configured
+package that builds both static & shared libraries is generated.
 
 =head2 Features
@@ -320 +321 @@
 =item * Installs a pkgconfig C<.pc> data file.
 
-=item * Includes a table specific autotest test suite.
+=item * Includes a table format specific autotest test suite.
 
 =item * Builds both shared and static libraries by default.
@@ -338 +339 @@
 =item * Functions to insert, select, and pop to/from FITS files.
 
-=item * Functions to convert between row structs and C<psMetadata>s.
+=item * Functions to convert between row structs and pslib C<psMetadata>s.
 
 =back
@@ -344 +345 @@
 =head1 TABLE DESCRIPTION FORMAT
 
-A simple config files specifies the name of the table, the name and types of
-all columns, and can optional specify which column are to be used as indexes.
-These C<Table Description> files are in the C<Configuration files> format as
-described in C<PSDC-430-007>.
-
-=head2 Example table description
+There are two slightly different configuration file forms.  A C<simple> format
+for describing a single table and a C<complex> format for describing more then
+one table and/or configuring specific details as to how the package is
+generated.  The syntax for both of these forms follows the C<Configuration
+files> format as described in C<PSDC-430-007>.
+
+=head2 Simple configuration
+
+A simple config file specifies the name of the table, the name and types of all
+columns, and can optionally specify which column(s) are to be used as indexes.
+
+=head2 Example simple configuration
 
     table   STR     foo
@@ -372 +379 @@
 database bindings.
 
+=head2 Complex configuration
+
+A complex config file consists of a series of C<METADATA> blocks.  One (and
+only one) of these blocks I<must> be named C<glueforge>. This block
+contains the global package configuration data.  Only the keys C<pkg_name> and
+C<pkg_namespace> are allowed in this block and they are both required.
+
+All other C<METADATA> blocks describe a single table with the name of the
+C<METATA> block being the tables name.  Otherwise, the format of items
+contained in a C<METADATA> block is the same as for the simple configuration.
+
+Note that nested C<METADATA> blocks are not allowed.
+
+=head2 Example complex configuration
+
+glueforge METADATA
+    pkg_name        STR  foodb 
+    pkg_namespace   STR  foo
+END
+
+foo METADATA
+    foo     STR     60      # Primary Key
+    bar     S32     0 
+    baz     F32     0.0
+    boing   F64     0.0
+    zot     BOOL    t       # Key
+END
+
+bar METADATA
+    zot     BOOL    t       # Key
+    boing   F64     0.0
+    baz     F32     0.0
+    bar     S32     0 
+    foo     STR     60      # Primary Key
+END
+
 =head1 OPTIONS
 
@@ -394 +437 @@
 =back
 
+=head1 BUGS
+
+The format of configuration files is not rigorously checked.  Improperly
+formatted files may not be caught and cause random (possibly silent) errors
+and/or improperly code generation.
+
 =head1 CREDITS
 
@@ -408 +457 @@
 =head1 COPYRIGHT
 
-Copyright (C) 2005  Joshua Hoblitt.  All rights reserved.
+Copyright (C) 2005-2006  Joshua Hoblitt.  All rights reserved.
 
 This program is free software; you can redistribute it and/or modify it under
@@ -428 +477 @@
 =head1 SEE ALSO
 
-L<PS:IPP::Metadata::Config>
+C<pslib>, C<PSDC-430-007>. L<PS:IPP::Metadata::Config>
 
 =cut