Tutorial/Readme File
THANK YOU FOR DOWNLOADING PerlBlog v.1.07 beta
Distributed freely under the GNU General Public Licence version 2. The attached licence and acknowledgements must be maintained with all alterations.
This unique script allows you to post, edit and customize your weblog more than any online blog,
because it's coded in Perl. It's advantages include a highly customisable interface that
lets you take command of your blog without the nitty-gritty coding, it's integrated commenting
and archiving system, and it's easy creation of new pages that follow your blog template
seamlessly. Editing your blog's template will become a hobby rather than a chore. Please
refer to EDITING YOUR WEBLOG for details on making the blog suit your taste.
This latest version works out of the box. Just secure, upload, CHMOD, and write!
It's not complicated.. this tutorial mostly covers how to customize your weblog. To make it
easier to understand, all the areas that are taken from the scripts themselves are shown in red
This tutorial covers:
BEFORE YOU INSTALL
CUSTOMIZING YOUR WEBLOG BEFORE UPLOADING
UPLOADING YOUR WEBLOG
USING YOUR WEBLOG
EDITING YOUR WEBLOG
ADDING MORE PAGES
USING WEBLOG-CONFIG.CGI
USING WEBLOG-ADMIN.CGI
ABOUT ACCESS.CGI
TROUBLESHOOTING
DOWNLOAD FILES
CONTACT
KNOWN BUGS
=================================================================================================
BEFORE YOU INSTALL:(top)
If you want to customize your weblog offline, then it is highly recommended that
you have the latest Apache HTTP server installed on your computer, along with ActivePerl.
You may download them here:
ActivePerl- http://www.activestate.com/Products/ActivePerl
Apache HTTP- http://httpd.apache.org/download.cgi
Refer to this tutorial for details http://www.4webhelp.net/tutorials/cgi/local.php
=================================================================================================
CUSTOMIZING YOUR WEBLOG BEFORE UPLOADING:(top)
Before you actually put your weblog online, you need to change the password to be able to
post an entry in your blog. (and to ensure that no one else can do that too). No one will
be able to see the password/username online.
To do so, open weblog-config.cgi using NOTEPAD, and scroll down to where you see
"EASY CUSTOMIZE". Change the part within the quotation marks to a username/password you'd
like, and save it.
$username = "truediarist"; # Weblog username
$password = "tryme1234"; # Weblog password
$adminusername = "truediarist"; # Weblog-admin.cgi username
$adminpassword = "tryme1234"; # Weblog-admin.cgi password
Also you CAN (but you do not need to) to change $code = "write";. Change it to
something harder to remember
like $code = "asghgal34454ijdfsdfs";
HENCE the page where you'll write your journal could be
http://www.mysite.com/directory/to/my/weblog.cgi?asghgal34454ijdfsdfs
=================================================================================================
UPLOADING YOUR WEBLOG ONLINE:(top)
1) Make sure your server supports Perl/CGI. A good site is http://free.prohosting.com
2) Make a directory where all your blog files will be located, usually under cgi-bin
3) Upload ALL files AS THEY ARE, using FTP or anything you choose.
-weblog.cgi (weblog script)
-weblog-config.cgi (weblog configuration script)
-weblog-admin.cgi (edit/delete your entries)
-access.cgi (password access script)
-forumdata (directory)
|
-header.txt (header file)
-footer.txt (footer file)
-months.txt (list of months)
-num.txt (last thread/reply)
-sidebar.txt (sidebar column text)
-200505.txt (sample month)
-about.txt (about page text)
-clear.js (quicktags javascript)
-quicktags.js (quicktags javascript)
-messages (directory)
|
-2.txt (welcome entry)
4) CHMOD the directory using FTP to 755
5) Test! Go to http://www.myhost.com/directory/to/your/blog/weblog.cgi
5) If it doesn't work, refer to TROUBLESHOOTING below
=================================================================================================
USING YOUR WEBLOG:(top)
To begin writing in your weblog, go to
http://www.myhosting.com/directory/to/my/weblog.cgi?write (or whatever you changed it to)
Username Type the username you put in weblog-config.cgi
Password Type the password you put in weblog-config.cgi
Date Add the date or any header topic
Entry Write your weblog journal entry here.
You can add every sort of imaginable HTML attribute to your blog entry.
People can also reply to your journals by clicking on the "X comments" link right beneath
every entry you write.
=================================================================================================
EDITING: (BEGINNER)(top)
Editing your script should be done in Notepad. Many of the colors and fonts you can edit
using weblog-config.cgi Open weblog-config.cgi using Notepad, scroll down,
and edit the areas described.
Your weblog is coded in PERL, which means there are places where plain HTML doesn't work.
Any place between
print <<"EOF"; and EOF
can be edited using HTML. It is highly suggested that you make backups of every file you
edit, in case anything goes wrong. If you are a beginner, I suggest you use
weblog-config.cgi and editing the parts you can see are commented and provided.
eg: You probably don't want "Welcome to my blog" as your title, so open weblog-config.cgi
with Notepad and scroll to the part
$blogtitle = "Welcome to my blog"; # Weblog Title
and change "Welcome to my blog" to something original!
Check the PerlBlog website for a complete guide on how to customize PerlBlog.
=================================================================================================
EDITING YOUR WEBLOG: (ADVANCED)(top)
Assuming you know about Perl:
The way the weblog works is such:
Every page is defined by a ? so that the journal entry page is ?write and the
archives page is ?archives. This is the same as going to
http://www.myhosting.com/directory/to/my/weblog.cgi?archives
etc.
Your links are:
http://www.myhosting.com/directory/to/my/weblog.cgi?archives- Archives
http://www.myhosting.com/directory/to/my/weblog.cgi?the-page-you-put-in-weblog-config
- Page where you can write your journal
http://www.myhosting.com/directory/to/my/weblog.cgi?about- Your "about" page
Words that have the $ sign are those that are either saved in the messages file
or defined elsewhere in the script.
When you write an entry in the journal, you need to type in the password and username that
you chose when you edited weblog-config.cgi. The script then saves that journal entry as a
number and a message. Hence you get two files that contain your entry. These are
saved under the messages directory, and the 200402 file (or any month that
you wrote the blog... December 2005 would be 200512)
Whenever a reply is posted on a comment, the reply message is saved under the journal entry
in the appropriate entry number under messages.
This you can edit using weblog-admin.cgi.
=================================================================================================
ADDING MORE PAGES(top)
There are two methods to do so:
1) ADD NEW HTML PAGE- This is easy: add a new link at the header script. Scroll down in weblog.cgi
You'll find a set of code like this:
<!-- LINKS TO YOUR PAGES --!>
[ <a href="weblog.cgi">$subtitle</a> |
<a href="?archives">archives</a> |
<a href="?about">about</a> ]
Just add for every page
| <a href="http://link.to/my/new/page.html">title of my new page</a>
and be sure to add the "]" to close the link area
2) ADD A NEW PERL PAGE- This is quite simple but needs several procedures. Its helpful when
you don't want to make an entirely new page, because your headers and sidebars are already
determined.
COPY AND PASTE
First, open weblog.cgi in Notepad and scroll to where you see ####### MY ABOUT PAGE#####.
Copy everything from that ### area to the next one, which is ##### THE ARCHIVES #####.
Then paste it right after the last script in the ABOUT PAGE section.
eg: the script ends like this
EOF
&printFooter;
}
(PASTE HERE)
EDIT PAGE ATTRIBUTES
Now go to the top of what you just copy and pasted: you'll see just below the MY ABOUT
PAGE header the following:
sub displayAbout
change it to sub displayYourpage (like if its a music page, sub displayMusic)
EDIT PAGE DIRECTION
Now scroll all the way to the near top of the whole script and you'll see a header called
###### QUERIES FOR SUB-ROUTINE #####
Add the follwing line in between the other similar queries
elsif ($command eq "Yourpage") {&displayYourpage ($value);}
like elsif ($command eq "Music") {&displayMusic ($value);}
squeeze it between "month" and "about" to make sure it works. So now you have
if ($command eq "archives") {&displayArchives;}
elsif ($command eq "month") {&displayMonth ($value);}
elsif ($command eq "music") {&displayMusic ($value);}
elsif ($command eq "about") {&displayAbout ($value);}
FINISHED
Your new page is now at http://www.myhosting.com/directory/to/my/weblog.cgi?Yourpage
or as the example: http://www.myhosting.com/directory/to/my/weblog.cgi?music
The address location is case sensitive.
=================================================================================================
USING WEBLOG-CONFIG.CGI:(top)
Weblog-config.pl is a script that helps you change the colors on your blog swiftly and
effortlessly. Just type the colors and fonts you'd like in weblog-config.cgi
with Notepad, save it, and upload it.
Note: without weblog-config.cgi in the same directory as weblog.cgi and
weblog-admin.cgi, the weblog will NOT work.
================================================================================================
USING WEBLOG-ADMIN.CGI:(top)
Weblog-admin.cgi can be used to delete or modify your journal entries as well as the replies
that your visitors make.
Go to http://www.myhosting.com/directory/to/my/weblog-admin.cgi
and login with the username and password that your put when you edited weblog-admin.cgi
There is a problem when you have only a single entry, and even if you try to edit it you will
come up with an error
"Error: no thread to edit is selected"
This problem dissolves once you have more entries.
You can also edit weblog-admin.cgi with HTML and Perl.
=================================================================================================
ABOUT ACCESS.CGI:(top)
You will not be able to view access.cgi online, nor will anyone be able to do so.
It is only there to serve the purpose of ensuring that no one except anyone who knows
the password will be able to post an entry in the blog.
You will not need to edit access.cgi.
=================================================================================================
TROUBLESHOOTING:(top)
What to do when your weblog.cgi does not work or comes up with a 500 Internal Server Error:
1) Make sure that your server allows CGI scripting.
2) Verify that you've CHMODed your directory to 755.
3) Verify that you have all the files uploaded AS they are, with the proper
directories in place.
If you have just uploaded your weblog and it doesn't work, then the problems are either
of the above. However if you have edited material in your .pl files, check to make sure:
1) You haven't added HTML scripts in the wrong places.
2) That if you have added HTML scripts, that every quotation mark " is preceded by \
eg: <a href=\"http://www.mysite.com\">
(only anywhere else than between print <<"EOF"; and EOF)
What to do when you've altered your scripts to a point of no return:
Download the files at http://www.chronicled.org/perlblog
What to do when your weblog.cgi comes up half blank
You may have inadvertently deleted a footer or a header file. These are neccessary
so that the script can execute the general settings, etc. Add a blank header.txt and
a footer.txt to resolve the problem.
=================================================================================================
CONTACT:(top)
Contact the author of the revised script by emailing dev@chronicled.org
Any feedback or comment is heartily appreciated, as well as any updates/bugs you may find.
You can also see the script in real time at the PerlBlog homepage
Last updated 4:52 PM 5/13/05
=================================================================================================
KNOWN BUGS/NEED TO BE FIXED THINGS:(top)
The only glitch noticeable now is with weblog-admin.cgi.
When one deletes every entry except the first, one ends up with all the
headerfile (i.e. 200305.txt) emptied, but the "file" itself (2.txt under messages)
remaining intact.
The other (already known) bug is that when you have only a single entry, even if
you try to edit it you will come up with an error "Error: no thread to edit is
selected", which dissapears once you have more entries.