@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
@c 02.0.00 Invoking: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
@c         Command-line arguments and options  - - - - - - - - - - - - - - - - -
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
@node Invoking
@unnumbered Invoking
@cindex 02.0.00 Invoking
@cindex invoking
@cindex command-line options

There are three (3) groups of command-line options for invoking the 
application (@ref{invocation menu} below). Each option group is independent 
of the others (with some exceptions). The @t{'help'} and @t{'version'} options 
override all other specified options. When one of the testing options is 
specified, it overrides any request for application-level (GPS) data.

@enumerate 1
@item Terminal Configuration Options:@*
These options configure the terminal environment for the application.@*
Configuration options include color attributes, I/O stream options, 
@LDQ{}locale@RDQ{}, signal processing, cursor shape and more.
All are optional, and if not specified, the default setting for that option 
will be used.@*
Please @xref{Invoking - Terminal Setup}.

@item AnsiCmd-class Testing Options:@*
These options specify a test of specific functionality within the AnsiCmd 
library. Because the @t{EarthPoints} application is primarily a test and 
demonstration application, the array of available tests is extensive.@*
Each test establishes its own terminal environment according to the needs 
of the specific test, and thus may override the corresponding terminal 
setup option(s).@*
All tests are within conditional compilation blocks 
@ifnothtml
@*
@end ifnothtml
(@ref{Build Options}), so all test code may be disabled without loss of 
application functionality.@*
Please @pxref{Invoking - AnsiCmd Tests}.

@item EarthPoints Application Options:@*
These options provide data for the top-level application functionality; 
specifically, global-positioning coordinates (latitude/longitude), and 
related data for calculating the distance between points on the globe.

To interactively invoke the application's help menu, at the command-line type:@*
@b{@verb{|   epts --help|}}@*
@b{@verb{|   epts -h|}}@*
@verb{|   |} or redirect the help menu through the @LDQ{}less@RDQ{} utility:@*
@b{@verb{|   epts --helpless|}}@*
@b{@verb{|   epts -hl|}}

Please @xref{Invoking - EarthPoints} for more information.
@end enumerate

@anchor{invocation menu}
@ifnothtml
@H5heading{Invocation Options,▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔}
@end ifnothtml
@ifhtml
@html
<span style="font-weight:bold; font-style:italic;">
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
<span style=" text-decoration:underline;">Invocation Options</span></span>
@end html
@end ifhtml

@menu
* Invoking - Terminal Setup::    Terminal Setup Options
* Invoking - AnsiCmd Tests::     Testing Options
* Invoking - EarthPoints::       Application Parameters
@end menu
@sp 2


@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
@lowersections
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
@c 02.1.00 Invoking - Terminal Setup:  - - - - - - - - - - - - - - - - - - - - -
@c         Terminal Setup Options  - - - - - - - - - - - - - - - - - - - - - - -
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
@node Invoking - Terminal Setup
@unnumbered Invoking - Terminal Setup
@cindex 02.1.00 Invoking - Terminal Setup
@cindex invoking, term setup
@cindex setup options
@cindex options, setup

When invoking the EarthPoint application (epts), terminal setup options are 
specified through the @LDQ{}@b{@verb{|--term|}}@RDQ{} command-line option:@*
@b{@verb{|    epts --term=SETUP_OPTIONS|}}

Options may be specified in any order and in any combination.@*
Multiple options may be concatenated, seperated by commas (@t{','}):@*
If the argument string contains whitespace, enclose the entire argument 
string in single- or double-quotes.

@example
# Set stream_Width==wide, Color==red/blue, Locale==French(Canada)
epts --term=W:w,C:rb,L:fr_CA.utf8

# Set Locale==from_terminal_environment, Panic_button==user_query, 
      cursor_Style==blinking_underline
epts --term="L:e, P:u, S:ub"

# Set input_Buffering==unbuffered_no_echo, Ansi_compliant==no, 
      Panic_button==ignore_with_alert, Color==blue/default
epts --term='B:ux, A:n, P:ia, C:b'
@end example

@Subheading{Summary of Options,------------------}

@indentedblock
@multitable {xxxxxxxxxxxxxxx}            {xxxxxxxxxxxxxxxxxxxxxxxxxx}
@headitem @ @ @ @ OPTION @ @ @ @ @ @ @    @tab @ @ DESCRIPTION
@item @ @ @ref{W option} @ @              @tab @ stream @b{W}idth 
@item @ @ @ref{C option} @ @              @tab @ @b{C}olor attributes
@item @ @ @ref{A option} @ @              @tab @ @b{A}nsi compliant
@item @ @ @ref{B option} @ @              @tab @ input @b{B}uffering
@item @ @ @ref{L option} @ @              @tab @ @b{L}ocale name
@item @ @ @ref{P option} @ @              @tab @ @b{P}anic button
@item @ @ @ref{Q option} @ @              @tab @ @b{Q}uit signal
@item @ @ @ref{Z option} @ @              @tab @ suspend ctrl+@b{Z}
@item @ @ @ref{S option} @ @              @tab @ cursor @b{S}tyle
@end multitable
@end indentedblock
@sp 2


@c = = = = = = = = = = = = = =
@c =      -W option          =
@c = = = = = = = = = = = = = =
@cindex W option
@cindex option, W
@anchor{W option}
@ifnothtml
@w{ @minus{}W  Stream Width.}
@end ifnothtml
@ifhtml
@html
<span style="font-size:110%;"><span style="font-weight:bolder;"> &ndash;W</span>
<span style="margin-left:2.0em;">Stream Width.</span></span>
@end html
@end ifhtml

The term @LDQ{}Stream Width@RDQ{} refers to the character width for input and 
output streams for the application. Typically, the character width is either 
8-bits (char) or 32-bits (wchar_t).

For console applications, the I/O stream width is established either directly 
by declaring the width @b{@emph{or}} by locking in the character width with 
the first data read from, or written to the the I/O streams. Once locked in, 
the stream width cannot be changed without closing and re-opening the stream(s), 
which is not as straightforward as it sounds, and is therefore discouraged.

@verb{|w -|} Use the wide (wcin/wcout) input/output streams. 
@ifnothtml
@* @verb{|     |}
@end ifnothtml 
This is the default, and is strongly recommended.@*
@verb{|n -|} Use the legacy narrow (cin/cout) input/output streams. 
@ifnothtml
@* @verb{|     |}
@end ifnothtml
The narrow I/O streams are not recommended for modern applications,@*
@verb{|     |} but may be used for testing the interface.

Example:@*
@b{@verb{|   epts --term=W:w     |}} # set Wide stream width

To set this option directly, call the AnsiCmd method: @ref{acSetStreamWidth}.
@sp 2


@c = = = = = = = = = = = = = =
@c =      -C option          =
@c = = = = = = = = = = = = = =
@cindex C option
@cindex option, C
@anchor{C option}
@ifnothtml
@w{ @minus{}C  Color Attributes.}
@end ifnothtml
@ifhtml
@html
<span style="font-size:110%;"><span style="font-weight:bolder;"> &ndash;C</span>
<span style="margin-left:2.0em;">Color Attributes.</span></span>
@end html
@end ifhtml

Specify the text foreground, and optionally the background color attribute(s). 
The foreground color argument is required, and the background argument is 
optional, and if not specified, the terminal default background will be used.

Within a console application, it is often useful, to use contrasting colors to 
draw the user's attention to important information. For applications which 
include the AnsiCmd library, these color attributes may be specified as a 
command line option. 

The @t{-C} option is used to specify one of the basic eight(8) colors (or default) 
for foreground and background. 

@example
k : blac@b{K}        b : @b{B}lue
r : @b{R}ed          m : @b{M}agenta
g : @b{G}reen        c : @b{C}yan
n : brow@b{N}        y : gre@b{Y}
d : @b{D}efault
@end example

Examples:@*
@b{@verb{|   epts --term=C:r     |}} # set Red foreground with Default background@*
@b{@verb{|   epts --term=C:cb    |}} # set Cyan foreground with Blue background@*
@b{@verb{|   epts --term=C:dg    |}} # set Default foreground with Green background@*

To set this option directly, call the AnsiCmd method: @ref{acSetFgBg}.
@sp 2


@c = = = = = = = = = = = = = =
@c =      -A option          =
@c = = = = = = = = = = = = = =
@cindex A option
@cindex option, A
@anchor{A option}
@ifnothtml
@w{ @minus{}A  Ansi Compliance.}
@end ifnothtml
@ifhtml
@html
<span style="font-size:110%;"><span style="font-weight:bolder;"> &ndash;A</span>
<span style="margin-left:2.0em;">Ansi Compliance.</span></span>
@end html
@end ifhtml

The most popular terminal emulator software, Gnometerm, Konsole and XTerm all 
support the core set of @t{ANSI} escape sequences. However, some terminal 
software may not understand some of the basic commands such as those which 
reset (disable) certain individual settings. 

For terminals with this limited support, the AnsiCmd library functions can 
substitute the full reset command for the unsupported individual reset commands. 
While the full reset is slower and less convenient for the application programmer, 
it provides a way to produce a reliable application interface.

For example, the standard way to reset the Bold attribute is with the 
@t{aesBOLD_OFF} sequence:@*
@verb{|   acSetMod ( aesBOLD_OFF );|}@*
If this command or similar commands is not supported by the terminal, then 
the global attribute reset can be called:@*
@verb{|   acSetMod ( aesRESET );|}@*
This substitution is done automatically if the internal non-compliance flag 
is set.

The level of @t{ANSI} compliance is specified by:@*
@verb{|y -|} Yes, the host terminal supports the common @t{ANSI} escape sequences.@*
@verb{|   |} This is the default, and should be correct in most cases.@*
@verb{|n -|} No, the terminal is unable to handle some of the necessary sequences.@*
@verb{|   |} Use the reliable reset when disabling an attribute.

