another set of cleanup edits for environment variables in the manual.

doc/manual/environ.tex

@@ -3,36 +3,40 @@
 \chapter{Environment Variables}
 
 \HPCToolkit{}'s measurement subsystem decides what and how to measure
-using information it obtains from environment variables.  When using
+using information it obtains from environment variables.  
+This chapter describes all of the environment variables that control
+\HPCToolkit's measurement subsystem. 
+
+When using
 \HPCToolkit{}'s \hpcrun{} script to measure the performance of
 dynamically-linked executables, \hpcrun{} takes information passed
 to it in command-line arguments and communicates it to \HPCToolkit{}'s
 measurement subsystem by appropriately setting environment variables.
 To measure statically-linked executables, one first adds \HPCToolkit's
 measurement subsystem to a binary as it is linked by using \HPCToolkit's
-\hpclink script. Prior to launching a statically-linked binary that
-includes \HPCToolkit's measurement subsystem, environment variables
-must be set manually by the user prior to launching an application.
-This section describes all of the environment variables that control
-\HPCToolkit's measurement subsystem. Section~\ref{user-env} describes
+\hpclink{} script. Prior to launching a statically-linked binary that
+includes \HPCToolkit's measurement subsystem, a user 
+must manually set environment variables.
+
+Section~\ref{user-env} describes
 environment variables of interest to users. Section~\ref{system-env}
 describes environment variables designed for use by \HPCToolkit{}
 developers. In some cases, \HPCToolkit's developers will ask a user
-to set some of these environment variables to generate a detailed error 
+to set some of the environment variables described in Section~\ref{system-env} to generate a detailed error 
 report when problems arise.
 
 \section{Environment Variables for Users}
 \label{user-env}
 
 \paragraph{HPCRUN\_EVENT\_LIST.}
 
-This environment variable is used provide
-HPCToolkit's measurement library with a set of sample (event, period)
-pairs that will be used for sample-based measurement. HPCRUN\_EVENT\_LIST
-must be set otherwise HPCToolkit's measurement facility will terminate
+This environment variable is used provide a set of (event, period)
+pairs that will be used to configure \HPCToolkit's measurement subsystem to perform 
+asynchronous sampling.  The HPCRUN\_EVENT\_LIST environment variable
+must be set otherwise HPCToolkit's measurement subsystem will terminate
 execution. If an application should run with sampling disabled,
 HPCRUN\_EVENT\_LIST should be set to NONE. Otherwise, HPCToolkit's
-measurement library expects an event list of the form shown below.
+measurement subsystem expects an event list of the form shown below.
 $$event1[@period1];...;eventN[@periodN]$$ As denoted by the
 square brackets, periods are optional. The default period is 1
 million.
@@ -46,7 +50,7 @@ \section{Environment Variables for Users}
 \paragraph{HPCRUN\_TRACE.}
 
 If this environment variable is set, HPCToolkit's measurement
-facility will collect a trace of sample events as part of a measurement
+subsystem will collect a trace of sample events as part of a measurement
 database in addition to a profile. HPCToolkit's hpctraceviewer
 utility can be used to view the trace after the measurement database
 are processed with either HPCToolkit's hpcprof or hpcprofmpi
@@ -57,7 +61,7 @@ \section{Environment Variables for Users}
 
 \paragraph{HPCRUN\_OUT\_PATH}
 
-If this environment variable is set, HPCToolkit's measurement library
+If this environment variable is set, HPCToolkit's measurement subsystem
 will use the value specified as the name of the directory where
 output data will be recorded. The default directory for a command
 $command$ running under control of a job launcher with as job ID
@@ -71,15 +75,15 @@ \section{Environment Variables for Users}
 Flags to set output path with \hpcrun: \verb|-o/--output| $directoryName$
 
 \paragraph{HPCRUN\_PROCESS\_FRACTION}
-
+\sloppy
 If this environment variable is set, \HPCToolkit's measurement
-library will measure only a fraction of an execution’s processes.
+subsystem will measure only a fraction of an execution’s processes.
 The value of HPCRUN\_PROCESS\_FRACTION may be written as a a floating
 point number or as a fraction.  So, '0.10' and '1/10' are equivalent.
 If HPCRUN\_PROCESS\_FRACTION is set to a value with an unrecognized
-format, \HPCToolkit's measurement library will use the default
+format, \HPCToolkit's measurement subsystem will use the default
 probability of 0.1. For each process, \HPCToolkit's measurement
-library will generate a pseudo-random value in the range [0.0, 1.0).
+subsystem will generate a pseudo-random value in the range [0.0, 1.0).
 If the generated random number is less than the value of
 HPCRUN\_PROCESS\_FRACTION, then \HPCToolkit{} will collect performance
 measurements for that process.
@@ -90,16 +94,16 @@ \section{Environment Variables for Users}
 \paragraph{HPCRUN\_MEMLEAK\_PROB}
 
 If this environment variable is set, \HPCToolkit's measurement
-library will measure only a fraction of an execution’s memory
+subsystem will measure only a fraction of an execution’s memory
 allocations, e.g., calls to \verb|malloc|, \verb|calloc|, \verb|realloc|,
 \verb|posix_memalign|, \verb|memalign|, and valloc. All allocations
 monitored will have their corresponding calls to free monitored as
 well. The value of HPCRUN\_MEMLEAK\_PROB may be written as a a
 floating point number or as a fraction.  So, '0.10' and '1/10' are
 equivalent. If HPCRUN\_MEMLEAK\_PROB is set to a value with an
