TightURL
                            Installation
                           version  0.1.2a

  Installing TightURL
  -------------------

  1. Untar the file: tar zxvf tighturl-0.1.2.tar.gz

  2. Move the files in the directory to where you want to run
     your installation of TightURL.

  3. Rename tighturl.php to index.php if desired. (highly desirable!)

  4. A. New installations should move the contents of the ./local directory
        into the main TightURL directory.
     B. Upgrades should review the contents of ./local and adjust existing
        config file and templates as seen fit.

  5. New installations should create a MySQL database and user if
     necessary. If you don't know how, (we were all beginners once) it
     goes something like this:
       mysql -u root -p
       Enter password: **********     
       mysql> create database tighturl;
       mysql> quit

     If you also need to add a MySQL user (you should never use "root"),
     then before you quit MySQL, you should enter a command like this:

       mysql> grant all on dbname.* to dbuser@localhost identified by 'pass';

     substituting the name of your database for "dbname", the name of the
     MySQL user you want to create for "dbuser", and the desired password
     in place of "pass". 

  6. New installations should create the TightURL table. In the ./local
     directory, edit tighturl.sql if you don't want your table named
     "tighturl", (this line: "CREATE TABLE `tighturl` (")
     then:
     
     mysql -p yourdatabase <tighturl.sql

     where "yourdatabase" is the name of the database you're using.
     (You may have created this in step 5, and you've probably chosen
     to call it "tighturl".)

  7. Edit the config settings in tighturl.config.inc.php as needed.
     New installs will need to change at least the MySQL database settings.
     See 'Configuration Settings' below.

  8. If you can set a custom 404 page for your Web site/directory, you
     can set it to tighturl/index.php and get shorter URLs.  To take
     advantage of this, set $FOFMethod=TRUE in tighturl.config.inc.php.

  9. Change the $svcname in tighturl.config.inc.php if desired.

 10. Edit the master site HTML template tighturl.tmpl if desired.
     See 'TightURL Templates' below.

 11. Edit the HTML sub-templates if desired.  These are:
     A. tighturl.main.tmpl : HTML shown for your TightURL homepage
     B. tighturl.save.tmpl : HTML shown when a URL is saved
     C. tighturl.help.tmpl : HTML shown for Help info (may not exist yet)
     D. tighturl.faq.tmpl  : HTML shown for FAQ (may not exist yet)

     See 'TightURL Templates' below for more information.

  Configuration Settings
  ----------------------

  These are the configuration (variables) settings that can and should
  be changed in tighturl.config.inc.php :
  
  MySQL:
    $dbhost  : DNS name of your MySQL server
    $dbuser  : MySQL user name
    $dbpass  : password for MySQL user name
    $dbname  : database containing TightURL's table
    $dbtable : name of TightURL's table

  Operating modes:
    $rewriting : Use 404-Method or mod_rewrite to compress TightURLs
      0 (FALSE) = full URL path (not compressed) TightURLs
      1         = 404-Method compressed TightURLs
      2         = mod_rewrite compressed TightURLs
	
    URIBL variables:
      $uribl    : Array of URIBLs to check
      $uriblurl : Array of Web sites corresponding to URIBLs checked

  Text strings and style variables:
    $svcname    : One-word name for your TightURL service
    $verbtext   : One-word name for the act of tightening URLs
    $pasttext   : Past-tense name for a tightended URL
    $tagline    : "tag line" for your TightURL service
    $headcolor  : Color for the TightURL <H1> HTML header
    $tablecolor : Color for the table the URL input field appears in
    $copystart  : 4-digit year of start of your copyright on your content.
                  defaults to current year if not given.

  NEVER CHANGE SETTINGS IN tighturl.php OR YOU WILL LOSE YOUR CHANGES
  any time you upgrade to a newer version of TightURL.  Always put your
  configuration settings in tighturl.config.inc.php where they will 
  survive upgrades.  Values in tighturl.config.inc.php override the
  defaults (garbage) in tinyurl.php .

  Reserved URLs
  -------------

  Because we use Base-36 numbers as TightURL IDs, as time goes on,
  certain desirable URLs will be issued that we might want to keep
  for ourselves.

  For instance, the letters 'faq' are well-understood around the Internet
  to mean "Frequently Answered Questions".  We might want to use the URL
  http://example.com/faq to point to our FAQ page, rather than issue it
  as a regular TightURL to a random visitor.  Reserved URLs allow you to
  specify Base-36 IDs that should never be issued as TightURLs.

  There are two kinds of Reserved URLs.  External (implicit) and Internal
  (explicit) Reserved URLs.

    External Reserved URLs:
       
       Any URL which exists in your Web space will be served up by
       your Web server, and not TightURL.  For this reason, any URL
       reasonably within your TightURL ID space that you want to use
       with your TightURL site itself should be reserved so that you
       don't issue a TightURL to anyone that won't actually work.

       For example, if you have a directory named: /www/example.com/faq
       your Web server will attempt to serve index.html from within
       that directory, and TightURL will never even see the request.
       This kind of reservation is implicit, and TightURL must be
       made aware of it.

    Internal Reserved URLs:
      
      Any URL which does not exist in your Web space but is Reserved
      within TightURL will cause TightURL to look for a correspondingly
      named TightURL Template, and serve that.  If the template does
      not exist, a 404 error is generated.

      For example, if you have reserved the ID 'faq', and TightURL
      sees a request for this reserved ID, it will attempt to open a
      template named tighturl.faq.tmpl and return that to the browser.

  It is VERY IMPORTANT that you decide what your Reserved URLs will be
  before your TightURL service is put into operation, or else you run
  the risk of wanting to reserve a URL that's already been issued as
  a TightURL to someone.  For example, by the time you've issued your
  19826th TightURL, you will have lost the opportunity to use 'faq' as
  a Reserved URL, because decimal (Base-10) number '19826' is number 
  'faq' in sexigesimal (Base-36).

    Reserving URLs:
      
      To reserve a URL, add it to the configuration array $ReservedURL .
      The following URLs are reserved by default:

        faq, help, code, source, docs, cvs, arch, url,
        about, admin, setup, svn

  There is little point in reserving URLs larger than 5 charcters long.
  The first 6 character ID is '100000' sexigesimal, which would be far
  past your 60 millionth TightURL issued. Since each additional Reserved
  URL adds a little more processing time, you don't want to add URLs 
  that will never be issued anyway.

  TightURL presently uses the ID "api" with the template that describes
  how to use the TightURL API.  It would be the 13878th TightURL in the
  system, which can easily be achieved on a moderately-used corporate-
  wide TightURL installation.

  TightURL Templates
  ------------------
  TightURL supports a simple variable-substitution templating system with
  one level of template nesting.

  The outer template is *always* the main site template, tighturl.tmpl .
  This template controls your site design and is *always* used to generate
  output pages to the browser.
   
  The inner template is *always* one of the following sub-templates 
  (or no sub-template):
    tighturl.main.tmpl : HTML shown for your TightURL homepage
    tighturl.save.tmpl : HTML shown when a URL is saved
    tighturl.help.tmpl : HTML shown for Help info (may not exist yet)
    (none)             : No inner template.

  Please note that many screens are generated using only the main site
  (outer) template.  All error screens are generated this way.

  The variables supported by TightURL Templates are:

    $HTML        : In the innermost or only template, replaced by a HTML
                   message from TightURL.  In an outer template, it is
                   replaced by contents of the inner (sub-)template.
                   You should never remove this variable from a template.
    $PARM        : Parameter when 404-Method not used.
    $URL         : Replaced by browser submitted URL.
    $URLLEN      : Replaced by lenghth of the submitted URL.
    $TIGHTURL    : Replaced by TightURL generated by the submission.
    $TIGHTURLLEN : Replaced by length of the generated TightURL.
    $DIFF        : Replaced by difference in length between URLs.
    $INPUT       : Replaced by submitted URL for use when there has
                   been an error detected in the input.
    $SVCNAME     : Replaced by name chosen for your TightURL service.
    $HEADCOLOR   : Replaced by color value chosen for <H1> HTML tags.
    $TABLECOLOR  : Replaced by color value chosen for the table.
    $TAGLINE     : Replaced by "tag line" for your TightURL service.
    $CPASTTEXT   : Replaced by capitalized past tense description of
                   tightened URLs.
    $PASTTEXT    : Same as $CPASTTEXT, but first letter not capitalized.
    $CVERBTEXT   : Replaced by capitalized verb description of your
                   TightURL service.
    $VERBTEXT    : Same as $CVERBTEXT, but first letter not capitalized.
    $COPYRIGHT   : Replaced by generated copyright string created from
                   $copystart config value and current year.
    $URIBLS      : Replaced by HTML showing URIBLs being checked.
    $HOST        : Replaced by hostname of Web site.
    $SELF        : Replaced by the URL path to the TightURL script.
    $TIGHTURLVER : Replaced by the TightURL running version number.

  TightURL Operating Modes
  ------------------------

  TightURL supports several operating modes that control its behavior:

  AntiAbuse: Generally if your web site is connected to the Internet and
  and the TightURL library can make outbound network connections, you should
  run with the antiabuse system turned on.  When the antiabuse system is
  turned off, virtually everything will be accepted into your database that
  can be shortened.

  NetChecks: Generally if your web site is connected to the Internet and
  and the TightURL library can make outbound network connections, you should
  run with the netchecks system turned on.  If your site has no connectivity
  or ability to make outbound network connections, you should turn the
  netchecks off.  When netchecks are off, TightURL will not be able to resolve
  URLs through redirections to their final destination, check for new versions
  of TightURL, or check submitted URLs against URI blacklists.

  GiveShortest: In the event your Squish/TightURL site has aliases, TightURL
  can be instructed to accept the submitted URL so long as any of the site's
  names can be used to produce a shortened URL, and to offer that URL as the
  suggested URL.  For example, if your site is http://example.com/johndoe and
  also can be reached at http://jd.example.com a user may submit a URL to the
  first sitename that cannot be shortened, but could be shortened by using the
  second sitename.  TightURL can be configured to accept the URL and suggest
  the second sitename as the returned shortened URL instead of rejecting it as
  a URL that could not be shortened.

    Database Modes
    --------------
    Efficient: In Efficient mode, TightURL assigns IDs sequentially, skipping
    only over Reserved URLs.  This is the recommended mode for all new sites.
    Once you choose a mode other than "Efficient", you'll never really be able
    to be efficient again, so make sure you know what you're doing.

    Randomizer: In Randomizer mode, TightURL attempts to issue IDs that
    aren't predictable in advance.  This is designed to please those who feel
    there's something wrong with walking through a TightURL database or for
    some reason don't want people to have the ability to try and grab specific
    IDs from the database.
    
    WordNumWord: In WordNumWord mode TightURL does not attempt to assign the
    shortest possible URL, rather it attempts to generate URLs that are easy
    to remember.  TightURL still rejects URLs that it can't shorten. 
    URLs produced by WordNumWord mode look like this:
    http://example.com/happy21day


  Squish Operating Modes
  ----------------------

  Squish supports three distinct "operating modes".  These are known as
  "basic", "mod_rewrite", and "404 Method".  You want to avoid changing your
  operating mode later, as changes to or from basic mode will cause all your
  URLs to change.  Changes between mod_rewrite and the 404 Method do not
  result in changes to your URLs, but your operating mode is something you
  should choose carefully and then stick with.

    Using basic mode
    ----------------

    This operating mode produces URLs that follow this pattern:
    http://example.com/?i=id  or http://example.com/yoursite/?i=id

    No changes to httpd.conf or .htaccess are required for basic mode, but
    this produces slightly longer and more inconvenient to type URLs.  If you
    can use mod_rewrite or the 404 Method, it is highly recommended that you
    do so.


    Using mod_rewrite with Apache
    -----------------------------

    PLEASE NOTE: There was a longstanding bug in Apache mod_rewrite that
    probably makes TightURL or anything like it unable to work except with
    what are still very recent versions of Apache.
    https://issues.apache.org/bugzilla/show_bug.cgi?id=34602

    Users are encouraged to use "404 Mode", and especially in the event
    their Apache version has the bug shown above.
   

    This operating mode produces URLs that follow this pattern:
    http://example.com/id  or http://example.com/yoursite/id

    Squish can be used with mod_rewrite by adding the following lines to
    httpd.conf or if you can't modify httpd.conf, you can use .htaccess :

    <IfModule mod_rewrite.c>  
      RewriteEngine On
      RewriteRule ^view/([a-z0-9-]+)/?$ index.php?v=$1 [NC,L]
      RewriteRule ^([a-z0-9-]+)/?$ index.php?i=$1 [NC,L]
    </IfModule>

    If you change the parameters (form variables) from "i" for the TightURL ID
    to look up, and "v" for the TightURL ID to preview, then you'll need to
    adjust these lines accordingly.

    Be aware that http.conf is read once when the Web server is started or
    reloaded, but .htaccess must be read and parsed for *every request*, so
    you always want to use http.conf over .htaccess whenever possible.
    

    Using "The 404-Method" with Apache
    ----------------------------------

    This operating mode produces URLs that follow this pattern:
    http://example.com/id or http://example.com/yoursite/id

    The "404-Method" refers to instructing your Web server to direct all
    requests that generate a "Not found" error (which is an HTTP error code
    404) to the TightURL script.  By doing this, TightURL will run for URLs in
    your TightURL site that don't exist, such as would be the case for
    http://example.com/tighturl.php/xxyy

    The xxyy is a TightURL ID number, not an actual Web page in your site.  By
    sending non-existent page requests to the TightURL script, you can look up
    those IDs and issue an HTTP Redirect without the need for mod_rewrite.

    To use the 404-Method, set $FOFMethod=1 in tighturl.config.inc.php.

      Using .htaccess
      ---------------

      Then put this in your .htaccess file:
  
        ErrorDocument 404 /index.php

      This change should take effect immediately after saving .htaccess .
      If it doesn't work, make sure you have AllowOverride FileInfo on in the
      directory you're running TightURL from.
  
      Using httpd.conf
      ----------------

      Alternatively to using .htaccess (and for improved performance), put the
      following line in your httpd.conf in the appropriate Directory section
      (and VirtualHost if applicable):
  
        ErrorDocument 404 /index.php

      You will need to reload your Apache configuration for this change to take
      effect.

  See the Apache documentation for more information.
  http://httpd.apache.org/docs/mod/core.html#errordocument
  http://httpd.apache.org/docs/mod/core.html#allowoverride

  Adding more URIBLs
  ------------------
  
  In the event other URIBLs beside SURBL become available, and you wish
  to check those also, edit $uribl and $uriblurl in 
  tighturl.config.inc.php .
  
  To add a new URIBL named uribl.example.com whose Web site is located
  at http://www.example.com 
  
  Change this:
  
      $uribl = array("multi.surbl.org");
      $uriblurl = array("www.surbl.org");

  To this:

      $uribl = array("multi.surbl.org","uribl.example.com");
      $uriblurl = array("www.surbl.org","www.example.com");

  You can add as many URIBLs as you want this way.

  Squeezing Your Base URL Down to the Smallest Possible Size
  ----------------------------------------------------------
  The "base URL" is the fixed portion of your TightURL URLs.  This
  would be everything up to the TightURL ID at the end of the URL.
  The length of the TightURL ID will start out at 1 character and may
  get up to 6 characters after tens of millions of TightURLs have been
  created in your system.  (Most TightURL installations are not 
  expected to get into the tens of thousands, let alone tens of
  millions) Because the ID is at most 6 characters, the most
  important thing you can do to get the shortest URL possible is to
  "squeeze" as many characters out of the base portion of the URL
  as possible.

  The following URL is "unfortunately long", but should still allow
  you to create tens of millions of TightURLs that can be used without
  wrapping in most e-mail programs.  It is 72 characters long:

  http://www.a-really-quite-long-name.com/~example01/tighturl.php?i=abcdef

  This URL is not only unfortunately long, it is unnecessarily long
  as well.  The following optimizations can be attempted:

  1. Drop the "www."
  2. Rename tighturl.php to something shorter.
  3. Rename tighturl.php to index.php and put it in a 1-character subdir.

  If optimizations 1 and 3 are successfully applied, we get a 58
  character URL (14 characters shorter):

  http://a-really-quite-long-name.com/~example01/t/?i=abcdef

  A more optimistic domain name (39 characters):

  http://example.com/~example/t/?i=abcdef

  Ideal scenario with own domain (29 characters):
  
  http://tighturl.com/?i=abcdef

  If you are able to use Mod_Rewrite or the 404-Method as shown
  above, you can also drop the "?i=" portion of the URL, saving
  another 3 characters.

  Mod_Rewrite or 404-Method scenario (26 characters):
 
  http://tighturl.com/abcdef

  This also works with the "unfortunately long" URL, bringing
  it down to 56 characters:

  http://a-really-quite-long-name.com/~example01/t/abcdef

********************************************************************************