##############################################################################
# NewsAdmin v1.0 (2000-01-06)                                                #
# Copyright (c) Stefan Pettersson, stefpet@algonet.se                        #
# More information at http://www.stefan-pettersson.nu/scripts/               #
# Disclaimer: No guarantees are made, use this script at your own risk       #
##############################################################################

NewsAdmin is a program which allows you to update a webpage with news through
a web interface. Done with all the different newssites in mind. You're not
limited in any special look, everything may be customized the way you want.
The web interface is password protected so not anyone can post news, even if
they figure out the URL.

This package should include the following files:
    1. readme.txt             - Installation instructions, Copyright,
                                and more (this file)
    2. newsadmin_settings.pl  - Configure the script in this file
    3. newsadmin.pl           - The main CGI/Perl script
    4. newsitem-template.html - Template for news
    5. headline-template.html - Template for headlines
    6. index.html             - Example page which includes the news

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

NewsAdmin is free to use as long as you provide a link back to the NewsAdmin
page and state on your site that it's using NewsAdmin. The following HTML
code is an example that you could use on your site:

<SITE NAME> are using
<a href="http://www.stefan-pettersson.nu/scripts/newsadmin/">NewsAdmin</a>.

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


Requirements
============

To be able to use NewsAdmin you must be able to install and run CGI-scripts
made with Perl on your webserver. You must also be able to use SSI (Server
Side Includes) in your html pages.

If you are unsure of any of this, ask your ISP/webhost (or your local geek
friend) ;-).


Setting up NewsAdmin
====================

The first thing you must make sure, is that the first line in newsadmin.pl
is pointing to Perl on your webserver. By default it is:

    #!/usr/bin/perl

This is usually correct, but if you get a strange error you know that this
might be the problem. Your system administrator knows about this.

Place all files (except readme.txt and index.html) in the cgi-bin directory
on your server (or where CGI-scripts may be executed). If you're transfering
the files via FTP, be sure to use ASCII because otherwise the linefeeds will
be wrong. Set the file permissions of newsadmin.pl:

    chmod 755 newsadmin.pl

You may do this from the system prompt if you've got telnet access to the
server, otherwise you usually can do this thru your FTP-client.

Now to the important part, how to get the news on your webpage. You'll use
SSI to include the news file and the headlines file on the webpage where you
want to display the news. This is done by inserting:

    <!--#include virtual="/www/headlines_incl.html"-->

and

    <!--#include virtual="/www/news_incl.html"-->

The path must be the one you've specified (see below). An example page
called index.html is included. Take a look at it to get a hang of it.


Configuring NewsAdmin
=====================