-unrecognized format, \HPCToolkit's measurement library will use the
+unrecognized format, \HPCToolkit's measurement subsystem will use the
 default probability of 0.1. For each memory allocation, \HPCToolkit's
-measurement library will generate a pseudo-random value in the range
+measurement subsystem will generate a pseudo-random value in the range
 [0.0, 1.0). If the generated random number is less than the value
 of HPCRUN\_MEMLEAK\_PROB, then \HPCToolkit{} will monitor that
 allocation.
@@ -110,7 +114,7 @@ \section{Environment Variables for Users}
 \paragraph{HPCRUN\_DELAY\_SAMPLING}
 
 \sloppy
-If this environment variable is set, HPCToolkit's measurement library
+If this environment variable is set, HPCToolkit's measurement subsystem
 will initialize itself but not begin measurement using sampling
 until the program turns on sampling by calling
 \verb|hpctoolkit_sampling_start()|. To measure only a part of a
@@ -124,7 +128,7 @@ \section{Environment Variables for Users}
 \paragraph{HPCRUN\_RETAIN\_RECURSION}
 
 Unless this environment variable is set, by default HPCToolkit's
-measurement library will summarize call chains from recursive calls
+measurement subsystem will summarize call chains from recursive calls
 at a depth of two. Typically, application developers have no need
 to see performance attribution at all recursion depths when an
 application calls recursive procedures such as quicksort. Setting
@@ -137,7 +141,7 @@ \section{Environment Variables for Users}
 
 \paragraph{HPCRUN\_MEMSIZE}
 
-If this environment variable is set, HPCToolkit's measurement library
+If this environment variable is set, HPCToolkit's measurement subsystem
 will allocate memory for measurement data in segments using the
 value specified for HPCRUN\_MEMSIZE (rounded up to the nearest
 enclosing multiple of system page size) as the segment size. The
@@ -148,7 +152,7 @@ \section{Environment Variables for Users}
 
 \paragraph{HPCRUN\_LOW\_MEMSIZE}
 
-If this environment variable is set, HPCToolkit's measurement library
+If this environment variable is set, HPCToolkit's measurement subsystem
 will allocate another segment of measurement data when the amount
 of free space available in the current segment is less than the
 value specified by HPCRUN\_LOW\_MEMSIZE. The default for low memory
@@ -163,10 +167,10 @@ \section{Environment Variables for Developers}
 
 \paragraph{HPCRUN\_WAIT}
 
-If this environment variable is set, HPCToolkit's measurement library
+If this environment variable is set, HPCToolkit's measurement subsystem
 will spin wait for a user to attach a debugger. After attaching a
 debugger, a user can set breakpoints or watchpoints in the user
-program or HPCToolkit's measurement library before continuing
+program or HPCToolkit's measurement subsystem before continuing
 execution. To continue after attaching a debugger, use the debugger
 to set the program variable DEBUGGER\_WAIT=0 and then continue.
 Note: Setting HPCRUN\_WAIT can only be cleared by a debugger
@@ -177,12 +181,12 @@ \section{Environment Variables for Developers}
 \paragraph{HPCRUN\_DEBUG\_FLAGS}
 
 \HPCToolkit{} supports a multitude of debugging flags that enable a
-developer to log information about HPCToolkit's measurement facility
+developer to log information about HPCToolkit's measurement subsystem
 as it records sample events. If HPCRUN\_DEBUG\_FLAGS is set, this
 environment variable is expected to contain a list of tokens separated
 by a space, comma, or semicolon. If a token is the name of a debugging
 flag, the flag will be enabled, it will cause HPCToolkit's measurement
-facility to log messages guarded with that flag as an application
+subsystem to log messages guarded with that flag as an application
 executes. The complete list of dynamic debugging flags can be found
 in HPCToolkit's source code in the file
 src/tool/hpcrun/messages/messages.flag-defns. A special flag value
@@ -203,11 +207,11 @@ \section{Environment Variables for Developers}
 \paragraph{HPCRUN\_ABORT\_TIMEOUT}
 
 If an execution hangs when profiled with HPCToolkit's measurement
-facility, the environment variable HPCRUN\_ABORT\_TIMEOUT can be
+subsystem, the environment variable HPCRUN\_ABORT\_TIMEOUT can be
 used to specify the number of seconds that an application should
 be allowed to execute. After executing for the number of seconds
 specified in HPCRUN\_ABORT\_TIMEOUT, HPCToolkit's measurement
-facility will forcibly terminate the execution and record a core
+subsystem will forcibly terminate the execution and record a core
 dump (assuming that core dumps are enabled) to aid in debugging.
 
 \parg
@@ -218,10 +222,10 @@ \section{Environment Variables for Developers}
 \paragraph{HPCRUN\_QUIET}
 
 If this unfortunately-named environment variable is set, HPCToolkit's
-measurement facility will turn on a default set of dynamic debugging
+measurement subsystem will turn on a default set of dynamic debugging
 variables to log information about HPCToolkit's stack unwinding
 based on on-the-fly binary analysis. If set, HPCToolkit's measurement
-facility log information associated with the following debug flags:
+subsystem log information associated with the following debug flags:
 TROLL (when a return address was not found algorithmically
 and \HPCToolkit{} begins looking for possible return address values
 on the call stack), SUSPICIOUS\_INTERVAL (when an x86 unwind recipe