[cig-commits] r5269 - mc/3D/CitcomS/trunk/doc/manual

[leif at geodynamics.org]

Author: leif
Date: 2006-11-14 18:06:20 -0800 (Tue, 14 Nov 2006)
New Revision: 5269

Modified:
   mc/3D/CitcomS/trunk/doc/manual/citcoms.lyx
Log:
Corrections to the section, "Changing Parameters".


Modified: mc/3D/CitcomS/trunk/doc/manual/citcoms.lyx
===================================================================
--- mc/3D/CitcomS/trunk/doc/manual/citcoms.lyx	2006-11-15 01:14:49 UTC (rev 5268)
+++ mc/3D/CitcomS/trunk/doc/manual/citcoms.lyx	2006-11-15 02:06:20 UTC (rev 5269)
@@ -2908,12 +2908,12 @@
 \end_layout
 
 \begin_layout Section
-Using CitComS.py without Pyre
+Using CitComS without Pyre
 \end_layout
 
 \begin_layout Standard
-Whether you build CitComS.py with or without the Pyre framework, two binary
- executables 
+When you build CitComS without the Pyre framework, two binary executables
+ 
 \family typewriter
 CitcomSRegional
 \family default
@@ -2921,7 +2921,7 @@
 \family typewriter
 CitcomSFull
 \family default
- are installed under the 
+ are built and (optionally) installed under the 
 \family typewriter
 bin
 \family default
@@ -2930,7 +2930,7 @@
 /usr/local/bin
 \family default
 ).
- These programs do not use the Pyre framework.
+ These programs do not use Python or the Pyre framework.
  Their usage is the same:
 \end_layout
 
@@ -2965,11 +2965,12 @@
 \end_layout
 
 \begin_layout Standard
-If you build CitComS.py with the Pyre framework, a program 
+If you build CitComS.py with the Pyre framework, a Python script named 
 \family typewriter
 citcoms
 \family default
- is installed under the 
+ is generated in the top-level build directory and (optionally) installed
+ under the 
 \family typewriter
 bin
 \family default
@@ -2978,17 +2979,16 @@
 /usr/local/bin
 \family default
 ).
- The program 
+ The 
 \family typewriter
 citcoms
 \family default
- is used for running both the regional and full spherical models.
- The program 
+ script is used for running both the regional and full spherical models.
+ Executed without any command line options, 
 \family typewriter
 citcoms
 \family default
