MessageSplit v1.00 - Documentation

                          Copyright (c) 1995
                by Robert B. Clark <rclark@iquest.net>
                        ClarkWehyr Enterprises
                This program is free for personal use.
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   Forte's Agent and Free Agent newsreaders allow you to save messages
   as ASCII text files.  Many people elect to save such messages into
   one big text file, and need some way to split that file back into
   individual articles.

   That's where MSGSPLIT comes in.

   Configuration:
   ~~~~~~~~~~~~~~
   In Agent, select File | Save Messages As... .  The lower part of
   the dialog box contains settings for "File Format" and "Header
   Fields to Include."  Your options are

   File Format
   -----------
    þ UNIX message file                Each message is preceded with
                                       "From user@domain.net date
                                       time".
    þ Precede each message with ...    Each message is preceded with a
                                       user-defined string.  The
                                       default string is "========\n".
    þ No separator between messages    Each message is followed by two
                                       blank lines.

   Header Fields to Include
   ------------------------
    þ All fields                       All header fields saved.
    þ Selected fields...               Only selected header fields
                                       saved.
    þ No fields (body only)            Only the article body is saved.

   MSGSPLIT uses the settings in this menu to determine how to extract
   articles and mail from your ASCII text file.

   Set the "File Format" toggle to either "UNIX message file" or
   "Precede each message with..."  These are the preferred settings
   for use with MSGSPLIT.

   The "No separator between messages" option is a poor choice because
   there is no unique string separating individual articles (two blank
   lines doesn't count, unfortunately).  If you do use this setting,
   MSGSPLIT will try to determine the start of an article by searching
   for the "From: " field in the header, so you should make sure that
   the saved text includes at least this header line if nothing else.

   MSGSPLIT reads these settings from your AGENT.INI file.  It will
   search the current directory first, then the directory in which
   MSGSPLIT.EXE resides, and finally each directory in your path.

   You may override this search by defining the separator string on
   the command line with the -S"separator" option.  Note that the
   quotes are required.  You'll need to use this switch if you do not
   use Agent, or if you have existing ASCII files saved to disk using
   a different separator scheme than that contained in your current
   AGENT.INI file.

   If for some reason the AGENT.INI file is invalid or is missing
   needed variables, MSGSPLIT will use the "From: user@domain.net"
   article header as a separator string.

   See the Agent Help item "Saving Messages As dialog box (File menu)"
   for additional information.


   Usage:
   ~~~~~~
   MSGSPLIT is a DOS application and must be run from the command line
   (a DOS box from within Windows is OK).

   Items in brackets ([]) are optional; those without brackets are
   required.  You may use either '-' or '/' to preface a parameter.

   Usage: MSGSPLIT [drive:][path]filename[.txt] [basename] [/Nmsg_num]
           [/S"separator"] [/?|/H]

     filename      Name of the concatenated ASCII file.
                   The extension defaults to .TXT if not specified.
     basename      Base filename of the extracted messages file(s).
                   The drive and path may be included if desired.
                   If not specified, defaults from the "filename" parameter.
     /Nmsg_num     Extracts only the msg_num'th message out of the file.
     /S"sep"       Case-sensitive separator string.  Mainly for use with
                   non-Agent newsreaders and to override AGENT.INI.

   Extracted messages will be named basename.001, basename.002, etc.
   Existing files will be overwritten without notification.

   Returns errorlevel 0 if an error occurred; otherwise returns the
   number of extracted message files.


   Examples:
   ~~~~~~~~~

   Let's assume that the AGENT.INI [Article] section contains

        [Article]
        SaveArticleFormat=1                    ; Use separator
        SaveArticleSeparator="\f\t\t===\n"     ; Separator string


   MSGSPLIT c:\agent\text       Extract all messages from C:\AGENT\TEXT.TXT
                                (separated by formfeed, tab, tab, =, =, =,
                                newline) and write each message to files
                                named C:\AGENT\TEXT.001, etc.
   MSGSPLIT text /n5 a:msg      Extract the fifth message from TEXT.TXT
                                (separated by formfeed, tab, tab, =, =, =,
                                newline) and write to A:MSG.005.
   MSGSPLIT text /s"Origin: "   Extract all messages from TEXT.TXT
                                (separated by "Origin: ") and write to
                                files named TEXT.001, etc.  This command
                                works well for QWK mail readers such as
                                Parson Consulting's RoboMail.

   Disclaimer:
   ~~~~~~~~~~~
   MessageSplit is freeware and no charges may be levied for this
   program other than a nominal media or access fee.  The author
   assumes no liability for the use or applicability  of this
   software.  By using this program, the user explicitly assumes all
   risk and responsibility.

                                 ###