6f32b1ba12ffa50bdffefd5cc88ea12141f1334a
kent
  Sat Sep 14 14:33:04 2019 -0700
Started to document how fields work in usage message.  Not complete.  My, this code could use a couple of functions broken up too - logic is a little tortured and long now.  Alas it's gonna be the sort of refactor where the functions are going to have 8 parameters each if I break up the big one.

diff --git src/hg/sqlUpdateRelated/sqlUpdateRelated.c src/hg/sqlUpdateRelated/sqlUpdateRelated.c
index 0828e96..e5475bb 100644
--- src/hg/sqlUpdateRelated/sqlUpdateRelated.c
+++ src/hg/sqlUpdateRelated/sqlUpdateRelated.c
@@ -8,30 +8,40 @@
 #include "fieldedTable.h"
 #include "csv.h"
 #include "jksql.h"
 
 void usage()
 /* Explain usage and exit. */
 {
 errAbort(
   "sqlUpdateRelated - Update a bunch of tables in a kind of careful way based out of tab \n"
   "separated files.  Handles foreign key and many-to-many relationships with a multitude\n"
   "of @ signs.  Currently only works with mysql cause going through jksql\n"
   "usage:\n"
   "   sqlUpdateRelated database tableFiles\n"
   "options:\n"
   "   -missOk - if set, tableFiles mentioned that don't exist are skipped rather than erroring\n"
+  "The tableFiles are in a interesting and peculiar format.  The first line with the field name\n"
+  "ends up controlling this program.  If a field starts with just a regular letter all is as\n"
+  "you may expect,  the field just contains data to load.  However if the field starts with\n"
+  "a special char, special things happen.  In particular\n"
+  "   ? - indicates field is a conditional key field.  Record is only inserted if the value\n"
+  "       for this field is not already present in table\n"
+  "   ! - indicates this is update key field.  Record must already exist,  values in other fields\n"
+  "       are updated.\n"
+  "   @ - indicates a foreign key relationship - see source code until docs are in shape\n"
+  "   @@ - indicates a many-to-many relationship - see source code until docs are in shape"
   );
 }
 
 /* Command line validation table. */
 static struct optionSpec options[] = {
    {"missOk", TRUE},
    {NULL, 0},
 };
 
 struct foreignRef
 /* What we need to handle a foreign key reference */
     {
     struct foreignRef *next;	    // Next in list
     char *nativeFieldName;	    // Name in the current table
     char *foreignTable;		    // Foreign table name