##############################################################################
#                       Random Link Generator v2.0                           #
#                       Random Link Selection Script                         #
#                                                                            #
#                         Scripts Archive                                    #
#                    https://worldwidemart.com/scripts/                      #
##############################################################################

DESCRIPTION
-----------
Random Link Generator selects and displays a random link from a predefined
list. It was commonly used for "random site" buttons, webrings, and link
exchange programs in the 1990s web.

FEATURES
--------
* Random link selection from list or file
* Multiple output modes (redirect, HTML, URL, JSON)
* External link file support
* Configurable link attributes
* Description support

REQUIREMENTS
------------
* Unix-based web server with CGI support
* Perl 5.x or higher

PACKAGE CONTENTS
----------------
rand_link.pl    - Main script
links.txt       - Sample links file
README          - This documentation

INSTALLATION
------------
1. Upload rand_link.pl to your cgi-bin directory
2. Set permissions: chmod 755 rand_link.pl
3. Create links.txt or edit links in the script
4. Add to your page

LINK FILE FORMAT
----------------
Each line in links.txt should be:
  URL|Title|Description

Example:
  https://example.com|Example Site|An example website
  https://example.org|Example Org|Another example site

Lines starting with # are treated as comments.

USAGE EXAMPLES
--------------
As a redirect link:
  <a href="/cgi-bin/rand_link.pl">Visit a Random Site</a>

Get HTML link via SSI:
  <!--#include virtual="/cgi-bin/rand_link.pl?mode=html" -->

Get just the URL:
  <!--#include virtual="/cgi-bin/rand_link.pl?mode=url" -->

Get JSON response:
  <script>
    fetch('/cgi-bin/rand_link.pl?mode=json')
      .then(r => r.json())
      .then(data => console.log(data.title));
  </script>

OUTPUT MODES
------------
redirect - HTTP 302 redirect to random link (default)
html     - Returns <a href="...">Title</a> HTML
url      - Returns plain text URL
json     - Returns {"url":"...","title":"...","description":"..."}

CONFIGURATION
-------------
$links_file  - Path to external links file
$output_mode - Default output mode
@links       - Array of links (if not using file)
$link_class  - CSS class for HTML output
$target      - Link target attribute (_blank, etc.)
$show_desc   - Include description in HTML output

COMMON USES (1990s)
-------------------
* Webrings - circular networks of related websites
* Link exchanges - mutual promotion programs
* "I'm Feeling Lucky" style random buttons
* Partner site rotation
* Banner/sponsor rotation

WEBRINGS EXPLAINED
------------------
Webrings were circular networks where sites linked to each other.
A typical webring navigation included:
  [Previous] [Random] [Next] [List All]

Each site would include webring navigation that allowed visitors
to discover related sites in the ring.

MODERN ALTERNATIVES
-------------------
For random links in modern web development:

JavaScript:
  const sites = [
    { url: 'https://example.com', title: 'Example' },
    { url: 'https://example.org', title: 'Another' }
  ];

  function randomSite() {
    const random = sites[Math.floor(Math.random() * sites.length)];
    window.location.href = random.url;
  }

React component:
  const RandomLink = ({ sites }) => {
    const random = sites[Math.floor(Math.random() * sites.length)];
    return <a href={random.url}>{random.title}</a>;
  };

Webring alternatives:
* IndieWeb Webring (https://xn--sr8hvo.ws)
* XXIIVV Webring (https://webring.xxiivv.com)
* Hotline Webring

LICENSE
-------
Artistic License

##############################################################################