You must configure NewsAdmin before you can use it. All changes are made in
the file newsadmin_settings.pl. Here are the following variables that you
should change if they doesn't already fit your system.

    @passwords = qw(
        secretpassword
        supersecret
    );
    	This is where you specify which passwords that should be used to
    	allow someone to do a news post. In the above example there are
    	two passwords, "secretpassword" and "supersecret". You may add or
    	delete as many passwords as you wish.

    $number_of_news = 20;
        Number of news that should be displayed at the same time. When
        the news count exceeds this value, the last one will be dropped
        when new news are inserted.

    $number_of_headlines = 8;
        Like the one above except that this is for headlines.

	$dateformat = '[monthname] [day] [year], [hour0]:[min0] [ampm]';
		You may change the look of the date and time when it's displayed
		in a news posting. You do this by using some special tags that
		will be replaced with a value. The following tags are available:
		
		[sec]            = seconds
		[sec0]           = seconds padded with a 0
		
		[min]            = minutes
		[min0]           = minutes padded with a 0
		
		[hour]           = hours (12h)
		[hour0]          = hours (22h) padded with a 0
	
		[hour24]         = hours (24h)
		[hour240]        = hours (24h) padded with a 0
	
		[ampm]           = display am or pm
		
		[day]            = day in month
		[day0]           = day in month padded with a 0
		
		[dayname]        = name of weekday
		[daynameshort]   = name of weekday short 
		
		[month]          = month
		[month0]         = month padded with a 0
		[monthname]      = name of month
		[monthnameshort] = name of month short
		
		[year]           = year (4 digits)
		[shortyear]      = year (2 digits)

        Examples:		
			Format: '[monthname] [day] [year], [hour0]:[min0] [ampm]'
			Result: January 6 2000, 01:01 pm
			
			Format: 'Posted [hour240]:[min0]:[sec0] [year]-[month0]-[day0]'
			Result: Posted 13:17:28 2000-01-06
			
    @daynames = qw(Sunday Monday Tuesday Wednesday Thursday Friday
                   Saturday);
		The names that will be used for each weekday is specified here
		with a space between each name. You might want to exchange these
		with the names in your language for example.
    
    @monthnames = qw(January February March April May June July August
                     September October November December);
		The names that will be used for each month is specified here with
		a space between each name.

    $news_file = '/www/news_incl.html';
        This is the path (not URL) to the file where the actual news are
        written. The specified file is the one you'll include in the html
        document where you want the news to be displayed.

        This file and the one for headlines does not need to be created.
        The script will create the automatically if they don't exist.

    $headlines_file = '/www/headlines_incl.html';
        Like above except that this on is for the headlines.

    $newsitem_template = 'newsitem-template.html';
        Template which describes how an inserted news item will look like.
        See below under customization for more information.

    $headline_template = 'headline-template.html';
        Template file for headlines.


Customization
=============

The look of the headlines and news which are inserted may be customized by
you. This is done by changing the template files. You simply use standard
HTML but include some special tags that will be replaced by author name,
date, headline, etc. See the examples which is originally distributed with
NewsAdmin.

Headline template:
    The headline template is used when writing to the headlines file which
    is simply a link to the actual news item.

    Example:
        <b><a href="#[%NA-ID]">[%NA-HEADLINE]</a></b><br>

News template:
	This is the actual news, it works exactly the same way as the
	headline template.

Here are the special tags which is used in the templates:
    [%NA-ID]         - Will be replaced by a unique id which is used to
                       link to the newsitem on the page. Used in headline.
    [%NA-HEADLINE]   - Headline
    [%NA-TIMESTAMP]  - Date
    [%NA-TEXT]       - The text itself
    [%NA-EMAIL]      - Email
    [%NA-AUTHOR]     - Author name

It's recommended that you first use the default templates, and then modify
them as you like.


How To Use NewsAdmin
====================

If you've succesfully installed NewsAdmin, you may simply enter it's url in
your browser to get going. If you've installed in cgi-bin on your site
you'll call it with:
    http://www.yourdomain.com/cgi-bin/newsadmin.pl

Options:
	Currently there is only one option in NewsAdmin.

	Convert double linefeeds into HTML
		This option will convert double linefeeds (ie you press RETURN two
		times in a row) into a <P> tag. The result is that the double
		linefeed actually is displayed on the HTML page.


What To Do If You Can't Get It To Work
======================================

Unfortunately I'm not able to support you in any way. Simply read these
instructions again and check the NewsAdmin webpage for Frequently Asked
Questions which might help you. If you're stuck, try getting some help
from your web-provider or any helpful tech savvy person you know.

The reason why I can't help you is that I would probably get swamped by
mails and unfortunately I haven't got the time to answer them all. So
please DON'T mail me asking for help. Thanks.

NewsAdmin homepage:

    http://www.stefan-pettersson.nu/scripts/newsadmin/


Version History
===============
v1.0  - 2000-01-06
    - Considered good enough to leave beta stage
    - Added customizable dateformat
    - Fixed a litte tiny bug
    
v0.4  - 1999-12-29
    - Added multiple passwords feature
    - Added linefeed to HTML conversion
    - Remade template parsing a little bit

v0.3  - 1999-12-09
    - First public beta
