Coranto will work on most Unix (including Linux & BSD) and Windows servers. It does not appear to work properly on MacOS 9 or lower systems (with MacPerl).
Perl 5 or better is required. On Windows, a recent version of ActivePerl is needed.
On Windows NT systems, the administrator may need to change permissions so that coranto.cgi can write to files in its directory. Or, more specifically: change the permissions on the Coranto directory so that IUSR_SERVERNAME has CHANGE access to it and the directory Coranto is running in has execute access in IIS. Contact your administrator if you are having permissions problems.
If your server requires that CGI scripts have a .pl extension, you can simply rename coranto.cgi and viewnews.cgi to coranto.pl and viewnews.pl. No script changes are necessary. DO NOT rename nsettings.cgi or nsbk.cgi, as they are not meant to be run.
Already very experienced with Perl scripts? Then follow these instructions:
Once set up, news will be written to news.txt, which can be included into an HTML page via any method which allows you to include a text file in your web page. Do not use viewnews.cgi unless you have read this readme.
If you have any problems, read the full instructions below.
Setup is a 5-step procedure. The amount of pain it will involve depends largely on the quirks of your web host. On some web servers it will be essential that you obtain some information from your host.
There are some prerequisites to using Coranto:
Note that Coranto will not work with Tripod, a free web host, even though they claim to support CGI.
There is also some information you must obtain from your web host prior to setup:
If all else fails, it's time to see if you can find some help at the Coranto Forum.
The first step is to open coranto.cgi and viewnews.cgi using a text editor (such as Windows Notepad) and change the first line of both files. The first line should be #! followed by the path to Perl 5 on your server.
If you don't know the path to Perl 5 on your server, check your web host's support pages or contact your web host.
For most users, this is all the text file editing that you have to do.
IMPORTANT:Some servers also have Perl 4 installed, an older version, alongside Perl 5. If you have problems, make sure your paths are pointing to Perl 5.001 or higher, as Coranto will not work at all with Perl 4.
Next, you should upload Coranto files to your server.
Where you choose to put the Coranto files on your site depends somewhat on the web server. Many servers will allow you to put Coranto in any directory. Others will require that you use a special directory called cgi-bin.If there's a cgi-bin directory on your web server, you generally can't go wrong in using it. Though most servers no longer require that you use this directory, none will complain if you do. If you're running other CGI scripts, you may also choose to try cgi-bin/coranto to avoid cluttering the cgi-bin directory.
Once you've chosen a directory, FTP all Coranto files except for newsdat.txt to this directory IN ASCII MODE (not binary mode or auto-detect). Your FTP program should have ASCII mode as an option; if not, download WS_FTP LE or SmartFTP, both free. (The download for WS_FTP LE is, as of this writing, somewhat buried on that site. Go to the Download Evaluations page; it is present as one of the product options there.)
IMPORTANT: If there's already a file called .htaccess in the directory you are uploading to, don't overwrite it with the version in the Coranto zip.
The directory that you just uploaded files to is your Program Files directory. There is one other directory that Coranto needs to use, the News Files directory. Whereas the Program Files directory holds the CGI code that runs Coranto, the News Files directory will hold the HTML files that contain your site's news. If your Program Files directory was cgi-bin (or a subdirectory), then you should create a separate directory outside cgi-bin for your News Files directory. A directory called news beneath your main directory is generally a good choice. If your Program Files directory was not cgi-bin, then you can usually use the same directory as both your News Files and Program Files directory, though you can still choose to use an external directory to avoid clutter.
Once you've chosen your News Files directory, upload newsdat.txt to that directory, in ASCII mode.
The next step is to CHMOD the files and directories. CHMOD is the arcane Unix name for telling your server what a file is for and who can access it. You should be able to CHMOD from your FTP client; if not, get a new client such as WS_FTP LE or SmartFTP.
If your server runs the Windows NT/2000 operating system, you can skip this step. (You may need to ask your server administrator to make coranto.cgi and viewnews.cgi executable, and crcfg.dat, nsettings.cgi, nsbk.cgi, and newsdat.txt writable.) If you're not sure of which operating system your server runs, then chances are that it's a form of Unix, in which case you must CHMOD files.
First, CHMOD your News Files directory 777. (On a few servers, this may cause problems; if problems occur, try 755.)
Next you must CHMOD certain Coranto files. newsdat.txt should be in the News Files directory, and all others should be in the Program Files directory.
There are several other files that are part of Coranto but they don't need any specific CHMOD values.
Above, three-digit CHMOD numbers are used. There's another method of setting
CHMODs, used by some FTP clients (like WS_FTP), that involves checking off permission
(Read, Write, and Execute) for three categories of users (Owner, Group, and
Other). If your FTP client does not support CHMOD numbers, use the following
table to translate the numbers:
|
CHMOD Number
|
Owner
|
Group
|
Other
|
|
666
|
Read, Write
|
Read, Write
|
Read, Write
|
|
755
|
Read, Write, Execute
|
Read, Execute
|
Read, Execute
|
|
777
|
Read, Write, Execute
|
Read, Write, Execute
|
Read, Write, Execute
|
Now access coranto.cgi via your web browser. For example, visit the URL http://your.site.com/path/coranto.cgi It should display a login page.
At the login screen:
At this stage Coranto should be fully installed and working. The next step it to make your web pages work with Coranto.
When you Submit News to Coranto it is stored in a database file. Build News takes the news entries from the database and builds them into web-usable files. Coranto can build many different news files in different locations, but by default Coranto builds a file called news.txt in your News Files directory.
news.txt contains HTML but is not a complete web page and should not be viewed directly in a web browser. It is designed to be included into an HTML page (often your site's home page). There are several methods by which you may include a text file inside an HTML page, and any of these should work to include news.txt. Here, we will describe the most common method: Server Side Includes, usually referred to as SSI. When you include an SSI in your web page, you are telling the server to merge together two separate files before showing your page to the person visiting your site.
Including news.txt into your web page via SSI is generally the most difficult and troublesome part of installing Coranto. Look at your web host's documentation to see if they have explanatory material about using SSI on their server; the generic instructions here attempt to accomodate most servers, but they simply won't work for some.
In order to use SSI in a web page, you will usually need to give the page an extension of .shtml rather than .html. If you try to use SSI in a page with a .html extension, 99% of the time you will simply get no result.
What exact SSI code you use to include news.txt depends on where news.txt is located in relation to the HTML file it is being included it. If both files are in the same directory, use:
<!--#include virtual="news.txt" -->
in your HTML file at the point where you'd like your news to appear.
If your HTML file and news.txt are in different directories, use the relative URL from your HTML file to news.txt. For instance, if the locations of the respective files are http://www.yoursite.com/index.html and http://www.yoursite.com/news/news.txt, use:
<!--#include virtual="news/news.txt" -->
Or, if the locations are http://www.yoursite.com/pages/main/main.html and http://www.yoursite.com/coranto/news.txt, use:
<!--#include virtual="/coranto/news.txt" -->
Try using variations on these examples in your web page.
