#######################################################################
#							              # 
#                     News Publisher Readme	                      #
#		   	  Version 1.06                                #
# 	                                                              #
#                    Created by Grant Williams                        # 
#					                              #
# Created on:  1/23/98          Last Modified on:  8/18/99            #
# I can be reached at:          gcw07@ionet.net                       #
# Scripts Found at:             http://www.roosh.com/news_publisher/  #
#######################################################################
# Please use the forum at the site for support questions and not      #
# email them. The forum is checked often. Emailed problems will not   #
# be answered unless I specified to email me. Thanks.                 #
#######################################################################
# COPYRIGHT NOTICE:						      #
# 								      #
# Copyright 1999 Grant Williams    All Rights Reserved.               #
#								      #
# This program may be used and modified free of charge by anyone, as  #
# long as this copyright notice and the header above remain intact.   #  
# By using this program you agree to indemnify Grant Williams from    #
# any liability that might arise from it's use.                       #
#								      #
# Selling the code for this program without prior written consent is  #
# expressly forbidden. Obtain permission before redistributing this   #
# software over the Internet or in any other medium.  In all cases    #
# copyright and header must remain intact.                            #
#                                                                     #
#######################################################################
# News Publisher Version History

  # v1.06 #
	- added 'all' category support for all add-ons
	- added byline feature
	- added 'no date' feature to news
	- added flock on/off ability [Thanks to Christian Land]
	- added delete comments feature
	- fixed the category limit bug

  # v1.05b #
	- fixed another category bug

  # v1.05a #
	- fixed category bug

  # v1.05 #
	- fixed y2k problem
	- fixed edit story error
	- added menu defaulting [Thanks to Gunslinger(GDI)]
	- added categories
	- added option to create a new window on autolinks and source links

  # v1.04a #
	- released the comment system script

  # v1.04 #
	- released the automated archiving script
	- centralized the configuration of all scripts
	- added source fields
	- fixed time offset
	- added a new date format
	- preview stories before posting
	- news now able to show a set number or a set number of days
	- added headlines to the single news story viewer

  # v1.03 #
	- added previous/next buttons to 'view all stories' section
	- added weekly or monthly news archives
	- added time adjustment
	- headlines able to show a set number or a set number of days

  # v1.02 #
	- added menu to top
	- added ability to stay logged in
	- added 3 different levels of access
	- added a more organized configuration screen
	- added more options to the headlines
	- made some variables optional in the configuration
	- optimized the code more
	- released single news story viewer script

  # v1.01 #
	- minor bug fixes
	- authors can view autolinks
	- released search engine script
	- optimized the code

  # v1.00 #
	- uses SSI to display news 
	- password protected 
	- unlimited authors 
	- individual author passwords 
	- authors only have access to stories they created 
	- edit author's information 
	- delete authors 
	- add news stories 
	- edit any news stories 
	- delete any news stories 
	- add autolinks 
	- delete autolinks 
	- edit autolinks 
	- admin has access to all stories 
	- news headlines 
	- customize HTML output 
	- configure via a web-based form 
	- configure the number of news to show 
	- automatic archiving of news 
	- monthly news archives
	- released
		
#########################################################################

The 'News Publisher' is version 1.05 of my news updater. This program
was made to help webmasters update their current news on their pages 
easier than changing their HTML page and then uploading it. This idea of 
creating this script was first thought up by Julian Figueroa. So I would 
like to thank him for giving me the idea of writing this script. He also
came up with the idea of autolinks, and again I would like to thank him for
that.

The 'News Publisher' should have come with the following files. 

         FILE	      -      DESCRIPTION