To set this option directly, call the AnsiCmd method: @ref{acFullReset}.
@sp 2


@c = = = = = = = = = = = = = =
@c =      -B option          =
@c = = = = = = = = = = = = = =
@cindex B option
@cindex option, B
@anchor{B option}
@ifnothtml
@w{ @minus{}B  Input Buffering.}
@end ifnothtml
@ifhtml
@html
<span style="font-size:110%;"><span style="font-weight:bolder;"> &ndash;B</span>
<span style="margin-left:2.0em;">Input Buffering.</span></span>
@end html
@end ifhtml

Specify the buffering options for the input stream (stdin).

By default, keyboard input at the terminal prompt is stored in the stream 
buffer until the user presses the Enter key; however, application control 
of the keyboard input stream is, in the author's view, critical to the success 
of the application.@*
@i{(Our opinions are plentiful and provided free-of-charge.)}

If your applications would benefit from having full control of keyboard input, 
then the @t{-B} option is used to specify the way keyboard input is captured, 
filtered and presented to the application.

@example
b : Buffered input from stdin is enabled (default).
    Keycodes are sent to the application when the Enter key is pressed.
    The terminal automatically echoes printing characters to the display,
    and processes control codes and other non-printing keycodes using
    whatever Voodoo rituals the terminal software developers follow.

u : Unbuffered input from stdin.
    Keycodes are available to the application as soon as the key is pressed.
    Echo of printing characters to the display is specified as a sub-option.

    Echo sub-options:
    x : Echo of data from stdin is disabled.
        This is the default and is assumed if no sub-option is specified.
    s : Soft Echo. This option automatically echoes printing characters to 
        the display, but captures the so-called "special" (non-printing) 
        keycodes and processes them according to the soft-echo sub-option.
        a : All "special" keycodes are captured, processed and passed on 
            to the application. This is the default soft-echo option.
        b : Basic "special" keycode group. This includes the cursor
            positioning and edit-key groups, but not the text-selection
            and clipboard-access keycodes.
        c : Cursor-positioning keycodes are passed to the application.
            The edit keycodes are discarded.
        e : Edit keycodes (Backspace, Delete, Insert and Alt+Enter) plus Tab
            and Shift+Tab are passed to the application. Cursor-positioning 
            keycodes are discarded. (useful primarily for debugging)
        d : Disable (discard) all "special" keycodes.
    @xref{Soft Echo Options} for more information.

Examples:
   @b{epts @t{--}term=B:b}   # Buffering is enabled.
   @b{epts @t{--}term=B:ux}  # Buffering is disabled with echo disabled.
   @b{epts @t{--}term=B:usa} # Buffering is disabled, echo enabled,
                       and all special keys enabled.
   @b{epts @t{--}term=B:usc} # Buffering is disabled, echo enabled,
                       and cursor-positioning special keys enabled.
   @b{epts @t{--}term=B:usd} # Buffering is disabled, echo enabled,
                       and all special keys discarded.
@end example

To set this option directly, call the AnsiCmd method: @ref{acBufferedInput}.
@sp 2


@c = = = = = = = = = = = = = =
@c =      -L option          =
@c = = = = = = = = = = = = = =
@cindex L option
@cindex option, L
@cindex locale, specify
@anchor{L option}
@ifnothtml
@w{ @minus{}L  Locale Name.}
@end ifnothtml
@ifhtml
@html
<span style="font-size:110%;"><span style="font-weight:bolder;"> &ndash;L</span>
<span style="margin-left:2.0em;">Locale Name.</span></span>
@end html
@end ifhtml

Specify the @LDQ{}locale@RDQ{} to be used within the application.

A locale is the set of rules used to interpret the way text and numeric data 
are processed and presented. A few examples of locale-dependent data are, 
currency values, telephone numbers, timestamps and measurements.

Two command-line options are available:

@example
e - Environment: Activate the locale specified in the terminal
    environment. This is the default and is almost always the the 
    right choice.

locale_name - specify a valid filename for the locale to be used.

Examples:
   @b{epts @t{--}term=L:e}             # take locale from environment
   @b{epts @t{--}term=L:zh_CN.utf8}    # specify Zhongwen (China) locale

@end example

It is very likely that the terminal environment in which your console 
application runs specifies the locale via one or more environment variables. 
At the command line type:@*
@b{@verb{|   echo $LANG|}}@*
To list the types of formatting handled by the current locale, at the 
command line type:@*
@b{@verb{|   locale|}}@*
To list the UTF-8 compliant locales supported by your system, at the 
command line type:@*
@b{@verb{|   locale -a | grep -i 'UTF'|}}@*
This should yield a list of filenames such as@*
@verb{|   en_US.UTF-8, zh_CN.utf8, es_AR.utf8|}

@i{@b{Technical Note:} Except for Windoze(tm), the civilized world uses UTF-8 
character encoding exclusively. Be sure that any locale specified for use 
in your application is based on UTF-8 encoding.}

@i{@b{Technical Note:} If a console application does not explicitly specify 
a locale, the so-called @LDQ{}C-locale@RDQ{} is used. This is not actually a 
locale at all but the complete lack of a locale@EMDASH{}resulting in a complete 
lack of coherent data formatting.}
@sp 2


@c = = = = = = = = = = = = = =
@c =      -P option          =
@c = = = = = = = = = = = = = =
@cindex P option
@cindex option, P
@anchor{P option}
@ifnothtml
@w{ @minus{}P  Panic Button.}
@end ifnothtml
@ifhtml
@html
<span style="font-size:110%;"><span style="font-weight:bolder;"> &ndash;P</span>
<span style="margin-left:2.0em;">Panic Button.</span></span>
@end html
@end ifhtml

The Break Signal, otherwise know as the Panic Button or @t{Control+C} is 
the primary method of killing a console application which has locked up 
or has gone off into the weeds.

By default, the terminal receives the break signal and immediately kills 
the application, leaving your data in an indeterminate state.

This is fine if you don't care about your data, but if you actually don't 
care about your data, @b{@emph{please}} step away from the keyboard 
@EMDASH and pursue a career in marketing. Otherwise, your application may 
benefit one of these options.

@example
i[a] - Ignore the break signal, that is capture the signal and discard it.
       Optionally produce an audible alert.
e - Exit the application on receipt of the break signal. The shutdown is 
    performed in an orderly way, returning all resources to the system
    before returning control to the terminal shell.
u - User interaction is required. The signal handler prompts the user
    whether to exit the application or to discard the break signal
    and continue the application.
c - Capture the signal and convert it to an ordinary keycode (wcsCTL_C) 
    which is commonly used by applications as the @LDQ{}copy@RDQ{} command.
t - The terminal is allowed to retain control of the break signal.
    If the user presses the CTRL+C key combination, the application will
    be terminated immediately, leaving the terminal in an indeterminate state.
    Although this is the default, it is not recommended.

Examples:
   @b{epts @t{--}term=P:i}          # Ignore break signal
   @b{epts @t{--}term=P:ia}         # Ignore break signal and sound an alert
   @b{epts @t{--}term=P:e}          # Exit the application
   @b{epts @t{--}term=P:u}          # User prompt on receipt of break signal
   @b{epts @t{--}term=P:c}          # Copy command conversion
   @b{epts @t{--}term=P:t}          # Terminal handler (default)

@end example

Please @pxref{Capturing the Break Signal} for additional information.

To set this option directly, call the AnsiCmd method: @ref{acCaptureBreakSignal}.
@sp 2


@c = = = = = = = = = = = = = =
@c =      -Q option          =
@c = = = = = = = = = = = = = =
@cindex Q option
@cindex option, Q
@anchor{Q option}
@ifnothtml
@w{ @minus{}Q  Quit Signal.}
@end ifnothtml
@ifhtml
@html
<span style="font-size:110%;"><span style="font-weight:bolder;"> &ndash;Q</span>
<span style="margin-left:2.0em;">Quit Signal.</span></span>
@end html
@end ifhtml

The Quit Signal (or Kill signal) is similar to the Panic Button described 
above, except that in addition to terminating the application, it also 
generates a core dump. 

A core dump is a file which contains a description of the the application 
state when it was terminated. This can include the register values, the 
call stack (addresses and parameters), a table of RAM contents and other 
information. This can be a large file, and it is recommended that it not 
be generated unless you actually need it.

The Quit Signal is captured by default during configuration of the 
AnsiCmd class and its derived classes. When the Quit signal is received, 
the application is shut down in an orderly manner. Use the 
@LSQ{}@b{Q option}@RSQ{} to disable this functionality.@*
@b{@verb{|   epts --term=Q:n|}}

To set/reset this option directly, call the AnsiCmd method: @ref{acCaptureQuitSignal}.
@sp 2


@c = = = = = = = = = = = = = =
@c =      -Z option          =
@c = = = = = = = = = = = = = =
@cindex Z option
@cindex option, Z
@anchor{Z option}
@ifnothtml
@w{ @minus{}Z  Suspend Signal.}
@end ifnothtml
@ifhtml
@html
<span style="font-size:110%;"><span style="font-weight:bolder;"> &ndash;Z</span>
<span style="margin-left:2.0em;">Suspend Signal.</span></span>
@end html
@end ifhtml

The @LDQ{}@b{@t{Suspend}}@RDQ{} signal is generated by the @t{Ctrl+Z} key 
combination. This signal suspends the currently-active process (places it 
into hibernation). The process will not be able to respond to any command 
other than a command to resume operation. Refer to documentaiton for the 
@LSQ{}@b{fg}@RSQ{} system utility for information on restoring the hibernating 
process.

While the @t{"suspend"} functionality is a valuable tool in some contexts, 
it is merely confusing to the average user when the running application simply 
freezes and cannot be restarted.