- can be executed without any command line options and will run a regional
- model with default parameters.
+ will run a regional model with default parameters.
  It can also run a full spherical model if the correct parameters are set
  (see Section 
 \begin_inset LatexCommand \vref{sec:Cookbook-1:-Global}
@@ -2999,7 +2999,8 @@
 \end_layout
 
 \begin_layout Standard
-On input, CitComS.py needs numerous parameters specified (see Appendix 
+On input, CitComS.py needs numerous parameters to be specified (see Appendix
+ 
 \begin_inset LatexCommand \vref{cha:Appendix-A:-Input}
 
 \end_inset
@@ -3030,9 +3031,15 @@
 
 \begin_layout Standard
 There are several methods to set the input parameters for CitComS.py: via
- the command line or by using a .cfg or .pml file.
- Command line input will override any input contained in a .cfg file, which
- will in turn override input in a .pml file.
+ the command line or by using a 
+\family typewriter
+.cfg
+\family default
+ or 
+\family typewriter
+.pml
+\family default
+ file.
 \end_layout
 
 \begin_layout Subsection
@@ -3040,7 +3047,7 @@
 \end_layout
 
 \begin_layout Standard
-Pyre uses the following syntax to change properties from the command lines.
+Pyre uses the following syntax to change properties from the command line.
  To change the value of a property of a component, use:
 \end_layout
 
@@ -3077,12 +3084,11 @@
 \begin_layout Standard
 Entering all those parameters via the command line involves the risk of
  typographical errors, which can lead to undesired results.
- You may find it easier to write a brief input file that contains the parameters.
- Since v2.1, the input parameters can be saved in a 
+ You may find it easier to write a brief a 
 \family typewriter
 .cfg
 \family default
- file.
+ input file that contains the parameters.
  This file has a format similar to a Windows INI file.
  The file is composed of one or more sections which are formatted as follows:
 \end_layout
@@ -3104,9 +3110,13 @@
 .cfg
 \family default
  files for your work.
- The contents are collected by default in a vim editor and all of the parameters
- wil be output on the termination of your run in a 
+ The files are syntax-colored by the 
 \family typewriter
+vim
+\family default
+ editor.
+ Upon termination of each run, all of the parameters are logged in a 
+\family typewriter
 .cfg
 \family default
  file.
@@ -3115,7 +3125,7 @@
 \begin_layout Subsection
 Using a 
 \family typewriter
-CitcomS.pml
+.pml
 \family default
  File
 \end_layout
@@ -3125,9 +3135,8 @@
 \family typewriter
 .pml
 \family default
- file is an XML file that assigns values to properties, components, and
- facilities in an application, allowing a user to override the default values
- assigned in the respective inventories.
+ file is an XML file that specifies parameter values in a highly structured
+ format.
  The file is composed of nested sections which are formatted as follows:
 \end_layout
 
@@ -3147,56 +3156,91 @@
 </component>
 \end_layout
 
+\begin_layout Subsection
+Specfication and Placement of Configuration Files
+\end_layout
+
 \begin_layout Standard
-The name of the 
+Configuration files of either type may be specified on the command line:
+\end_layout
+
+\begin_layout LyX-Code
+$ citcoms example.cfg
+\end_layout
+
+\begin_layout LyX-Code
+$ citcoms example.pml
+\end_layout
+
+\begin_layout Standard
+In addition, the Pyre framework searches for configuration files named 
 \family typewriter
-.pml
+CitcomS.cfg
 \family default
- file must be 
+ or 
 \family typewriter
 CitcomS.pml
 \family default
-.
- There are several places to put the 
-\family typewriter
-CitcomS.pml
-\family default
- files, depending on the scope you would like them to have.
+ in several predefined locations.
+ You may put settings in any or all of these locations, depending on the
+ scope you want the settings to have:
 \end_layout
 
 \begin_layout Enumerate
-In 
+
 \family typewriter
-PREFIX/etc/CitcomS
+PREFIX/etc/CitcomS.cfg
 \family default
- directory, meant to override variables system-wide.
+ and 
+\family typewriter
+PREFIX/etc/CitcomS.pml
+\family default
+, for system-wide settings;
 \end_layout
 
 \begin_layout Enumerate
-In 
+
 \family typewriter
-$HOME/.pyre/CitcomS
+$HOME/.pyre/CitcomS.cfg
 \family default
- directory, meant to override variables for just one user.
+ and 
+\family typewriter
+$HOME/.pyre/CitcomS/CitcomS.pml
+\family default
+, for user settings and preferences;
 \end_layout
 
 \begin_layout Enumerate
-In the current directory, meant to be local overrides.
+the current directory (
+\family typewriter
+./CitcomS.cfg
+\family default
+ and 
+\family typewriter
+./CitcomS.pml
+\family default
+), for local overrides.
  
 \end_layout
 
 \begin_layout Standard
-You can have multiple 
+Parameters given directly on the command line will override any input contained
+ in a 
 \family typewriter
-CitcomS.pml
+.cfg
 \family default
- files in different directories.
+ or 
+\family typewriter
+.pml
+\family default
+ configuration file.
+ Configuration files given on the command line override all others.
  The 
 \family typewriter
-CitcomS.pml
+CitcomS.*
 \family default
- in 3 will override all the others, 2 overrides 1, and 1 verrides the default.
- 
+ configuration files placed in (3) will override those in (2), (2) overrides
+ (1), and (1) overrides only the built-in defaults.
 \end_layout
 
 \begin_layout Section