-------------------------------------------------------------------------
     1. readme.txt    - the installation instructions for news publisher

     2. news.cgi      - the perl CGI that runs it all
     3. config.cgi    - a perl CGI that you edit to configure the scripts
     4. np-lib.cgi    - a perl CGI that contains general subroutines

     5. upgrade.txt   - a text file that tells how to upgrade
     6. upgrade.cgi   - a perl CGI that will upgrade your database

     7. search.cgi    - a perl CGI that lets you search archived news
     8. viewnews.cgi  - a perl CGI that lets you view only 1 story at a time
     9. comments.cgi  - a perl CGI that lets visitors comment on stories
    10. archives.cgi  - a perl CGI that makes archiving easier

    11. single news   - the readme file for installation of the viewnews.cgi
             readme
    12. search readme - the readme file for installation of the search.cgi
    13. archives      - the readme file for installation of the archives.cgi
          readme
    14. comments      - the readme file for installation of the comments.cgi
          readme
-------------------------------------------------------------------------

You will need to edit the news.cgi file to install to the script.
Below is a description of how to modify the necessary file:

_________________________________________________________________________

                       CONFIG.CGI NEWS CONFIGURATION
		      ===============================

The configuration of the script has change a little in version 1.04a from 
previous versions. You now configure everything in the config.cgi script.
This file must be placed in your server's cgi-bin. This file must be chmoded 755.
Ask your system administrator for more information on either the cgi-bin or the
chmod command.

This file will be the most difficult to modify. Below is a summary of how to
configure all of the variables and what the options do:

###########################################################################
# Define Variables


$datadir = "/path/to/datadirectory";
	This variable should contain the absolute system path to your
	news data directory. So if you keep all your files in 
	/home/username/public_html and you make a directory under 
	there called 'newsdata', then $datadir would be set to:
	/home/username/public_html/newsdata. The 'newsdata' directory
	should be chmoded 777.

$archivedir = "$datadir/archives";
	This is the name of your news archive directory which will be 
	inside the $datadir.  All of the monthly news archives will be 
	created and held in this directory. This directory should be 
	chmoded 777. If you want to have it else where, remove the
	$datadir variable from it and type in the absolute system path
	to the directory you want it placed in. It must be chmoded 777.

$NewsScriptUrl = "http://your.host.xxx/cgi-bin/news.cgi";
	This is the URL that points to news.cgi. This will be used often
	in the news.cgi file, so this must be correct. If you renamed news.cgi
	to news.pl, be sure to change the $scripturl to reflect this change.

$admin_passwd = "password";
	This is a password that you will use to run most of the functions.
	Individual authors will receive their own password, so don't tell 
	many people what this is.

$new_window = 1;
	If this is set to 2 a new window will be created when clicking on an
	autolink or a source link. (1 = NO; 2 = YES;)

$site_identification = "";
	This is an optional variable. Leave it as is if you wish to not use it.
	If you want to give it a name, you may. Such as ": Roosh Net News".
	It will show up next to the title "News Publisher" on the top of every
	page in the script.

$cgi_use_flock = 1;
	If this is set to 1, it will use file locking. If you are running a Windows
	server, then you should set this to 0, to disable file locking.

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

$newshtmlpage = "http://your.host.xxx/index.html";
	NOTE: this variable is no longer in the script. You now will set up
	the html page that you want the script to point to for headlines in
	the configuration screen.

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

The config.cgi is now ready to upload. So upload it and chmod it 755.

Now onto the second part of configuration. Upload the np-lib.cgi script to
the same directory that the config.cgi is located in. There is nothing to edit
in this script. You just need to upload it and chmod it 755. Now the last part of
the installation is you need to configure the news.cgi script, but it is very easy.

First make sure the perl location at the top is correct. Then scroll down to
these lines:

require "config.cgi";
require "np-lib.cgi";

If you did not rename config.cgi or np-lib.cgi to anything else you do not have to 
change anything. If you did rename either one or both of these files change the names
so that they point to the config.cgi file. The news.cgi file must be placed in your 
server's cgi-bin and/or in the same directory as the config.cgi and np-lib.cgi. This file 
must be chmoded 755. Ask your  system administrator for more information on either 
the cgi-bin or chmod command.

Now once you upload the news.cgi you must configure it.

____________________________________________________________________________

                       OPTIONS & CONFIGURATION
		      =========================