For this reason, the @t{"suspend"} signal (@t{SIGTSTP}) is captured by default 
and is converted to an ordinary keycode, wcsCTL_Z. 
@ifhtml
@*
@end ifhtml
The @t{Ctrl+Z} key combination is often used by applications (LibreOffice, 
jEdit, etc.) to @i{@LDQ{}undo@RDQ{}} a previous action.@*
@b{@verb{|   epts --term=Z:n|}}@*
@b{@verb{|   epts --term=Z:y|}} (default)
@sp 2


@c = = = = = = = = = = = = = =
@c =      -S option          =
@c = = = = = = = = = = = = = =
@cindex S option
@cindex option, S
@anchor{S option}
@ifnothtml
@w{ @minus{}S  Cursor Style.}
@end ifnothtml
@ifhtml
@html
<span style="font-size:110%;"><span style="font-weight:bolder;"> &ndash;S</span>
<span style="margin-left:2.0em;">Cursor Style.</span></span>
@end html
@end ifhtml

Specify the shape and animation (blinking or steady) of the visible cursor.

@example
d - Default. Use the terminal's default cursor shape and animation.
    For most environments, a full-cell, blinking block is the default.

b[b|s] - Block. The cursor shape is a rectangular block that fills one 
         entire character cell.
         Sub-options: 'b' - blinking (default)
                      's' - steady (non-blinking)
u[b|s] - Underline. The cursor shape is a thin horizontal bar at the 
         bottom of the character cell. This resembles an underline or
         the underscore character '_'
         Sub-options: 'b' - blinking
                      's' - steady
v[b|s] - Vertical bar. The cursor shape is a thin vertical bar at the
         left edge of the character cell. This is similar, but not
         identical to the vertical bar character: '|' on the keyboard.
         Sub-options: 'b' - blinking
                      's' - steady

Examples:
   @b{epts @t{--}term=S:u}          # Underline (with blinking default)
   @b{epts @t{--}term=S:vb}         # Vertical bar, blinking
   @b{epts @t{--}term=S:vs}         # Vertical bar, steady (non-blinking)

@end example

To set this option directly, call the AnsiCmd method: @ref{acSetCursorStyle}. 
Note that this method may also be used to set cursor as invisible.

@cindex blink timeout
@cindex timeout, blinking
@cindex gsettings, blink
@H5heading{Technical Note:,
           ▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔}
The blinking-cursor options are impacted by the terminal software's blink timeout 
value. For Gnome, the default timeout is ten seconds, after which the cursor 
will stop blinking and become steady state. To adjust this timeout value under 
Gnome, use either the @t{'dconf'} editor or the @t{'gsettings'} utility.

Get the current timeout value:@*
@verb{|   gsettings get org.gnome.desktop.interface cursor-blink-timeout|}@*
Get the range of valid values for this option:@*
@verb{|   gsettings range org.gnome.desktop.interface cursor-blink-timeout|}@*
Set a new timeout value in seconds:@*
@verb{|   gsettings set org.gnome.desktop.interface cursor-blink-timeout 25|}

Other desktop schemes will have a similar mechanism for adjusting the 
cursor blink timeout value.
@sp 2


@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
@c 02.2.00 Invoking - AnsiCmd Tests: - - - - - - - - - - - - - - - - - - - - - -
@c         Testing Options - - - - - - - - - - - - - - - - - - - - - - - - - - -
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
@node Invoking - AnsiCmd Tests
@unnumbered Invoking - AnsiCmd Tests
@cindex 02.2.00 Invoking - AnsiCmd Tests
@cindex invoking, test options
@cindex testing options
@cindex options, testing

Tests for the AnsiCmd library are specified as arguments to the 
@t{"@b{@t{--test}}"} command-line option.@*
@b{@verb{|   epts --test=TEST_OPTION|}}

The specific test within a group of related tests is specified by from one 
to four characters as detailed in this chapter. The first character indicates 
the test group. For instance, the letter @t{'@b{C}'} designates the group 
of color-attribute tests. If a test group is invoked without indicating a 
specific test, then the menu of available tests in that group will be 
displayed and the application will exit.@*
@b{@verb{|   epts --test=C|}} @ @ will display the color test menu:@*
   @verb{|        Color Attribute Testing Options:|}@*
   @verb{|   -----------------------------------------------|}@*
   @verb{|   'f'  Four-bit Fgnd/Bkgnd color attributes.|}@*
   @verb{|   'b'  Background color attribute options.|}@*
   @verb{|   't'  Table lookup, 8-bit color attributes.|}@*
   @verb{|   'r'  R/G/B color-attribute matrix (6x6x6).|}@*
   @verb{|   'g'  Greyscale color attributes.|}@*
   @verb{|   'a'  Aixterm Fg/Bg extensions (non-standard).|}@*
   @verb{|   'd'  Decode tracking data for attribute mods.|}@*
   @verb{|   's'  Swap acaExpand foreground/background.|}

Similarly, if a test group and a test are specified, but the test requires 
an argument or arguments, then a menu of available arguments for that 
test will be displayed and the application will exit.@*
@b{@verb{|   epts --test=Cr|}} @ @ will display the RGB color test arguments:@*
   @verb{|        RGB Test Options:|}@*
   @verb{|   ---------------------------------------------------|}@*
   @verb{|   'r'  Red  : Display full range of red colors.|}@*
   @verb{|   'g'  Green: Display full range of green colors.|}@*
   @verb{|   'b'  Blue : Display full range of blue colors.|}@*
   @verb{|   'y'  greY : Display full range of greyscale colors.|}@*
   @verb{|   'w'  Web  : Display "web-safe" colors.|}

A few test require two(2) arguments, for example:@*
@b{@verb{|   epts --test=Tec|}} @ @ Terminal group, Echo test, Cursor keys

If a test and its argument(s) are fully specified, then optionally, the 
next character indicates the text color attribute to be used for outputting 
the results of the test. The available color attributes are:@*
@verb{|   'k' blacK     'r' Red|}@*
@verb{|   'g' Green     'n' browN|}@*
@verb{|   'b' Blue      'm' Magenta|}@*
@verb{|   'c' Cyan      'y' greY|}@*
@verb{|   |} If not specified, the terminal default color is used.@*
@verb{|   |} Note: The color-attribute tests will ignore this argument.@*
Examples:@*
@b{@verb{|   epts --test=Eb|}} @EMDASH Perform @t{'@b{E}'}rasure test 
      with @t{'@b{b}'}lue text.@*
@b{@verb{|   epts --test=Ac |}} @EMDASH Perform @t{'@b{A}'}SCII code test 
      with @t{'@b{c}'}yan text.@*
@b{@verb{|   epts --test=Tig|}} @EMDASH Perform @t{'@b{T}'}erminal @t{'@b{i}'}nput 
      test with @t{'@b{g}'}reen text.@*
@b{@verb{|   epts --test=Wddb|}} @EMDASH Test @t{'@b{W}'}indow @t{'@b{d}'}ialog, 
      sub-test @t{'@b{d}'} with @t{'@b{b}'}lue text.@*
@sp 1

@Subheading{Summary of Options,------------------}

