
Ringlink 2.0
============


INTRODUCTION

Ringlink is a CGI Perl program that provides the tools necessary
to run and administrate rings of websites. You are permitted to
make use of it for free, but if you intend to copy, modify or
redistribute Ringlink, you must make sure that your actions are
in compliance with the terms of the GNU General Public License,
included in the file LICENSE.TXT in this distribution.

The address of the Ringlink homepage is http://www.ringlink.org/.
If you encounter problems when installing or using Ringlink, you
find a couple of tips at the homepage about how to get help. You
are strongly recommended to subscribe to the Ringlink-open
mailing list in order to keeping yourself posted on the
development of Ringlink. (See the homepage for info about how to
subscribe.)


UPGRADE NOTE

If you are upgrading from version 1.2, please note:

- Extensive changes of the program code have been made, e.g. in
  order to make the code pass "use strict" and "-w" tests.
  Accordingly, every single program file should be replaced, and
  all customization you might have done in the *.pl/*.cgi or *.pm
  files, possibly with the exception of mainhtml.pm, admhtml.pm,
  and mailhtml.pm, needs to be moved to the new program files.

- As regards mainhtml.pm, admhtml.pm, and mailhtml.pm, besides a
  couple of other things, all the Perl variables have been
  changed. Basically they were changed from $::something to
  $rlmain::something. If you consider to keep your customized
  copies of those files, check the Ringlink CVS repository for
  details.
  http://cvs.ringlink.org/cgi-bin/viewcvs.cgi/ringlink/Ringlink/

- Previously customized HTML code and certain other ring data
  include Perl variables, e.g. $::sitetitle. In version 2.0 those
  variables have been replaced by 'substitutes', e.g.
  [sitetitle]. The program is still compatible with previously
  saved ring data, but the documentation for your Ringlink
  installation might need to be updated.

- The previous file gentools.pm has been replaced by rlmain.pm.

- There are a few new files and directories due to the fact that
  version 2.0 is internationalized.

- The variable $rlmain::cgipath (previously $::cgipath), storing
  the path to the directory with the *.pl or *.cgi files, does no
  longer need to be set in rlconfig.pm.


INSTALL

You should have received the following files with this
distribution:

    README.TXT (this file)
    LICENSE.TXT

    /ringlink/index.html
             /ringlink50x51blk1.gif
             /ringlink50x51grlk1.gif

    /ringlink/mod_perl/ringlink_mod_perl.conf
                      /startup.pl

    /cgi-bin/ringlink/admin.pl
                     /goto.pl
                     /home.pl
                     /langinstall.pl
                     /list.pl
                     /newring.pl
                     /newsite.pl
                     /next.pl
                     /next5.pl
                     /prev.pl
                     /prev5.pl
                     /rand.pl
                     /ringadmin.pl
                     /siteadmin.pl

    /cgi-bin/ringlink/data/.htaccess

    /cgi-bin/ringlink/lang/en.po
                          /es.po
                          /fr.po
                          /ringlink.pot
                          /sv.po

    /cgi-bin/ringlink/lib/.htaccess
                         /admhtml.pm
                         /mailhtml.pm
                         /mainhtml.pm
                         /ring.pm
                         /rlconfig.pm
                         /rlmain.pm
                         /site.pm

    /cgi-bin/ringlink/lib/Locale/PGetText.pm

    /cgi-bin/ringlink/lib/Mail/Sender.pm

You will need to do some preparations before you upload them on
your server:

1. If you are going to install Ringlink in a Unix environment,
   you must make sure that the first line of each CGI file, i.e.
   those with the file extension .pl, points to the appropriate
   Perl program on your server (has to be Perl 5 or later).

2. The directory with program specific Perl modules (the *.pm
   files in the distribution) is called the Ringlink library. In
   order to let Perl know where to look for the library, the
   third line of each CGI file looks like this:

       use lib 'lib';

   This command presupposes that the Ringlink library is a
   subdirectory to the directory with the CGI files, and that the
   subdirectory is named 'lib'. When installing Ringlink in a
   Unix or Linux environment, the command will normally not need
   to be edited. However, when installing it on a NT server, you
   should edit the command to include the full path to the
   Ringlink library. It may look something like this:

       use lib 'd:/scripts/ringlink/lib';

   Note, though, that there may be cases when the full path is
   required or advisable when installing Ringlink in a Unix or
   Linux environment as well. Compare 5. below.

3. Some systems need the file extension .cgi instead of .pl in
   the names of the CGI files in order to understand that the
   files shall be executed. If that's the case for you, you have
   to rename all the *.pl files to *.cgi.

4. There are two small .htaccess files included in the
   distribution. Their purpose is to prevent the files in the
   Ringlink library and the data directory from being readable
   from a browser, since some of those files will include
   sensitive information such as passwords and the ring members'
   email addresses. The .htaccess files might make a difference
   in this respect, but in many cases they don't:

   - They will only work on Apache servers.

   - A few Apache servers are configured not to let the server
     access be controlled by the users in this way.

   - On many servers with "real cgi-bins", reading access to all
     files and directories under the cgi-bin is prevented anyway.
     If that's the case for you, you can refrain from uploading
     the .htaccess files (even if they do no harm if you still
     use them).

   If you are on a server where the .htaccess files don't work,
   and the access hasn't been properly restricted otherwise, you
   are strongly recommended to study the discussion about this at
   http://www.ringlink.org/faq/miscellany.html#8

5. You will need to edit the rlconfig.pm file, but before you do
   that, you have to decide in which directories the files are
   going to be placed. Often you'd better follow the directory
   structure as described above, and edit the rlconfig.pm file
   accordingly. If you decide otherwise, e.g. in order to take
   care of the browser access issue mentioned in the previous
   section, please note the following:

   - Placing the CGI files somewhere under the cgi-bin directory
     is common practice, and required by some systems. If your
     system allows it, you can put them whereever you like, as
     long as you put all the 14 files in the same directory.

   - If the Ringlink library is some other directory than the
     subdirectory 'lib' to the directory with the CGI files, you
     need to change the "use lib 'lib';" command accordingly.
     (See 2. above.)

   - The index.html file can be put whereever you like, as long
     as it can be read by the visitors of your site. (Unlike the
     CGI files, the *.pm files, the ??.po files, and the
     .htaccess files, you are also free to rename index.html to
     whatever you prefer. This file is intended to work as a
     template when you create the "homepage" of your Ringlink
     installation.)

   - The files with the registered ring and site info will be
     saved in the data directory. You can place the data
     directory whereever you like (and it does not necessarily
     need to be named 'data').

6. The files ringlink_mod_perl.conf and startup.pl are example
   files, and they are included in the distribution only as a
   help to them who want to run Ringlink under mod_perl. 

Now you are ready to create the necessary directories and upload
the files.

* If you use FTP to upload the files, make sure that they are
  uploaded in ASCII mode. The .gif files shall be uploaded in
  binary mode, though.

* PGetText.pm shall be placed in a subdirectory to the Ringlink
  library, and that subdirectory shall be named 'Locale'.

* Sender.pm shall be placed in a subdirectory to the Ringlink
  library, and that subdirectory shall be named 'Mail'.

* The ??.po files shall be placed in a subdirectory to the
  directory with the CGI files, and that subdirectory shall be
  named 'lang'.

* You need to create an empty subdirectory to the 'lang'
  directory, which shall be named 'mo'.

* Chmod the CGI files 755.

* Chmod the data directory and the 'mo' directory 777.

When you have uploaded all the files, and set the appropriate
file permissions, the first thing you need to do is to run
langinstall.pl. This will create the necessary language databases
in the 'mo' directory.

That should be it. Enjoy your Ringlink installation! And, when
it's up and running, I'd appreciate if you go to the Ringlink
Systems Directory at http://www.ringlink.org/directory/ and
submit your installation.


August 22, 2001

Gunnar Hjalmarsson
gunnar@ringlink.org


P.S.   Don't forget to backup the data files.