The script should now be working correctly. Go to the script's address and
you will have a login screen. Login in with the following:

	Name    :   admin
	Password:   the password you entered in the $admin_passwd variable.

The first time you do this, you will be taken to a screen with configuration
options. Below are detail explainations of each option:

                        --- GENERAL OPTIONS ---

  - Do you want to enable the option allowing authors to edit their 
    informtion? Authors will only be able to edit their email address and 
    password.
	This will either give the individual authors the ability to edit 
	their email address and password or not allow them to edit anything.

  - Do you want to use encryption with the authors passwords?
    ( You should only use unencrypted passwords if your server does NOT 
    allow encryption. )
	Self explanitory. 

  - How many old messages do you want to be shown in the admin section?
    NOTE: Once in the admin section, the news admin and the authors may 
    look at all old messages. This is the amount that will be shown in when 
    you first enter the admin section.
	This should not be placed too high. As you can view all stories
	once you are in the admin section.

  - What do you want the time offset to be?
    NOTE: You should leave this at 0 until you find out the time offset. 
    Look in the readme for more info on this subject.
	This is used if you are wanting the posted time to be different from
	that of the server the script resides on. To find out if you need to
	change this variable, you need to post a news story and look at its
	time compared to your time. Change accordingly. So, if your time is
	an hour greater than the time the stories are posting you have this
	variable as 1. Or if it was one hour less than the time the stories 
	are posting you have this variable as -1.

  - How do you want the news to be archived?
    NOTE: 'Weekly' is just every seven days worth of news are put into a 
    file.
	This will either make the news be archived in a monthly archive files
	or a weekly archive files. The weekly is every seven days worth of
	news is placed into an archive file.

  - Do you want to use the comment system?
    NOTE: Look in the readme file for more info on the comment system.
	This is the optional comments. If you wish to use them set this field
	to yes and add the variable <<comments>> to the news look. Also, you
	must install the comments.cgi script for this to work properly.

  - What text do you want before the source link?
	If you enable the source in a news story, it will add this text or
	html before the link at the end of the news story.

  - Do you want to use bylines?
    NOTE: Look in the readme file for more info on bylines.
	This will allow you to add a short sentence to lead into the story.

  - Do you want to use categories?
    NOTE: Look in the readme file for more info on categories.
	This will allow you to create multiple news section without installing mutliple
	copies of the news script. Each category is configurable, and you can restrict
	author's access to categories. If you set categories to yes, you now configure
	the look of each category in the category options section.

  - Do you want to use the "special" all category?
    NOTE: Look in the readme file for more info about the "special" all category. Once 
    this is set to 'Yes' you configure the category in the categories section.
	This will only be visible if the use categories option is set to yes. This category
	is a special category that will contain the contents of all the other categories. So,
	if you wish to have one page that has the contents of all categories, you use this
	option. The other categories still are there, and can still be called seperately.
	If you set this to yes

                        --- HEADLINE OPTIONS ---

  - What HTML do you want before the date in the headlines?
	This can have any HTML in it. This will be what goes before the
	headline date which is two options down. If you put 
	"<font face='arial' size='2'>" in this field then
	it would have it directly before the date like this:
	"<font face='arial' size='2'>January 1, 1998".

  - What HTML do you want after the date in the headlines?
	This is the HTML that goes directly after the headline date. So if 
	you had "</font><P>" in this field, with the above example it would 
	show up like this:
      	"<font face='arial' size='2'>January 1, 1998</font><P>".

  - What do you want the headline date to look like?
	This field should be pretty straight forward. Just look at the
	options.

  - How many headlines do you want to be shown?
	This is the amount of days of headlines you want for the news page.
	You can either choose from the shown number of days or the shown
	number of news stories. This is used if you want to have links to 
	your news stories on your index.html page to you news page. This 
	will always be created, but you don't have to use the SSI call to 
	call the text file that holds it.

  - How do you want the headlines of the stories to look?
    NOTE: Look in the readme file for specifics on how to edit this field. 
    This field will change the look of all headlines of the news stories 
    when they are shown on the web. 
	You can change any of the HTML in this field. You CAN have the
	following text somewhere inside this field, all are optional:


	<<id>> - this is the ID for the link to the news HTML page. These 
		 should be used like this: 
			http://www.something.com/index.shtml#<<id>> 
		 So the link will be correct for the news stories.
	
	<<subject>> - the news stories subject

	<<email>>   - this is the email address for the author that wrote
		      the story.

	<<author>>  - this is the others name. These should be used in a
		      <a href="mailto:>.
 
	<<time>> - This is the time that the story was originally
		       created.

	<<date>> - This is the date that the story was originally
		       created. The format is 1/01/99.

	<<comments>> - This is used if you want the comments to be displayed.
		       You must also select to use comments in the configuration.

	<<category>> - If the category option is enabled, it will display 
	               the category name.

	<<byline>> - If the byline option is enabled, it will display 
	               the byline.

                        --- NEWS STORY OPTIONS ---


  - What HTML do you want before the date in the news story?
	This can have any HTML in it. This will be what goes before the
	news story date which is two options down. If you put 
	"<font face='arial' size='2'>" in this field then
	it would have it directly before the date like this:
	"<font face='arial' size='2'>January 1, 1998".

  - What HTML do you want after the date in the news story?
	This is the HTML that goes directly after the news story date. So if 
	you had "</font><P>" in this field, with the above example it would 
	show up like this:
      	"<font face='arial' size='2'>January 1, 1998</font><P>".

  - What do you want the news story date to look like?
	This field should be pretty straight forward. Just look at the
	options.

  - How many days of news do you want to be shown on the main news page?
	This is the amount of days of news stories you want on the main
	page. Or the number of news stories you want shown on the main page.

  - How do you want the time to look?
	Again, this field should be straight forward. Look at the options.

  - How do you want the news stories to look?
    NOTE: Look in the readme file for specifics on how to edit this field. 
    This field will change the look of all news stories when they are shown 
    on the web. 
	You can change any of the HTML in this field. You CAN have the
	following text somewhere inside this field, some are required:

	<<id>>   -  this is so the headlines know which story to goto. Use
		    it in an <A NAME="<<id>>">.

	<<subject>>  -  this is the stories subject

	<<story>> - this is the story.

	<<time>> - This is the time that the story was originally
		       created.

	<<email>>   - this is the email address for the author that wrote
		      the story.

	<<author>>  - this is the authors name. These should be used in a
		      <a href="mailto:>.

	<<date>> - This is the date that the story was originally
		       created. The format is 1/01/99.

	<<comments>> - This is used if you want the comments to be displayed.
		       You must also select to use comments in the configuration.

	<<category>> - If the category option is enabled, it will display 
	               the category name.

	<<byline>> - If the byline option is enabled, it will display 
	               the byline.

