NAME

       starconvert - convert text data files to StarPlot format

SYNOPSIS

       starconvert [ options ] spec-file input-file [ output-file ]

DESCRIPTION

       Although  many stellar data files are publicly available on the Internet from NASA and other astronomical
       organizations, there is no set format for these files.  The program starconvert acts as a buffer  between
       this  confusion  and the format in which StarPlot requires data files.  To do so, it uses a specification
       file that details how various fields of stellar data (name,  distance,  right  ascension,  etc.)  may  be
       extracted from the original data file.

       On the StarPlot web site are available some packages of data that include both an original data file from
       NASA, and also a  specification file.  These  packages  are  referred  to  as  "data  sets",  from  which
       starconvert  can  produce  a  data file in StarPlot format.  For ease of use, this should be done via the
       starpkg(1) shell script.

       The starconvert command uses the specifications in spec-file  to  convert  input-file  to  StarPlot  data
       format  and  writes  the  results  to output-file if specified, or standard output if not.  The first two
       arguments are required.  Exactly ONE may be replaced with a dash `-' for reading from standard input.

OPTIONS

       --     Signals the end of the options.  This allows you to use a spec-file whose filename begins with the
              '-' character.

       --add-sun
              Add  an entry for the Sun to the generated StarPlot-format data file, if it is not already present
              in the original raw data file.  This is the default behavior, so this flag has an effect  only  if
              it reverses an earlier --no-add-sun flag.

       --no-add-sun
              Do  not  add an entry for the Sun to the generated StarPlot-format data file, unless it is present
              in the original raw data file.  Adding the Sun is otherwise  done  by  default,  since  most  star
              catalogs do not include it.

SPECIFICATION FILES

       For  detailed  information  on  how to write a specification file, see the example file listed below.  Be
       aware that I expect to change the default format of starconvert spec files after  version  1.0,  although
       starconvert will remain backwards-compatible.

FILES

       /usr/share/doc/starplot/ - Contains documentation
       /usr/share/doc/starplot/examples/example.spec - Example specification file

SEE ALSO

       starplot(1), starpkg(1)

AUTHOR

       Copyright  ©  2000-2002  under the GNU GPL by Kevin B. McCarty <starplot@starplot.org>.  The StarPlot web
       page is at www.starplot.org.

                                                    Nov 2002                                      starconvert(1)