[teqc] helpful tip of week 1897

Lou Estey lou at unavco.org
Thu May 19 07:35:12 MDT 2016

This week's tip: making (more) sense of '-' vs. '+' teqc options

If you have ever wondered why some teqc options start with '-' and some with '+',
then you are not the first.  Last week's tip mentioned that teqc's design was rooted
on UNIX command line usage and the same is roughly true of teqc's option design.

Some early UNIX command options had no '-' or '+' prefix on their options. The
command `tar` (originally, "tape archive") is a good example.  Even today, you
might perform one of several basic `tar` operations, like create a tar file, i.e.
usage from `man tar`: tar c[BDeEFhilnopPqTvw@[0-7]][bfk][X...] ...
Notice that the options are all one letter.

Other early UNIX commands used a '-' to designate one or more options, like `ls`
("list"):  ls [-aAbcCdeEfFghHilLmnopqrRstuvVx1@] ...
again with one letter for each option.

And with one letter options, it's hard to develop a mnemonic to map each option's
letter to its function.

Some more recent UNIX/Linux commands use one-letter and multi-letter equivalents,
like `rsync`, with '-h' = '--help', and '-v' = '--verbose', and '-q' = '--quiet'.

When the code that was to become teqc was being written, it was becoming clear
fairly early on that:

   - trying to use just one letter for options was going to be insufficient

   - many options were going to require both an 'off' and an 'on' state and, even
     though there would be a default setting, it needed to be clear which the user
     was doing

   - other options were going to refer to an 'input', with a different functionality
     for the option for 'output'

At the start, there were a few one-letter options for teqc.  (The few that remain
today are from the early code development.)

It was decided to use a '-' and '+' to turn toggle options "off" or "on". Hence,
'-qc' means you are not doing qc (the default) and '+qc' means that you are.
(One major exception: '-help' = '+help'.)

Also, '-' was used to mean an "input" and '+' for an "output"; thus '-nav' to
specify a list of specific RINEX navigation files to input for doing a qc and
'+nav' to specify a list of RINEX navigation files to output during translation;
'-binex' means the input should be interpreted as BINEX and '+binex ...' means
to output BINEX (after reading the input data).

If there is no on/off or input/output, then either '-' or '+' should work.  For
example, using '-jav jps' is equivalent to '+jav jps', that is, interpret the input
as Javad JPS format.  Again, the major exception is '-help' = '+help', because if
you are trying to get help, you don't want to be worrying about the option's sign!

There are a few teqc options with '++'.  E.g. `teqc ++igs` means "output the
current list of IGS equipment names and exit" and `teqc ++sym` means "output
the list of qc symbols and exit".  There is also a growing list of special
output options using '-', '+', and '++', e.g.:

teqc +help | grep event
         +event[s] .          output any event info to stdout
         +event[s] ..         output any event info to stderr
         +event[s] name       output any event info to file 'name'
         ++event[s] name      append any event info to file 'name'
         -event[s]            don't output event info (default)

where '-' means don't output anything (i.e. the "off" state), '+' means
to output and '++' means to append (to an existing file).

I hope this gives you a better idea of why certain option signs were used with
teqc as you make your way through the menagerie of its options.


Louis H. Estey, Ph.D.              office:  [+001] 303-381-7456
UNAVCO, 6350 Nautilus Drive           FAX:  [+001] 303-381-7451
Boulder, CO  80301-5554            e-mail:  lou  unavco.org
      WWW:  http://www.unavco.org   http://jules.unavco.org

"If the universe is the answer, what is the question?"
                                                -- Leon Lederman

Past helpful tips:

week 1894: using teqc config files - http://postal.unavco.org/pipermail/teqc/2016/002067.html
week 1895: qc of high-rate data - http://postal.unavco.org/pipermail/teqc/2016/002071.html
week 1896: UNIX/Linux shells for Windows - http://postal.unavco.org/pipermail/teqc/2016/002072.html

More information about the teqc mailing list