Click 'Set Configurartion' and it will save the information. Now you can go 
and log back in and it will take you to a different screen. If you wish to 
change the configuration, select "Configuration" from the menu and it will 
take you back to the configuration screen. Your configuration will
take effect the next time you add, edit, delete news, or if you select the
"Update news File" from the menu. Now, on to the other options.

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

                              Author Options
			     ================

When you go into this options you have the ability to do three things. You
may Edit authors information. You can edit their name, email, level setting,
and password. Also you may Delete authors. The author will be deleted, but 
their stories will stay intact. And the final option is the ability to Add 
authors. You just type in their name, email, and what they want as a password
and there user level setting and click the add author button. Then authors 
may log in with their name and password. They will be able to add news 
stories, edit their stories, and delete their stories, once they log in. If
they have a higher setting then they can do more than a normal user. They can
edit/delete all news stories and add/edit authors. 

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

                            Autolink Options
			   ==================

Under here, you may edit, delete, and add autolinks. An autolink is an option
that authors can enable when creating a news story. If you had an autolink
named "News Publisher", then enabled autolinks. Whenever you typed in the 
words "News Publisher" in the story, the script will change those words into 
a link like this:

     <a href="http://www.roosh.com/news_publisher/">News Publisher</a>

This makes it easy for links that you use often. So you don't have to keep
typing in the link over and over again.

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

                              Category Options
			     ==================

