@(#)INSTALL	1.1 5/9/91 
The first step to installing rkive is to customize the configuration to
suit your local needs. In the past, you had to take a fresh distribution 
and edit the rkive.h file and Makefile to suit local preferences. If you
had many local changes, or didn't record the local changes, upgrading
could be a pain...

Nearly every site will need to make changes to the rkive configuration
as distributed.  Local configuration of the rkive software requires you 
to edit a couple files. The rkive.h and Makefile files must be created 
from their templates rkive.h.dst and Makefile.dst.  You should create a 
shell script called localize.sh which copies the files and makes local 
changes to the copies.  A sample localize shell script can be found in 
localize.smpl.  

The localize.sh shell script you create should copy rkive.h.dst to rkive.h, 
and copy Makefile.dst to Makefile.  It should chmod the files so that your
script can make changes and write the changes out.  It should then invoke 
ed(1) on the files, making any necessary local changes.  Use localize.smpl
as a reference if you need to.  The easiest thing to do is just copy the
localize.smpl to localize.sh and make your local changes to that. It contains
just about every configurable parameter specified in rkive.h and the Makefile.
Just delete the entries that you don't want to change and modify the ones
you do...

Once you're finished editing localize.sh, create a rkive.h and Makefile 
tailored for your site with the command

    sh ./localize.sh

Inspect rkive.h and Makefile to ensure that all your local customizations
got into your final versions. If you saw a "?" when you ran localize.sh, 
one or both of the files is certainly wrong. It's a good idea to anchor 
the patterns in localize.sh's ed(1) scripts. For instance, use /^BINDIR/
instead of /BINDIR/.

Now that you know how to do it, just what things do you need to consider 
when customizing rkive ?

RKIVE.H:

Ownership: (OWNER, GROUP)
    Who will the default owner of the archives be ? You might want to
    consider setting up a user and group just to support the archives for
    a little added security... Values specified in rkive.h are overridden
    by values specified in the rkive.cf configuration file.


File Modes: (MODES, DIR_MODE)
    What will the default modes of the files be when created. What will
    the default directory modes be on creation ?  I personally like to keep
    the archives as just that. Let the others copy the files to another location
    to unpack. For that reason, I keep file creation as readable by all, 
    writable by none...  Values specified in rkive.h are overridden by
    values specified in the rkive.cf configuration file.


Mailer: (SUBJECT_LINE, MAIL)
    If you have a smart mailer that supports a "-s subject" command
    and you wish to have the subject line added when archived mail
    is sent, define SUBJECT_LINE.  Specify which mail program to use
    to send the mail by setting MAIL.


Problem Article Storage: (PROBLEMS_DIR)
    The PROBLEMS_DIR is the default directory to use in the event 
    problems are encountered such as duplicate article names and the 
    execution flags do not specify overwriting. The new, inbound article 
    is stored in the PROBLEMS_DIR in problems_dir/newsgroup/volume/filename 
    so that the administrator can review and fix the problem whenever time 
    becomes available...  The PROBLEMS_DIR define is used only if the 
    administrator has not specified the PROBLEMS path variable inside of 
    the LOCATION (rkive.cf config) file.


News Spool Directory: (SPOOLDIR)
    I am sure you can figure this one out...


Location of the Rkive Configuration file: (LOCATION)
    This specifies the location of the default rkive configuration 
    file, rkive.cf.


Dealing With Repostings: (ADD_REPOST_SUFFIX,  REPOST_SUFFIX,  MV_ORIGINAL)
    If ADD_REPOST_SUFFIX is defined, all reposts will have the 
    string specified in REPOST_SUFFIX appended to the archive
    filename so that a repost of elm/part07 would appear in
    the archive as elm/part07-repost prior to any compression.
                        *** CAUTION ***
          This should *not* be used on a filesystem with 14 
          character file name limits. If you are going to be 
          making your archive available to the general community 
          do *not* use this. The portability of filenames is 
          greatly reduced. This has been added with much hesitation. 
          The rational was that there was no reason to punish/limit 
          the functionality just because of limitations of a specific 
          "brand" of unix and since that "brand" was correcting its 
          "error" in the future, why not put it in now ? This is *NOT*
          a configuration item on a per newsgroup basis. It might be 
          useful for Historical archiving using only Volume/Issue 
          archiving with no COMPRESSION.
  
    If MV_ORIGINAL is defined, the original article is placed into an
    "original" directory within the problems directory (if duplicated). 
    The inbound reposted article is placed into the archive in the correct 
    position.

    If No Reposting Defines are specified, the inbound article is placed 
    into the archive in the correct position only if the initial article 
    is not in the archive.  Otherwise the reposted article is placed in 
    the problems directory as a normal duplicate article is now.


Volume Directory Basename: (VOLUME)
    If you wish your volume directories to be Volume, VOL, vOLuMe
    or any other such nonsense, change the VOLUME define.


Zero Pad Volume Directory Names: (ZEROFILL)
    A very small change to construct change the volume directory names 
    from "volume1" to "volume01". In this manner all of the archive
    volume directories appear in lexical order instead of jumbled 
    together in directory listings. 


Removing Unnecessary Article Headers: (REDUCE_HEADERS)
    If you wish to have the headers "trimmed" when the file is archived,
    assure that REDUCE_HEADERS is defined. Currently all header lines that
    are not either;
        From:, Newsgroups:, Subject:, Message-ID: Approved:, and Date:
    will be removed. See news_arc.c if you wish to add or subtract header
    lines to keep. This can produce a savings of between 200 to 500 bytes
    per archived article.


Default Record Formats: (DEFAULT_INDEX_FORMAT, DEFAULT_LOG_FORMAT)
    These two defines specify a default format for generating either
    index or log file records in the event that there is no index or 
    log file format specified for either the newsgroup or for the global 
    default.  See article.1 for a discussion of the different types of 
    selection characters available for use in the format specifications.


How Many Newsgroups Are To Be Archived?: (NUM_NEWSGROUPS)
    The size of the group array. If you are archiving the world
    you might need to bump this up...


Chronological Archiving Storage: (NO_MONTH_DIR)
    The ifdef NO_MONTH_DIR is used to decide which way Chronological 
    archives are to be stored. By default for format is something like

          /usenet/alt/sources/volume89/Jun/890629.01
   
    If you wish not to have the month directory, define NO_MONTH_DIR
    and the archives will be stored as

         /usenet/alt/sources/volume89/890629.01


Which mkdir function do you want to use ?: (MKDIR, USE_SYSMKDIR)
    Define MKDIR if there is a mkdir() function in your 
    system library (AT&T 5.2 or earlier systems are probably
    out of luck..)
    Define USE_SYSMKDIR if you wish to system off /bin/mkdir.
    If you do not define either, the function makedir will
    create the directory itself. PLEASE ASSURE THAT IT WILL
    WORK FOR YOUR SYSTEM PRIOR TO USING IT... (Should work on
    System 5.3 and prior SYSV systems.)


MAKEFILE:

Do you wish to have this built with NNTP capabilities ?
    This requires that you have networking libraries and the
    NNTP source code available to you during compilation.
    You will need to specify the base directory location of 
    the nntp sources using NNTPSRCDIR. If you wish debugging
    turned on in NNTP, specify that using NNTPDEBUG. You should
    not have to touch the NNTPFLAGS, NNTPSRCS and NNTPOBJS.
    If you need EXCELAN networking support defined for nntp,
    uncomment EXOSFLAGS and EXOSLIBS.


Are you on a Sequent ?
    If so, uncomment SFLAGS and since there is not getopt() function
    available, uncomment GETOPTO and GETOPTC.



Is your system missing the getopt() function ?
    Uncomment GETOPTO and GETOPTC.


Which Compiler to use ? 
    Define your favorite C compiler using CC. 


Special Compilation Flags needed ?
    Use FLAGS to set special flags like -g or -O or -Wall...
    The list goes on...


YACC Compilation support:
    Set yacc flags using YFLAGS. Specify which yacc to use with YACC.


Directory Access Routines Location:
    rkive needs to have POSIX Compatible directory access routines.
    If you do not have it builtin to your system libraries then specify
    the -l option. If you use Doug Gwyn's routines, (or other compatible
    routines) define the library in which they appear such as -lndir or
    -lposix. 
    NOTE THE FOLLOWING PLEASE ...
       I really need to make it clear that I do not want to cobble up 
       the sources with directory access methods for every different 
       flavor of unix.  I did that with lc and it is truly ugly... :-(  
       If you don't believe me, look for yourself. I have adopted a policy 
       of using only the dirent directory access routines. Most vendors 
       are moving towards the POSIX directory access library compatibility 
       so it seemed like a good idea then and now. For the systems that do 
       not have that capability, I use Doug Gwyn's POSIX compatible directory 
       access library that was posted to c.s.unix.  Its well worth installing 
       and its availability can help you out in more than just rkive.
       I encourage you to send me patches for all you enhancements and fixes
       but do not send me patches to add support for your directory routines.


Additional Libraries:
    If your system requires additional libraries or if you wish to
    use shared libraries, add the -l declarations to LIBS below such
    as -lc_s


General Items:
    LP, PR, and NROFF let you configure those items as local taste
    suits you.


Where To Put Rkive Executables:
    Specify where you want to install the rkive executables by setting
    BINDIR.


Where To Put Rkive Support Files:
    Rkive has a couple of support files such as the rkive.cf and
    update_netdocs. You may want to put other rkive local external 
    commands somewhere are well. Use RKIVEDIR to specify where they
    should go.


**** NOTE ****

rkive can be called from the command line using the default rkive.cf or
you can specify a different one to use. If you rkive both from the sys
file and from cron or a command line you will most assuredly need more
than one .cf file. You can use different configuration files to logically
group operations by the time you want it run. An example might be that
you want to use the update_netdocs script (or some other external command)
to archive the monthly postings so that they are not checked each night.
The point here is that you have a lot of flexibility here and it is worth
you while to spend a little time deciding how you want to use rkive to
best suit your individual site needs.

