[Patches] patch: document how to add a new command-line option

[Jonathan Thornburg]

As I discussed in two recent messages on the cactusmaint mailing list,
  http://www.cactuscode.org/mailman/private/cactusmaint/2006-May/021429.html
  http://www.cactuscode.org/mailman/private/cactusmaint/2006-May/021430.html
adding a new command-line option to Cactus is quite error-prone, with
updates required in (at least) 5 different places in the code, not to
mention the Fine Documentation.

The Right Solution would clearly be to drive all the code's command
line handling (short-option parsing, long-option parsing, and help
messages) from a single table.  However, as a hopefully-temporary bandaid
until this is done, the following patch puts a comment at 4 of the 5
places-in-the-code-where-the-list-of-all-command-options-appears pointing
to a longer comment at the 5th place, which lists all 5 places.  This
way a future programmer who goes to add a new command-line option can
at least quickly find all 5 places needing updating.

ciao,

-- 
-- Jonathan Thornburg <jthorn at aei.mpg.de>      
   Max-Planck-Institut fuer Gravitationsphysik (Albert-Einstein-Institut),
   Golm, Germany, "Old Europe"     http://www.aei.mpg.de/~jthorn/home.html      
   "Washing one's hands of the conflict between the powerful and the
    powerless means to side with the powerful, not to be neutral."
                                      -- quote by Freire / poster by Oxfam
-------------- next part --------------
Index: CommandLine.c
===================================================================
RCS file: /cactusdevcvs/Cactus/src/main/CommandLine.c,v
retrieving revision 1.59
diff -u -r1.59 CommandLine.c
--- CommandLine.c	11 May 2006 13:55:51 -0000	1.59
+++ CommandLine.c	28 May 2006 13:10:32 -0000
@@ -61,6 +61,11 @@
 /********************************************************************
  *********************        Defines          **********************
  ********************************************************************/
+
+/*
+ * See comments in  CCTKi_ProcessCommandLine()  for a list of all the
+ * places you have to update if you add a new command-line option.
+ */
 #define CACTUS_COMMANDLINE_OPTIONS                                      \
         "[-h] [-O] [-o paramname] [-L n] [-W n] [-E n] [-r[o|e|oe|eo]] " \
         "[-S] [-T] [-t name] [-parameter-level <level>] [-v] "          \
@@ -538,6 +543,11 @@
 void CCTKi_CommandLineHelp (void)
 {
   char **argv;
+
+  /*
+   * See comments in  CCTKi_ProcessCommandLine()  for a list of all the
+   * places you have to update if you add a new command-line option.
+   */
   const char *commandline_options_description =
     "-h, -help                           : gets this help.\n"
     "-O[v], -describe-all-parameters     : describes all the parameters.\n"
Index: ProcessCommandLine.c
===================================================================
RCS file: /cactusdevcvs/Cactus/src/main/ProcessCommandLine.c,v
retrieving revision 1.36
diff -u -r1.36 ProcessCommandLine.c
--- ProcessCommandLine.c	11 May 2006 13:55:51 -0000	1.36
+++ ProcessCommandLine.c	28 May 2006 13:10:33 -0000
@@ -93,6 +93,19 @@
 @@*/
 int CCTKi_ProcessCommandLine(int *inargc, char ***inargv, tFleshConfig *ConfigData)
 {
+  /*
+   * If you add a new command-line option, you must update (at least)
+   * the following different places in the code:
+   * - the definition of  long_options[]  in this function
+   * - the 3rd argument in the call to  getopt_long_only()  in this function
+   * - the  switch (c)  statement in this function
+   * - the #define of CACTUS_COMMANDLINE_OPTIONS near the top of
+   *   src/main/CommandLine.c
+   * - the help message printed by CCTKi_CommandLineHelp()
+   *   (also in  src/main/CommandLine.c )
+   * You should also update the description of command-line options in the
+   * Cactus Users' Guide, in  doc/UsersGuide/RunningCactus.tex .
+   */
 
   int option_index = 0;
   int c;