NAME:
     authorproc
 PURPOSE: (one line)
     Create author lists for LaTeX manuscripts
 DESCRIPTION:
  This tool automates the building of a AASTeX formatted authorlist for inclusion
    in a manuscript along with a separate file of acknowledements.  All of the
    control inputs are carried in a configuration file (usually config.ini) in
    a directory where the output files are to be written.  Other than control
    inputs, this program expects to find a tab-separated file containing the
    raw data for the author list.  This file is usually created via a Google form
    that the observers fill out with their information.  That form is then
    exported for use by this program.  The file names are normally named with
    embedded version date information and the file that sorts alphabetically to
    the end of the list is used to build the output files.

  This program attempts to validate the information.  Some errors are just noted
    to the terminal while others will cause the program to quit prematurely and
    not write any output files.  If there are any errors, you probably should not
    use the output files until the errors are eliminated.
 CATEGORY:
     Publications
 CALLING SEQUENCE:
     authorproc, cfgfile, /verbose
 INPUTS:
     cfgfile = Configuration file to control behavior (default = 'config.ini')
               (must contain fields and campaigns keywords)
 OPTIONAL INPUT PARAMETERS:
 KEYWORD PARAMETERS:
     verbose = Flag, if set will increase number of processing status messages
 OUTPUTS:
   The primary output of this program is a set of files and are written to the current
     directory..  Previous versions of these files are silently overwritten.
     authorlist.tex - Markup text for the author list.  This uses the AASTeX package
                        commands for building the author list.
     acktext.tex - A block of text that can be added to the acknowledgement section.
                      This is built from the list of respondents not requesting to be
                      authors.
     master.email - A list of email addresses for the authors, one address per line
     allraw.txt - A list of all participants, one name per line but with a comma
                     after each name but the last.  The order is randomized.
     allauth.txt - A list of all authors, one name per line but with a comma after
                     each name but the last.  The order matches the publication order.
 COMMON BLOCKS:
 SIDE EFFECTS:
 RESTRICTIONS:
  It is a bad idea to directly edit the output of this program even though that
    might seem like the easy thing to do.  The correct process is to edit the
    source google spreadsheet, re-export the file, and run this program again until
    the output correct.
 PROCEDURE:
  grep this file for getvalue to see all the controls from the config file, some
    of the less obvious or more complicated controls are described here.
  [authorlist]
    pubdir - This is the directory where the .tsv files are to be found.  
    campaigns -  This is a blank delimited list of campaigns for this publication.
                    It is required that there is one .tsv file for each campaign
                    in this list.  There must be at least one campaign.  Every
                    campaign must have its own section in the config file with
                    information needed to control decoding the information and
                    varying options.

  [CAMPAIGN]
    There need to be as many sections as there are campaigns to be aggregated
      for the final list.  Replace "CAMPAIGN" with the official name of the campaign,
      usually something like PA20220722 where the first two characters are from the
      object or project and the rest is the UT date of the event.
    The following are required items:
      fields - This is a list of seven integers, blank delimited, that identify
         which columns of the tsv file are to be used for the main input information
         from the .tsv file for this campaign.  The seven numbers refer, in turn,
         to the following conceptual field values:
            fields[0] = publication order (primary sort key)
            fields[1] = Last name of the respondent (secondary sort key)
            fields[2] = First name plus any initials of the respondent
            fields[3] = Category of respondent (not used by this program)
            fields[4] = Email address of respondent (required only for authors)
            fields[5] = Institution code (not the full institution)
            fields[6] = ORCID
         There are usually many more columns in the .tsv file than used by this program.
    The following are optional items:
       CJK - Name in unicode characters for a Japanese alphabet name, blank delimited
       Arabic - Name in unicode characters for a name in Arabic form, blank delimited

    The .tsv file is the last file matching the pattern of
         pubdir+campaigns[i]+'_*.tsv'

  There must also be a file named "address.tsv" in the current directory.  This file
    is a tab-delimited file with two columns.  The first column is the institution
    code (fields[5]).  The second column is the full name of the institution to be
    included in the authorlist.  All authors must have a code that resolves to a
    value in this file.
   
 MODIFICATION HISTORY:
  2023/12/09 - Written by Brian Keeney, SwRI, based on template from Marc Buie