Here you may create/edit/delete categories. A category is a way for a user to
have multiple news sections using the same script. Most of it is self explanitory.

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

			    View All Stories
			   ==================

This options is pretty much self explanitory.

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

			    Update News File
			   ==================

This is used to update the HTML output that shows up on your web page. This
should only be used if you hand edit your database (which you should have no
reason to do), or if you changed the configuration and want to update the 
look before the next story is posted, edited, or deleted.

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

			        Log Out
			   ==================

This option is pretty much self explanitory.
____________________________________________________________________________

			  Final Installation Notes
			 ==========================

The last thing you need to know is how to make the news show up on your web
page. You have to use SSI calls to make it show up. Ask your server admin for
specifics on SSI and if you have to change .html to .shtml. Here are the SSI 
calls:

<!--#include virtual="data/1.viewh"-->
	This must point to this file for the headlines to show up. The file
	name doesn't need to be changed, but the location to it does. Change
	the "data/" to the correct location which holds your files. This should
	be the relative path to it and not the full system path to the file. If you
	are using multiple categories, then each category will have their own display
	file associated with the category's number. (eg. category 1, 1.viewh; category 2,
	2.viewh; etc.) Look in the category's option section to find the category's number.
	If you are using the special category, it will be all.viewh.

<!--#include virtual="data/1.viewn"-->
	This must point to this file for the news to show up. The file
	name doesn't need to be changed, but the location to it does. Change
	the "data/" to the correct location which holds your files. This should
	be the relative path to it and not the full system path to the file. If you
	are using multiple categories, then each category will have their own display
	file associated with the category's number. (eg. category 1, 1.viewn; category 2,
	2.viewn; etc.) Look in the category's option section to find the category's number.
	If you are using the special category, it will be all.viewn.

For archived news to show up you must use the following call:

Monthly Archived News Files

<!--#include virtual="data/archives/(1)1-99.archive" -->
	This would be the archive for January 1999. Again this must point
	to the correct location that holds the archives. The archives are
	held in the directory you specified in this variable $archivedir.
	The archive directory will be inside the directory that holds all
	your other files. There will be an archive for each month you have
	written news in. So for February 99, the archive name would be:
	(1)2-99.archive, and so forth. If you are using multiple categories, 
	then each category will have their own display files associated with 
	the category's number. (eg. category 1, (1)1-99; category 2, (2)1-99; etc.) 
	Look in the category's option section to find the category's number.

Weekly Archived News Files

<!--#include virtual="data/archives/(1)1.1.99-1.7.99.archive" -->
	This would be the archive for the news that was posted from January 
	1, 1999 to January 7, 1999. Again this must point to the correct 
	location that holds the archives. The archives are held in the 
	directory you specified in this variable $archivedir. The archive 
	directory will be inside the directory that holds all your other 
	files. There will be an archive for each seven days worth of news 
	you have written. So for January 8, 1999 through January 15, 1999, 
	the archive name would be: (1)1.8.99-1.15.99.archive, and so forth.
	Look inside the archive directory to see what the filenames are. If 
	you are using multiple categories, then each category will have their 
	own display files associated with the category's number. (eg. category 1, 
	(1)1.1.99-1.7.99.archive; category 2, (2)1.1.99-1.7.99.archive; etc.) 
	Look in the category's option section to find the category's number.

____________________________________________________________________________

If you wish to add any add-on script, please look at that add-ons readme file
for help.

_________________________________________________________________________

That is it. Everything should be working correctly, and you should know how
to do everything that you need to know. The rest is self explanitory. If I 
missed anything please let me know. I tried to make it as good as possible,
but may have missed some topics. Have fun.