@indentedblock
@multitable {xxxxxxxxxxxxxxx}       {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@headitem @ @ @ @ OPTION @ @ @ @     @tab @ @ DESCRIPTION
@item @ @ @ref{test C}               @tab @ @b{C}olor tests
@item @ @ @ref{test P}               @tab @ @b{P}ositioning tests
@item @ @ @ref{test E}               @tab @ @b{E}rasure tests
@item @ @ @ref{test A}               @tab @ @b{A}scii control code tests
@item @ @ @ref{test F}               @tab @ @b{F}ont switch test
@item @ @ @ref{test @t{I}}           @tab @ @b{I}deograph test
@item @ @ @ref{test T}               @tab @ @b{T}erminal setup tests
@item @ @ @ref{test W}               @tab @ @b{W}indow tests
@item @ @ @ref{test D}               @tab @ @b{D}ialog tests
@item @ @ @ref{test S}               @tab @ @b{S}andbox
@end multitable
@end indentedblock

Options for testing the functionality of the AnsiCmd-class library.

For options which require arguments, the option must be immediately 
followed by the EQUAL sign ('=') which must be immediately followed by 
its argument. If the argument string contains space characters, enclose 
it in quotation marks.

Please @pxref{Development and Testing} or study the @t{AnsiCmdTest.cpp} 
source file for more information about how the individual tests are constructed.
@sp 2

@c = = = = = = = = = = = = = = = = 
@c = Test C - Color Attriibutes  =
@c = = = = = = = = = = = = = = = =
@cindex color test
@cindex test, color
@anchor{test C}
@ifnothtml
@w{ @minus{}C  Color Attrubutes.}
@end ifnothtml
@ifhtml
@html
<span style="font-size:110%;"><span style="font-weight:bolder;"> &ndash;C</span>
<span style="margin-left:2.0em;">Color Attributes.</span></span>
@end html
@end ifhtml

The majority of escape sequences definined in the @t{ECMA-48 (ANSI)} standard 
are related to setting foreground and background color attributes. These 
definitions reflect the evolution of color support on hardware terminals and 
within terminal emulators from 3-bit (8 colors) to 4-bit (16 colors) through 
today's so-called true-color (usually 24-bit) systems.

Each of the color palettes supported by the standard is exercised by one 
or more of the color-attribute tests listed here.

@example
f : Four-bit color attribute tests (16-color palette)
b : Background option tests
t : Table lookup tests (8-bit color)
g : Greyscale attribute tests
a : Aixterm extensions
r : Rgb, red/green/blue tests (24-bit color)
    r : Red spectrum
    g : Green spectrum
    b : Blue spectrum
    y : greYscale spectrum
    w : Web-safe r/g/b colors
d : Decoding and encoding attribute tracking data
    a : API-level tests (default)
    b : Basic low-level ANSI escape tests
s : Swap/build8Bit/buildRgb - acaExpand class utilities
@end example
@sp 2


@c = = = = = = = = = = = = = = = = 
@c = Test P - Positioning Tests  =
@c = = = = = = = = = = = = = = = =
@cindex positioning test
@cindex test, positioning
@anchor{test P}
@ifnothtml
@w{ @minus{}P  Positioning Tests.}
@end ifnothtml
@ifhtml
@html
<span style="font-size:110%;"><span style="font-weight:bolder;"> &ndash;P</span>
<span style="margin-left:2.0em;">Positioning Tests.</span></span>
@end html
@end ifhtml

One group of the escape sequence defined by the standard provides various 
ways to set the cursor position. Some of these sequences set an 
@LDQ{}absolute@RDQ{} (terminal-relative) position. Others define a move 
relative to the current cursor position. All the supported variations are 
used during this test.
@sp 2


@c = = = = = = = = = = = = = = = = 
@c = Test E - Erasure Tests      =
@c = = = = = = = = = = = = = = = =
@cindex erasure test
@cindex test, erasure
@anchor{test E}
@ifnothtml
@w{ @minus{}E  Erasure Tests.}
@end ifnothtml
@ifhtml
@html
<span style="font-size:110%;"><span style="font-weight:bolder;"> &ndash;E</span>
<span style="margin-left:2.0em;">Erasure Tests.</span></span>
@end html
@end ifhtml

In the early days of computing, terminals were @emph{extremely} slow. 
For this reason, several innovative ways of erasing an area of the display 
were implemented to increase the speed of display updates. Some of these 
include erasing part of a line, a whole line, and either the top half or 
bottom half of the display. It is even possible to @LDQ{}erase@RDQ{} the 
data which has already been scrolled out of the window. 
@w{@i{(It was a whole thing....don't ask :-)}}
@sp 2


@c = = = = = = = = = = = = = = = = =
@c = Test A - ASCII Control Tests  =
@c = = = = = = = = = = = = = = = = =
@cindex ascii test
@cindex test, ascii
@anchor{test A}
@ifnothtml
@w{ @minus{}A  ASCII Control Codes, Function Keys and ALT Key Combinations.}
@end ifnothtml
@ifhtml
@html
<span style="font-size:110%;"><span style="font-weight:bolder;"> &ndash;A</span>
<span style="margin-left:2.0em;">ASCII Control Codes, Function Keys and ALT Key Combinations.</span></span>
@end html
@sp 2
@end ifhtml

@cindex CTRL-key combo
@H5heading{@t{ASCII} Control Codes,
           ▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔}
@t{ASCII} control codes (00h - 1Fh) were at one time an important part of 
systems which relied on serial communication (e.g. Teletype machines) for 
user interaction. On modern systems, most of these codes are unused by the 
terminal software and inconvenient for application use.@*
A few control codes however, are vital to operation. The most common are 
null(00h), bell(07h), backspace(08h), horizontal-tab(09h), linefeed i.e. 
newline(0Ah), vertical-tab(0Bh), form-feed(0Ch), carriage-return(0Dh), 
and of course Escape(1Bh). Others may be used in specialized circumstances.@*
These keycodes are presented to the application as non-printing byte values, 
@b{@emph{OR}} as system signals, which if not properly handled can cause 
chaos within an application. A prime example of this would be the CTRL+C 
Break signal. For this reason, these byte values and signals are captured 
by the AnsiCmd library and converted to unique keycodes for use by the 
application. A common example of these would be @w{@t{Copy/Cut/Paste}} 
and similar keycodes.@*
@example
    Key         Raw      Name Of     Common
Combination    Input     Keycode     Usage
───────────  ──────────  ────────    ──────────
 CTRL+C      break(03)   wcsCTL_C    Copy
 CTRL+X         18       wcsCTL_X    Cut
 CTRL+V         16       wcsCTL_V    Paste
 CTRL+Z      susp(1A)    wcsCTL_Z    Undo
 CTRL+A         01       wcsCTL_A    Select All
 CTRL+S      pause(13)   wcsCTL_S    Save
 CtrL+Q      resume(11)  wcsCTL_Q    Quit
 Ctrl+4         1C       wcsCTL_4    Kill App
 Ctrl+[         1B       wcsESCAPE   Escape
@end example

The keycodes in this group consist of the @b{CONTROL key} plus one of:@*
@b{@verb{|   a-z 4 5 6 7 [ \|}}@*
Note that when the CONTROL key is pressed, the system ignores the SHIFT key, 
so @t{CTRL+A} generates the same byte code as @t{CTRL+a}.

@cindex Fnn-key combo
@H5heading{Function Key Combinations,
           ▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔}
The function keys @t{@b{F01-F12}} and their conditioned varients are often 
assigned to system-level tasks, but the terminal emulator may also be configured 
to pass these keycodes through to the application level.

All function keys generate escape sequences of between three(3) and seven(7) 
bytes. There are 48 (12 * 4) Function key combinations available:@*
@verb{|   a) F01-12, b) Shift+F01-12, c) Ctrl+F01-12, and|}@*
@verb{|   d) Ctrl+Shift+F01-12|}@*
Only the first three groups are supported by the AnsiCmd class; 
(36 sequential codepoints). When received, members of the fourth group, 
@t{Ctrl+Shift+Fnn} are silently converted to Ctrl+Fnn equivalents.

The @t{AnsiCmd} library captures these sequences and converts them 
to ordinary Unicode codepoints (keycodes) in the range: 0x002000 through 0x002023. 
Unicode assigns these keycodes to mathematical symbols which will seldom, if 
ever be generated directly by the keyboard. Some examples of the captured 
and converted sequences are shown in the table.

@example
    Key       Escape            Name Of  Unicode
Combination  Sequence           Keycode  Codepoint
───────────  ─────────────────  ──────── ─────────
F02          1B 4F 51           wcsF02   0x002001
Shift+F02    1B 5B 31 3B 32 51  wcsSF02  0x00200D
Ctrl+F02     1B 5B 31 3B 35 51  wcsCF02  0x002019
@end example

Please see the @t{AnsiCmdDef.hpp} source module for the full list.

@cindex ALT-key combo
@H5heading{ALT Key Combinations,
           ▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔}
The Left ALT key in combination with another key provides what are commonly 
known as the @t{GUI} keys. These key combinations are often used as shortcut 
keys within applications. For instance, @w{@t{ALT+F, ALT+E and ALT+H}} are 
often used to invoke an application's @LDQ{}File@RDQ{}, @LDQ{}Edit@RDQ{}, 
and @LDQ{}Help@RDQ{} menus, respectively.@*
Because these keycodes are presented to the application as escape sequences, 
it is necessary to capture the escape sequences and convert them to unique 
keycodes for use by the the application. For the examples mentioned, these are:@*
@example
    Key       Escape   Name Of
Combination  Sequence  Keycode
───────────  ────────  ────────
  ALT+F       1B 46    wcsALT_F
  ALT+E       1B 45    wcsALT_E
  ALT+H       1B 48    wcsALT_H
@end example

The keycodes in this group consist of the @b{Left ALT key} plus one of:@*
@b{@verb{|   a-z !  "  #  $  %  &  '  (  ) *  +  ,  -  .  /  :  ;|}}@*
@b{@verb{!   <  =  >  ?  @  \  ]  ^  _  {  |  }!}}@*
Note that to avoid clutter, the alphabetic character are processed as 
case insensitive: @t{ALT+A} yields the same keycode as @t{ALT+a}. 
Also, the numeric combinations @t{ALT+0} through @t{ALT+9} are assigned 
the same keycodes as their shifted equivalents (assumes U.S. English 
keyboard layout).@*
@verb{|   ! @ # $ % ^ & * ( )|}@*
@verb{|   1 2 3 4 5 6 7 8 9 0|}
@sp 1

@H5heading{Other Keycodes,▔▔▔▔▔▔▔▔▔▔▔▔▔▔}
@ifhtml
@sp 1
@end ifhtml
The @LDQ{}Special Keys@RDQ{} group of keycodes are also reported by this test.

Please see the @t{AnsiCmdDef.hpp} source file for a full list of the 
assigned keycode names. @i{(or run this test)}
@sp 2


@c = = = = = = = = = = = = = = = = =
@c = Test F - Font Selection Tests =
@c = = = = = = = = = = = = = = = = =
@cindex font test
@cindex test, font
@anchor{test F}
@ifnothtml
@w{ @minus{}F  Font Selection Tests.}
@end ifnothtml
@ifhtml
@html
<span style="font-size:110%;"><span style="font-weight:bolder;"> &ndash;F</span>
<span style="margin-left:2.0em;">Font Selection Tests.</span></span>
@end html
@end ifhtml

A @LDQ{}font@RDQ{} is a set of glyphs (visible pictures) which are used to 
represent the @LDQ{}codepoints@RDQ of a character set. 
The @t{ECMA-48 (ANSI)} standard defines a method for selecting any of ten(10) 
fonts to be used for display text.

The "Primary Font" is specified in the aeSeq enumerated type as:@*
@b{@verb{|    aesPRIMARY_FONT  (decimal 10)|}}

The "Alternate Fonts" are specified by the aeSeq value of:@*
@b{@verb{|    aesALTERNATE_FONT|}}@*
with a numeric argument between 1 and 9 (inclusive).
These are translated to @t{ANSI} command codes 11 through 19, respectively.@*
Please @pxref{acSetFont} for more information.

Testing thusfar indicates that setting alternate fonts is not supported by 
the terminal emulators used during development. The font is set in the 
terminal's Preferences/Settings and appears to be unavailable to console 
applications; however, this tests exercises the font commands, and further 
research will be conducted.
@sp 2


@c = = = = = = = = = = = = = = = = =
@c = Test I - Ideograph Tests      =
@c = = = = = = = = = = = = = = = = =
@cindex ideograph test
@cindex test, ideograph
@anchor{test @t{I}}
@ifnothtml
@w{ @minus{}I  Ideograph Tests.}
@end ifnothtml
@ifhtml
@html
<span style="font-size:110%;"><span style="font-weight:bolder;"> 
&ndash;<span style="font-family:monospace;">I</span></span>
<span style="margin-left:2.0em;">Ideograph Tests.</span></span>
@end html
@end ifhtml

An @LDQ{}ideogram@RDQ{} is technically a symbol representing a concept or 
and idea, or what today we would call a @LDQ{}meme@RDQ{}. Street signs 
without words, mathematical-operator symbols or a photo of a cat hanging 
onto a branch with one paw could be considered as ideograms.

The ideograms defined by the @t{ECMA-48 (ANSI)} standard appear to have 
been intended as line-drawing tools or text decorations; however, they 
seem to have been abandoned before they were completed. As such, 
they are unlikely to be supported by modern terminals; however, this test 
issues the associated escape sequences to see what happens i.e. nothing:@*
@verb{|   aesIDEO_UNDER     // |}ideogram underlined@*
@verb{|   aesIDEO_UDOUBLE   // |}ideogram double-underlined@*
@verb{|   aesIDEO_OVER      // |}ideogram overlined@*
@verb{|   aesIDEO_ODOUBLE   // |}ideogram double-overlined@*
@verb{|   aesIDEO_STRESS    // |}ideogram stress marking@*
@verb{|   aesIDEO_OFF       // |}all ideogram attributes off
@sp 2


@c = = = = = = = = = = = = = = = = = =
@c = Test T - Terminal Config Tests  =
@c = = = = = = = = = = = = = = = = = =
@cindex terminal test
@cindex test, terminal
@anchor{test T}
@ifnothtml
@w{ @minus{}T  Terminal Configuration Tests.}
@end ifnothtml
@ifhtml
@html
<span style="font-size:110%;"><span style="font-weight:bolder;"> &ndash;T</span>
<span style="margin-left:2.0em;">Terminal Configuration Tests.</span></span>
@end html
@end ifhtml

This test exercises the various terminal configuration options and the 
internal tracking data related to those options.

@example
i : Input stream capture
e : Echo options, with a focus on the "soft-echo" options.
    a : All soft-echo special keys translated. (incl. clipboard tests)
    b : Basic set of soft-echo special keys.
    c : Cursor-movement special keys translated.
    d : Disable soft-echo special-key translation.
    e : Edit keys: Backspace/Del/Insert translated.
    r : Report special key translations.
    t : Terminal echo of key input.
    n : No echo of key input.
t : Terminal configuration validation of options, including
    input buffering, cursor style and capture of the break signal.
b : Blocking vs. non-blocking read from 'stdin'
r : Raw input stream reporting. The data are reported in unmodified form.
o : Output, tests handling of multi-byte character data in the output stream.
m : Modifiers: Bold, Italic, Underline, Reverse, Overline, etc.
f : Formatted output. Test data formatting and output to stdout.

Examples:
   @b{epts @t{--}test=T}      # Display the menu of sub-options
   @b{epts @t{--}test=Tb}     # Test blocking vs. non-blocking input
   @b{epts @t{--}test=Tec}    # Soft-echo options, cursor-movement keys


@i{Developer's Note: The text-modifier tests are included with the 
terminal configuration group because the tests include verification of 
the flags that track which modifier(s) are set at any given time.}
@end example
@sp 2


@c = = = = = = = = = = = = = = = = = =
@c = Test W - Window (ACWin) Tests   =
@c = = = = = = = = = = = = = = = = = =
@cindex window test
@cindex test, window
@anchor{test W}
@ifnothtml
@w{ @minus{}W  Window (ACWin) Tests.}
@end ifnothtml
@ifhtml
@html
<span style="font-size:110%;"><span style="font-weight:bolder;"> &ndash;W</span>
<span style="margin-left:2.0em;">Window (ACWin) Tests.</span></span>
@end html
@end ifhtml

The window group consists of @t{API}-level algorithms which are implemented 
at a higher abstraction level compared to the basic @t{ANSI} escape sequences.

At an intermediate level are the line-drawing and box objects which simply 
draw lines and rectangles to the display. These objects are defined by the 
@b{@ref{acDrawLine}} method and the @b{@ref{AC_Box Class}}, 
respectively.
@c @w{@b{@ref{acDrawLine}}} method and the @w{@b{@ref{AC_Box Class}}}, 

At the higher level of abstraction is the @b{@ref{ACWin Class}} which 
defines a relatively primitive window object which optionally contains an 
array of text fields and other user-interface controls (@b{@pxref{skForm Class}}).@*
See also the next section which describes @LDQ{}dialogs@RDQ{}, which are 
functionally sub-windows within the main window.

Visually, an ACWin window is simply a rectangle drawn within the terminal 
window; however, application-level interaction is carefully range-checked 
and validated to maintain the integrity of the window. This allows the 
application designer to focus on the project, rather than being distracted 
with organizing color change sequences, counting text columns and other 
low-level details.

The tests in this group exercise all the major functionality of defining and 
managing the ACWin object.

@example
w : Window (ACWin) interactive tests
f : Form: skForm class (and skField class) user interface controls
t : Automatic text reformatting to fit specified dimensions
d : Default AC_Win window constructor
s : Save and restore static text written to the window
m : Menus and Scrollbox controls. These controls require specialized tests.
h : Highlight text. Scan field text for a given token, and highlight it.
e : Documentation tool, take a screenshot to insert into documentation.
b : Box drawing tests
l : Line drawing tests
x : eXternal interface tests
    a : AnsiCmd API-level clipboard tests (tty output)
    w : Window (ACWin/ACDlg) clipboard tests
    t : Temporary-file management
    s : Shell out to command line
    l : Launch external application

Examples:
@b{   epts --test=W   } # Display the menu for the window group
@b{   epts --test=Ww  } # Interactive test of ACWin configuration
@b{   epts --test=Wf  } # User interaction via skForm control group
@b{   epts --test=Wlg } # Line-drawing tests with 'g'reen lines
@b{   epts --test=Wxw } # Clipboard-to-window communication

@end example

@c = = = = = = = = = = = = = = = = = =
@c = Test D - Dialog (ACDlg) Tests   =
@c = = = = = = = = = = = = = = = = = =
@cindex dialog test
@cindex test, dialog
@anchor{test D}
@ifnothtml
@w{ @minus{}D  Dialog (ACDlg) Tests.}
@end ifnothtml
@ifhtml
@html
<span style="font-size:110%;"><span style="font-weight:bolder;"> &ndash;D</span>
<span style="margin-left:2.0em;">Dialog (ACDlg) Tests.</span></span>
@end html
@end ifhtml

The dialog tests are a functional subset of the the window tests 
@ifnothtml
@*
@end ifnothtml
(@pxref{ACWin Class}), but because the Dialog is at the highest level of 
abstraction, a large number of tests are required, so they are grouped separately.

@example
 'D'         Dialog-oriented tests (application-level functionality).
      'q'    QuickDialog tests are specified by the letter 'q', followed 
             by the letter or number for the specific test:
             '1' Basic information dialog (one control)
             'e' Basic decision dialog with English pushbuttons
             'c' Basic decision dialog with Chinese pushbuttons
             'v' Basic decision dialog with Vietnamese pushbuttons
             's' Basic decision dialog with Spanish pushbuttons
             't' Auto-Timeout dialog, displayed for specified interval only
             'p' Dialog dimensions determined by size of Preformatted text.
             'w' Fixed-width dialog with text automatically formatted 
             'h' Fixed-height dialog with text automatically formatted 
             'r' Repositioned automatically within the parent window.
             '?' If no test letter is specified, or if an invalid test 
                 is specified, the QuickDialog test menu is displayed.
      'd'    Dialog, full initialization. Tests re specified by the letter 
             'd', followed by the letter or number for the specific test.
             -- Dialog invocations with full initialization allow for any 
                _reasonable_ number of customized controls of all defined 
                control types, in any order and in any position.
             'a' Preformatted text, Auto-dimensions,
                 Centered horizontally and vertically.
             'b' Auto-height, Fixed width, Text reformatted to specified width.
             'c' Preformatted text, Auto-width, Fixed height, 
                 Centered horizontally and vertically.
             'd' Unformatted text, Auto-dimensions, 
                 Centered horizontally and vertically.
             'e' Unformatted text, Fixed horizontal and vertical offsets, 
                 Auto-height, Fixed-width. 
                 Text truncated to fit available space.
             'f' Unformatted text, Fixed horizontal and vertical offsets, 
                 Fixed-height, Auto-width.
                 Text truncated to fit available space.
             't' Unformatted text, Centered vertically and horizontally, 
                 Fixed height and width specified, with height value overridden, 
                 but truncation of text still required.
             'w' Unformatted text, Centered horizontally, Fixed height and width, 
                 Fixed vertical offset, Text truncated to fit available space.
             'h' Move dialog horizontally in increments using preformatted text.
                 Resize dialog as necessary to stay within parent window.
             'i' Move dialog horizontally in increments using unformatted text.
                 Resize dialog as necessary to stay within parent window.
             'v' Move dialog vertically in increments using preformatted text.
                 Resize dialog as necessary to stay within parent window.
             'u' Move dialog vertically in increments using unformatted text.
                 Resize dialog as necessary to stay within parent window.
             'z' Dialog demonstrating all features: Pushbuttons, Radiobuttons, 
                 Textboxes, static text.
             '?' If no test letter is specified, or if an invalid test 
                 is specified, the full-Dialog test menu is displayed.
      '0'    Display the menu of dialog tests.
      's'    Sidebar test. This test is unrelated to dialogs. It is 
             included in this group because this group uses an empty 
             ACWin window object which allows for easy testing of the 
             Sidebar functionality.


Examples:
@b{   epts --test=D   } # Display the menu for the dialog group
@b{   epts --test=Dq  } # Display the menu for the QuickDialog sub-group
@b{   epts --test=Dd  } # Display the menu for the full-dialog sub-group
@b{   epts --test=Dqp } # Dialog dimensions derived from displayed text
@b{   epts --test=Ddz } # Dialog with samples of all control types

@end example
@sp 2

@c = = = = = = = = = = =
@c = Test S - Sandbox  =
@c = = = = = = = = = = =
@cindex sandbox test
@cindex test, sandbox
@anchor{test S}
@ifnothtml
@w{ @minus{}S  Sandbox.}
@end ifnothtml
@ifhtml
@html
<span style="font-size:110%;"><span style="font-weight:bolder;"> &ndash;S</span>
<span style="margin-left:2.0em;">Sandbox.</span></span>
@end html
@end ifhtml

The @LDQ{}Sandbox@RDQ{} is a common name among nerdy types to indicate a work 
area in which experimental operations may be performed without compromising 
the platform as a whole.

Invoking the Sandbox executes user-defined functionality created for 
ad hoc testing. Note that code created in the Sandbox may be affected 
by the AnsiCmd class initialization as specified by arguments to the 
@LDQ{}@b{@verb{|--term|}}@RDQ{} command-line option.@*
@xref{Invoking - Terminal Setup} for more information.

Invoking the Sandbox test may include one or two optional arguments 
which are passed as parameters to the Sandbox method.
Each of these optional arguments consists of a single alpha-numeric character, 
(case insensitive). 

Examples:@*
@b{@verb{|   epts --test=S   |}} # invoke the Sandbox with no arguments@*
@b{@verb{|   epts --test=St  |}} # invoke the Sandbox with one argument@*
@b{@verb{|   epts --test=S4c |}} # invoke the Sandbox with two arguments

The specified arguments will be displayed in the top row of the window as 
shown, and these parameters may be referenced in the usual way.@*
(A question mark will be displayed for unspecified argument(s)).
@example
Test ANSI Commands: 'S' '4' 'c'
-------------------------------

Welcome to the Sandbox!

@b{Example:}
void AnsiCmd::Test_Sandbox ( wchar_t parmA, wchar_t parmB )
@{
   if ( parmA == L'4' )
      this->SolveWorldHunger ( parmB ) ;
   else if ( parmA == L'5' )
      this->MakeScrambledEggs_with ( parmB ) ;
   else if ( parmA == L'?' )
      this->SpendAllDayOnTikTok () ;
@}
@end example
@sp 2


@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
@c 02.3.00 Invoking - EarthPoints: - - - - - - - - - - - - - - - - - - - - - - -
@c         Application Parameters  - - - - - - - - - - - - - - - - - - - - - - -
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
@node Invoking - EarthPoints
@unnumbered Invoking - EarthPoints
@cindex 02.3.00 Invoking - EarthPoints
@cindex invoking, EarthPoints
@cindex application options
@cindex options, application

@Subheading{Summary of Options,------------------}

@indentedblock
@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@headitem @ @ OPTION @tab @ @ DESCRIPTION
@item @ @ @ref{coa option}                @tab @ Specify the first set of
                                               @ global coordinates.
@item @ @ @ref{cob option}                @tab @ Specify the second set of
                                               @ global coordinates.
@item @ @ @ref{file option}               @tab @ Specify a file containing
                                               @ global coordinate pairs.
@item @ @ @ref{formula option}            @tab @ Specify the formula to be
                                               @ used to calculate distance.
@item @ @ @ref{convert option}            @tab @ Convert coordinate-pair
                                               @ format to alternate formats
@item @ @ @ref{color option}              @tab @ Specify color attribute for
                                               @ reporting results.
@item @ @ @ref{verbose option}            @tab @ Display verbose output for
                                               @ results of calculation.
@item @ @ @ref{window option}             @tab @ Display the report within a 
                                               @ window object.
@item @ @ @ref{dump option}               @tab @ Display and verify contents
                                               @ of a file of GPS records.
@item @ @ @ref{version option}            @tab @ Reports EarthPoints version 
                                               @ number and copyright info.
@item @ @ @ref{help option}               @tab @ Display all EarthPoints and
                                               @ AnsiCmd options
@item @ @ @ref{helpless option}           @tab @ Same as @t{'--help'} option
                                               @ except pipe through @t{'less'}
@end multitable
@end indentedblock

Options may be specified in any order.

For each option that requires one or more arguments, the option name and 
its argument(s) may be separated by either @t{'='} or @t{' '} (space). 
@ifnothtml
@*
@end ifnothtml
Note that if the argument contains whitespace, then the entire argument 
sequence must be enclosed within single-quotes or double-quotes. 
@ifnothtml
@*
@end ifnothtml
This prevents the terminal's shell program from @i{@LDQ{}interpreting@RDQ{}} 
(trashing) your argument formatting.

@verbatim
Examples:
    --coa=Miami:25.775163:80.208615
    --coa 'Miami: 25.775163 : 80.208615'
    --cob="Buenos Aires: -34 36 12.0 : -58.381666667"
    --file='Europen Capitol Cities - 2007.txt'
@end verbatim

@b{Note:} As a convenience, the long-form options may be uniquely specified 
in a truncated form. At least six (6) characters of the option must be 
specified. This consists of the two @t{'dash'} characters, plus the first four 
characters of the option name. Example: The @LDQ{}@b{@t{--verbose}}@RDQ{} 
option may be uniquely specified as @LDQ{}@b{@t{--verb}}@RDQ{}. 
@sp 2

@anchor{GPS Coordinate Records}
@Subheading{GPS Coordinate Records,----------------------}

A GPS coordinate record has the following format:@*
@verb{|   [LABEL:] LATITUDE : LONGITUDE|}@*
where:

@itemize @BDISC
@item @b{@verb{|LABEL:   |}} @EMDASH (optional) city or place name associated with the@*
@verb{|            |} coordinates, followed by the colon character (@t{':'})@*
@verb{|            |} which separates the label from the latitude field.
@item @b{@verb{|LATITUDE |}} @EMDASH (required) Specify the latitude for the record@*
@verb{|            |} in degrees or radians.
@item @b{@verb{|colon (:)|}} @EMDASH (required) Separates latitude and longitude values.@*
@item @b{@verb{|LATITUDE |}} @EMDASH (required) Specify the longitude for the record@*
@verb{|            |} in degrees or radians.
@end itemize

Whitespace between fields of the record is optional, and will be ignored.@*
Whitespace within a coordinate field delimits the tokens within that field:@*
@verb{|   Examples: '25 46.50978'  _or_  '25 46 30.5868'|}@*
The label field is simple text, and may contain spaces if desired.
@ifnothtml
@*
@end ifnothtml
(Note the trailing colon @t{':'}).@*
@verb{|   Example: "Miami, Florida, USA:"|}@*

Latitude and longitude pairs may be expressed in either degrees or radians.@*
Within a latitude:longitude pair, each value may take one of the following 
formats.

@enumerate 1
@item a decimal degree value
@verbatim
  Examples:
  --coa='Miami: 25.775163 : -80.208615'
  --cob='Buenos Aires: -34.603333333 : -58.381666667'
@end verbatim

Note that positive degree values indicate North latitude or East longitude, 
while negative values indicate South latitude or West longitude."

@item a decimal radian value
@verbatim
  Examples:
  --coa='Miami: 0.449861R : 4,883281R'
  --cob='Buenos Aires: 5.679243R : 5.264233R'
@end verbatim

Note that the trailing 'R' character of each value indicates radians. 
Note also that an arc in radians is expressed as a positive value only.

@item an integer degree value followed by a decimal minutes value
@verbatim
  Examples:
  --coa='Miami: 25 46.50978 : -80 57.948611'"
  --cob='Buenos Aires: -34 36.20 : -58 22.90'
@end verbatim

@item an integer degree value followed by an integer minutes value, 
followed by a decimal seconds value
@verbatim
  Examples:
  --coa='Miami: 25 46 30.5868 : -80 57 56.91666'
  --cob='Buenos Aires: -34 36 12 : -58 22 54.0'
@end verbatim
@end enumerate
@sp 1
@hr40d{}

@Subheading{Invocation Options,------------------}
@sp 1

@c = = = = = = = = = = = = = =
@c =      --coa option       =
@c = = = = = = = = = = = = = =
@cindex coa option
@cindex option, coa
@anchor{coa option}
@ifnothtml
@w{ @minus{}@minus{}coa  Coordinate pair A.}

@end ifnothtml
@html
<span style="font-size:110%;"><span style="font-weight:bolder;"> &ndash;&hairsp;&ndash;coa</span>
<span style="margin-left:2.0em;">
Coordinate pair A.
</span></span>
@end html
@indentedblock

Specify the record containing the first pair of GPS coordinates.

Formatting of the record is described in the @ref{GPS Coordinate Records} 
section, above.

Two sets of GPS coordinates are needed to calculate arc length. See the 
@w{@t{"cob" option},} below.

Please @pxref{verbose option}, below for sample output formatting.
@end indentedblock
@spi


@c = = = = = = = = = = = = = =
@c =      --cob option       =
@c = = = = = = = = = = = = = =
@cindex cob option
@cindex option, cob
@anchor{cob option}
@ifnothtml
@w{ @minus{}@minus{}cob  Coordinate pair B.}

@end ifnothtml
@html
<span style="font-size:110%;"><span style="font-weight:bolder;"> &ndash;&hairsp;&ndash;cob</span>
<span style="margin-left:2.0em;">
Coordinate pair B.
</span></span>
@end html
@indentedblock

Specify the record containing the second pair of GPS coordinates.

Formatting of the record is described in the @ref{GPS Coordinate Records} 
section, above.

Two sets of GPS coordinates are needed to calculate arc length. See the 
@w{@t{"coa" option},} above.

Please @pxref{verbose option} below for sample output formatting.
@end indentedblock
@spi


@c = = = = = = = = = = = = = =
@c =     --file option       =
@c = = = = = = = = = = = = = =
@cindex file option
@cindex option, file
@anchor{file option}
@ifnothtml
@w{ @minus{}@minus{}file  Filespec of GPS coordinate database.}

@end ifnothtml
@html
<span style="font-size:110%;"><span style="font-weight:bolder;"> &ndash;&hairsp;&ndash;file</span>
<span style="margin-left:2.0em;">
Filespec of GPS coordinate database.
</span></span>
@end html
@indentedblock

Specify a file containing a database of GPS coordinate pairs and identify 
two specific records from that database. These records represent the 
endpoints of the arc distance to be calculated.

The target file is a plain text file containing any number of GPS records. 
The individual records follow the same format as command-line record 
specification described at the beginnig of this chapter. An example database 
file is shown below. @i{(Not that you would ever do anything so foolish, 
but the filename may not contain the colon ':' character.)}

Each target record is specified by its label, either the full label text, 
or a substring which uniquely identifies the beginning of the record label. 
The scan is case-insensitive. Specifying the database filename and record 
labels takes the form:@*
@verb{|   --file='FILENAME:LABEL_A:LABEL_B'|}

The following record specifications are equivalent.@*
@b{@verb{|   epts --file='GPS_Records.txt:Chicago, IL:Miami, FL'|}}@*
@b{@verb{|   epts --file='GPS_Records.txt:chi:Mia'|}}

Alternatively, the records may be specified using the @b{@emph{index}} of 
of the record(s) within the database using the special token: 
@LDQ{}LABn@RDQ{} where @t{'n'} is a zero-based index.

Examples:@*
@b{@verb{|   epts --file='GPS_Records.txt:Chicago, IL:LAB14'|}}@*
@b{@verb{|   epts --file='GPS_Records.txt:LAB2:Miami, FL'|}}@*
@b{@verb{|   epts --file='GPS_Records.txt:LAB2:LAB16'|}}

@cindex GPS database
@cindex database, GPS
@Subsubheading{Example GPS Record Database,
               ...........................}

Each record lives on a seperate line. Note the range of available coordinate 
formats. Blank lines and lines beginning with the hash character ('#'), are 
interpreted as comments and will be ignored.

@verbatim
# ---------------------------------------------------
# The Not Fully United Kingdom.
# ---------------------------------------------------
#                                              INDEX
#                                              -----
# London, England                                0
London         : 51 30 26.0 : -0 7 39.0

# Edinburgh, Scotland                            1
Edinburgh      : 55.953056 : -3.188889

# Cardiff, Wales                                 2
Cardiff        : 0.898525R : 3.086106R

# Belfast, Northern Ireland                      3
Belfast        : 54.596521 : -5.930578
@end verbatim

Three GPS database files are included with the AnsiCmd package:@*
@verb{|   'US_Capitols.txt', 'UK_GPS.txt' and 'testpoints.txt'|}.
@end indentedblock
@spi


@c = = = = = = = = = = = = = =
@c =    --formula option     =
@c = = = = = = = = = = = = = =
@cindex formula option
@cindex option, formula
@anchor{formula option}
@ifnothtml
@w{ @minus{}@minus{}formula  Formula for arc calculation.}

@end ifnothtml
@html
<span style="font-size:110%;"><span style="font-weight:bolder;"> &ndash;&hairsp;&ndash;formula</span>
<span style="margin-left:2.0em;">
Formula for arc calculation.
</span></span>
@end html
@indentedblock

Select the formula to be used for calculation of the arc distance between 
the two specified GPS coordinates.@*
(Three(3) characters are sufficient to uniquely identify the argument.)

Available formulae:
@example
@b{lambert}    The Lambert formula calculates the arc on an ellipsoid.
@b{haversine}  The Haversine formula calculates the arc on a sphere.
@b{all}        Displays the calculations for all supported formulae.

Examples:
   epts --coa='36.1:-14.3' --cob='37.7:-12.4' @b{@t{--form=lambert}}   (default)
   epts --coa='36.1:-14.3' --cob='37.7:-12.4' @b{@t{--form=haversine}}
   epts --coa='36.1:-14.3' --cob='37.7:-12.4' @b{@t{--form=all}}
@end example

Additional formulae may be implemented in a future release.
@end indentedblock
@spi


@c = = = = = = = = = = = = = =
@c =    --convert option     =
@c = = = = = = = = = = = = = =
@cindex convert option
@cindex option, convert
@anchor{convert option}
@ifnothtml
@w{ @minus{}@minus{}convert  Convert coordinate formatting.}

@end ifnothtml
@html
<span style="font-size:110%;"><span style="font-weight:bolder;"> &ndash;&hairsp;&ndash;convert</span>
<span style="margin-left:2.0em;">
Convert coordinate formatting.
</span></span>
@end html
@indentedblock

Convert one(1) latitude or longitude value from the given format to the 
alternate supported formats and display the results.

The @t{'convert'} option takes one argument of the form:@*
@verb{|   --convert=GPS_COORDINATE_VALUE|}

This option is useful primarily for debugging the input-parsing routines; 
however, it may also be useful for experimenting with the various GPS 
coordinate value formats.

Example coordinate values and the report generated:

@example
@b{@t{epts --convert='-80 57 56.91666'}}
   Converted Value:
    dec:-80.965810      decimal degrees (degrees+minutes+seconds)
    deg:-80.000000      degrees component
    min: 57.000000      minutes component
    sec: 56.916660      seconds component
    rad: 1.728473       radians
    fmt: vfSec          source format identifier (enum valFmt)

@b{@t{epts --convert=4.2579R}}
   Converted Value:
    dec:-63.959700
    deg:-63.000000
    min: 57.000000
    sec: 34.918520
    rad: 4.257900
    fmt: vfRad
@end example
@end indentedblock
@spi


@c = = = = = = = = = = = = = =
@c =     --color option      =
@c = = = = = = = = = = = = = =
@cindex color option
@cindex option, color
@anchor{color option}
@ifnothtml
@w{ @minus{}@minus{}color  Specify color attribute for application.}

@end ifnothtml
@html
<span style="font-size:110%;"><span style="font-weight:bolder;"> &ndash;&hairsp;&ndash;color</span>
<span style="margin-left:2.0em;">
Specify color attribute for application.
</span></span>
@end html
@indentedblock

Specify the foreground and background color attributes for display of the 
output. The terminal window's color attributes are used by default.

If the @b{@t{--window}} option is used, then the window's border 
attributes may also be specified. (Border attributes, if specified, 
are ignored for TTY output.)

The @t{'--color'} option may be used to specify alternate attributes. 
The format of the arguments takes the form:@*
@verb{|   --color=text_fgnd:text_bkgnd[:border_fgnd:border_bkgnd]|}

Each color is specified as one of the following:@*
@example
   '@b{black}'       '@b{blue}'
   '@b{red}'         '@b{magenta}'
   '@b{green}'       '@b{cyan}'
   '@b{brown}'       '@b{grey}'

   '@b{dflt}' use terminal default attribute
@i{(The first four characters of the name uniquely identify the color.)}

Examples:
   @b{@t{epts --color=blue:grey}}       // blue text on grey background
   @b{@t{epts --color=green:dflt}}      // green text on default background
   @b{@t{epts --color=dflt:blue}}       // default text color on blue background

   // blue text, grey bkgnd, cyan border fgnd, black border bkgnd
   @b{@t{epts --color=blue:grey:cyan:black}}
   // default text fgnd:bkgnd, magenta border fgnd, blue border bkgnd
   @b{@t{epts --color=dflt:dflt:magenta:blue}}
@end example

@end indentedblock
@spi


@c = = = = = = = = = = = = = =
@c =    --verbose option     =
@c = = = = = = = = = = = = = =
@cindex verbose option
@cindex option, verbose
@anchor{verbose option}
@ifnothtml
@w{ @minus{}@minus{}verbose  Report verbose results.}

@end ifnothtml
@html
<span style="font-size:110%;"><span style="font-weight:bolder;"> &ndash;&hairsp;&ndash;verbose</span>
<span style="margin-left:2.0em;">
Report verbose results.
</span></span>
@end html
@indentedblock
The standard arc-distance report displays the coordinates in both degrees 
and radians, and then displays the arc-distance in both kilometers and 
miles, calculated using the specified formula.

The verbose arc-distance report displays the same information, except 
that the coordinate values in degrees are broken down into their component 
parts: Degrees, Minutes and Seconds.

@ifnothtml
@sp 1
@end ifnothtml
@H5heading{Standard Report:,
           ▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔}
@verbatim
Miami, FL                         Buenos Aires, AR
======================            ======================
LATITUDE    LONGITUDE             LATITUDE   LONGITUDE
----------  ----------            ----------  ----------
  0.44986     1.74169  Radians      2.53765     2.12264
 25.77516   -80.20862  Degrees    -34.60333   -58.38167
@end verbatim
@verb{|       Distance: |}@b{@verb{|12905.069560 km  (8018.838378 mi)|}}
@ifnothtml
@sp 1
@end ifnothtml
@H5heading{Verbose Report:,
           ▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔}
@verbatim
Miami, FL                         Buenos Aires, AR
======================            ======================
LATITUDE    LONGITUDE             LATITUDE   LONGITUDE
----------  ----------            ----------  ----------
  0.44986     1.74169  Radians      2.53765     2.12264
 25.77516   -80.20862  Degrees    -34.60333   -58.38167
       25         -80  Deg(int)         -34         -58
       46          12  Minutes           36          22
       31          31  Seconds           12          54
@end verbatim
@verb{|       Distance: |}@b{@verb{|12905.069560 km  (8018.838378 mi)|}}
@end indentedblock
@spi


@c = = = = = = = = = = = = = =
@c =     --window option     =
@c = = = = = = = = = = = = = =
@cindex window option
@cindex option, window
@anchor{window option}
@ifnothtml
@w{ @minus{}@minus{}window  Display report in a window.}

@end ifnothtml
@html
<span style="font-size:110%;"><span style="font-weight:bolder;"> &ndash;&hairsp;&ndash;window</span>
<span style="margin-left:2.0em;">
Display report in a window.
</span></span>
@end html
@indentedblock

By default, the arc-distance report is displayed in the terminal window 
using common TTY (Teletype) style output. This output is formatted using 
basic ANSI escape sequences.

Optionally, the arc-distance report may be formatted within an ACWin-class 
window object positioned within the terminal window. The ACWin class  is 
derived from the base AnsiCmd class and implements more advanced @t{ANSI} 
formatting. It is designed to resemble an @t{'@b{ncurses}'} dialog window.

Please @pxref{ACWin Class} for more information.

By default, the dialog window is positioned with the origin (upper-left corner) 
at row one(1), column four(4) of the terminal window. However, any position 
within the terminal window may be specified using parameters of the form: 
@t{'@b{row:column}'}. 

The row and column are 1-based offsets from the upper-left corner of the 
terminal window. @xref{cursor offsets} for a discussion of 1-based versus 
0-based terminal offsets.

Additionally, specifying a zero (0) value for either parameter indicates that 
the dialog is to be centered in that dimension. See examples below.

If the specified position would place any part of the dialog beyond the 
boundaries of the terminal window, then the position will be automatically 
adjusted to ensure that the entire dialog is visible.

Examples:@*
@b{@verb{|   epts --window      |}} // no position specified, use default 1:4@*
@b{@verb{|   epts --window=2:1  |}} // positioned at row 2, column 1@*
@b{@verb{|   epts --window=12:0 |}} // positioned at row 12, centered horizontally@*
@b{@verb{|   epts --window=0:5  |}} // centered vertically, and at column 5@*
@b{@verb{|   epts --window=0:0  |}} // centered both vertically and horizontally@*
In the following example, the row specified is beyond the number of rows 
in the terminal window, so the vertical offset will be automagically adjusted 
such that the lower edge of the dialog is on the bottom row of the terminal 
window:@*
@b{@verb{|   epts --window=99:0 |}} // auto-adjusted row, and centered horizontally@*

@ifnothtml
@verbatim

  ┌─┤ EarthPoints v:0.0.03 (c) 2022-2023  The Software Samurai ├─┐
  │   Miami, FL                         Buenos Aires, AR         │
  │   ======================            ======================   │
  │   LATITUDE    LONGITUDE             LATITUDE   LONGITUDE     │
  │   ----------  ----------            ----------  ----------   │
  │      0.44986     1.74169  Radians      2.53765     2.12264   │
  │     25.77516   -80.20862  Degrees    -34.60333   -58.38167   │
  │           Distance: 12905.069560 km  (8018.838378 mi)        │
  │                                                              │
  │                   Press Any Key to Exit....                  │
  └──────────────────────────────────────────────────────────────┘
@end verbatim
@end ifnothtml
@ifhtml
@indentedblock
@html
<div class="tscap" style="background-color:#993300; max-width:38.00em; line-height:1.165em;"><span class="br_r">┌─┤ EarthPoints v:0.0.03 (c) 2022-2023  The Software Samurai ├─┐</span>
<span class="br_r">│</span><span class="br_n">   Miami, FL                         Buenos Aires, AR         </span><span class="br_r">│</span>
<span class="br_r">│</span><span class="br_n">   ======================            ======================   </span><span class="br_r">│</span>
<span class="br_r">│</span><span class="br_n">   LATITUDE    LONGITUDE             LATITUDE   LONGITUDE     </span><span class="br_r">│</span>
<span class="br_r">│</span><span class="br_n">   ----------  ----------            ----------  ----------   </span><span class="br_r">│</span>
<span class="br_r">│</span><span class="br_n">      0.44986     1.74169  Radians      2.53765     2.12264   </span><span class="br_r">│</span>
<span class="br_r">│</span><span class="br_n">     25.77516   -80.20862  Degrees    -34.60333   -58.38167   </span><span class="br_r">│</span>
<span class="br_r">│</span><span class="br_n">           <span class="bl_n">Distance: 12905.069560 km  (8018.838378 mi)</span><span class="br_n">        </span><span class="br_r">│</span>
<span class="br_r">│</span><span class="br_n">                                                              </span><span class="br_r">│</span>
<span class="br_r">│</span><span class="br_n">                  <span class="re_r">  Press Any Key To Exit...  </span>                </span><span class="br_r">│</span>
<span class="br_r">└──────────────────────────────────────────────────────────────┘</span>
</div>
@end html
@end indentedblock
@end ifhtml

Please visit the author's website to download the NcDialog API, and for a 
discussion of full-featured dialog windows based on the ncurses library. 
@ifnothtml
@*
@end ifnothtml
@xref{By the Same Author} for details.
@end indentedblock
@spi


@c = = = = = = = = = = = = = =
@c =     --dump option       =
@c = = = = = = = = = = = = = =
@cindex dump option
@cindex option, dump
@anchor{dump option}
@ifnothtml
@w{ @minus{}@minus{}dump  Dump GPS file contents.}

@end ifnothtml
@html
<span style="font-size:110%;"><span style="font-weight:bolder;"> &ndash;&hairsp;&ndash;dump</span>
<span style="margin-left:2.0em;">
Dump GPS file contents.
</span></span>
@end html
@indentedblock
Display and verify the formatting of GPS coordinate records contained in 
the specified file.

A database of GPS coordinate records is a plain text file with a series of 
records in the form:@*
@verb{|   Phoenix, AZ : 33 26 53.15 : -112 5 49.54|}@*
consisting of three(3) fields, seperated by colons (':').@*
@verb{|   Label       : Latitude    : Longitude|}

Formatting of the record is described in the 
@ifnothtml
@*
@end ifnothtml
@ref{GPS Coordinate Records} section, above.

When constructing a database of GPS coordinate records, the syntax of the 
records should be verified. 
@ifhtml
@*
@end ifhtml
The syntax of each record in the database is 
verified using the @t{"--dump"} option.

Example:@*
@b{@verb{|   epts --dump='US Capitols.txt'|}}

The following is the output for the scan of the @t{'testpoints.txt'} file 
included in this package.

@verbatim
EarthPoints (epts) v:0.0.03 Copyright(c) 2022-2023  The Software Samurai
========================================================================
Validate contents of GPS record file: 'testpoints.txt'
------------------------------------------------------
00) :25 46 30.5868 : -80.208615                             (OK)
01) Miami, FL : 25 46 30.5868 : -80.208615                  (OK)
02) Buenos Aires, AR : -34 36 12.0:-58 22.90                (OK)
03) Indianapolis, IN : 39.768611 : -86.158056               (OK)
04) Lafayette, IN : 40.417222 : -86.878611                  (OK)
05) San Francisco, CA : 37.7775 : -122.416389               (OK)
End-Of-File
@end verbatim

If a syntax error is found, it will be indicated by a status of 
@LDQ{}(?)@RDQ{}.@*
For example, this record is missing the madatory field delimiter @t{':'} 
between the Label and Latitude fields.@*
@verb{|01) Miami, FL   25 46 30.5868 : -80.208615                  (?)|}
@end indentedblock
@spi


@c = = = = = = = = = = = = = =
@c =     --help option       =
@c = = = = = = = = = = = = = =
@cindex help option
@cindex option, help
@anchor{help option}
@ifnothtml
@w{ @minus{}@minus{}help  (or @minus{}h)  Display command-line help.}

@end ifnothtml
@html
<span style="font-size:110%;"><span style="font-weight:bolder;"> &ndash;&hairsp;&ndash;help &nbsp;&nbsp; (or &ndash;h)</span>
<span style="margin-left:2.0em;">
Display command-line help.
</span></span>
@end html
@indentedblock
Command-line Help. Display a brief summary of command-line usage and 
options. (overrides everything on command line except @w{@t{'--version'})}

@verbatim
   EXAMPLES:  epts --help
              epts -h
@end verbatim
@end indentedblock
@spi


@c = = = = = = = = = = = = = =
@c =   --helpless option     =
@c = = = = = = = = = = = = = =
@cindex helpless option
@cindex option, helpless
@anchor{helpless option}
@ifnothtml
@w{ @minus{}@minus{}helpless  (or @minus{}hl)  Display command-line help.}

@end ifnothtml
@html
<span style="font-size:110%;"><span style="font-weight:bolder;"> &ndash;&hairsp;&ndash;helpless</span>
<span style="margin-left:2.0em;">
Display command-line help.
</span></span>
@end html
@indentedblock
Display command-line help. Same as the @t{'--help'} option above except 
that the help menu will be piped through the @t{'less'} utility.

@verbatim
   EXAMPLES:  epts --helpless
              epts -hl
@end verbatim
@end indentedblock
@spi


@c = = = = = = = = = = = = = =
@c =    --version option     =
@c = = = = = = = = = = = = = =
@cindex version option
@cindex option, version
@anchor{version option}
@ifnothtml
@w{ @minus{}@minus{}version  Report EarthPoints version number.}

@end ifnothtml
@html
<span style="font-size:110%;"><span style="font-weight:bolder;"> &ndash;&hairsp;&ndash;version</span>
<span style="margin-left:2.0em;">
Report EarthPoints version number.
</span></span>
@end html
@indentedblock
Display the EarthPoints version number and copyright information.@*
(overrides everything else on the command line)

To @b{@emph{also}} report the AnsiCmd-class version number, append an 
@t{'a'} to the argument.

@verbatim
   EXAMPLES:  epts --version
              epts --versionA
@end verbatim
@end indentedblock
@sp 2

@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
@raisesections


