==== NAME ==== Posy - a website generator inspired by blosxom ==== VERSION ==== This describes version ``0.98'' of Posy. ==== DESCRIPTION ==== This is a simple website content management system inspired by the design of blosxom. The filesystem is the database, there are flavour templates, and plugins. However, this system doesn't require one to write one's entry files in a particular format; one can choose from pure HTML, plain text, or blosxom format. And other formats can be dealt with if one writes a plugin to deal with them. This distribution includes a CGI script (posy.cgi) and one command-line script (posy_static) which use the Posy engine to process input data files into web-page output. == Terms == A few terms: data_dir, data directory The directory where the input data files are kept. This need not be the same directory as the posy.cgi script or any other script. This is set up with sub-directories in a hierarchical fashion and chiefly contains the files holding the web content you wish to display. state_dir, state directory The directory where "state" files are written. Thus this needs to be a directory writable by the script, which may need special care when using Posy with a CGI script, since the user and permissions tend to be tricky with CGI scripts. config_dir, config directory The directory where configuration files are kept, in a hierarchical manner which mirrors that of the data directory. This defaults to being the same directory as the data_dir. flavour_dir, flavour directory The directory where flavour files are kept (see "flavour"), in a hierarchical manner which mirrors that of the data directory. base_dir, base directory For convenience, one can just set a "base" directory and Posy will set the data_dir to being $base_dir/data, the state_dir to being $base_dir/state, and the flavour_dir to being $base_dir/flavours and the config_dir to being the same as data_dir. full path, full filename The absolute location of a given file; the absolute pathname. path (a) the relative location of a file (relative to the data directory or to the top of the website, depending on context) (b) the current request path (which may or may not be the relative location of a file) path-type The type of request path. This can be "entry", for an individual file, "category", for a sub-directory, "chrono" for a dated request, "top_entry" for an entry at the top of the website, "top_category", for the very root page, or "file" for a file which is not an entry. basename The "base" name of a file. So a file called /wibbles.txt would have a basename of "wibbles". chunk A given output page is pasted together from several chunks, each of which has a "flavour" template for it. The chunks are: content_type The MIME-type of the output page. Usually this is text/html, but some variations may call for text/plain or something else. head The "head" part of the page; which usually includes the opening tag, the content, and the opening tag and any initial content required. header A header part of a page; something which may or may not be repeated over the page, depending on how its contents change. entry The template for the actual page content; for pages which source multiple entry-files per page, this is repeated for each entry file. An entry file is just an individual input content file. foot The "foot" part of the page; usually contains trailing content, and the closing and tags. flavour The Posy system, like the blosxom system, enables use of multiple template-sets by giving them a "flavour" extension, which can be parsed from the initial request path by either the extension of the request path, or by a "flav" parameter. One can then set up a different template-set for each flavour, and customize the look of the output pages while keeping the content separate. ==== REQUIRES ==== File::Spec File::Copy File::stat File::Find Data::Dumper Storable CGI::Minimal Test::More ==== INSTALLATION ==== Since this is a set of modules and scripts for a website-generator, then installation needs will vary depending on the particular setup a person has. There are two parts to the installation, no matter the setup: installing the modules, and installing the CGI script. This section covers installing the modules. The instructions for installing the CGI script are in the script itself; just run perldoc on it. perldoc ./posy.cgi But first, the modules. == Administrator, Automatic == If you are the administrator of the system, then the dead simple method of installing the modules is to use the CPAN or CPANPLUS system. cpanp -i Posy This will install the modules and the ``posy_static'' script in the usual places which they get installed when one is using CPAN(PLUS). Note, however, that this does NOT install the CGI script, and that this will need to be done separately. Therefore you will need to grovel around to find the directory into which the Posy source was placed, in order to get at the CGI script to install it. Therefore you may find it simpler to just download the Posy tarball and install it by hand. Or, you may wish to install the Posy bundle: cpanp -i Bundle-Posy This installs not only the base Posy system, but all the major plugins. You still have to install the posy.cgi by hand, though. == Administrator, By Hand == If you are the administrator of the system, but don't wish to use the CPAN(PLUS) method, then this is for you. Take the Posy-*.tar.gz file and untar it in a suitable directory. tar -xzvf Posy-0.81.tar.gz cd Posy-0.81 To install this module, run the following commands: perl Build.PL ./Build ./Build test ./Build install Or, if you're on a platform (like DOS or Windows) that doesn't like the "./" notation, you can do this: perl Build.PL perl Build perl Build test perl Build install == User With Shell Access == If you are a user on a system, and don't have root/administrator access, you need to install Posy somewhere other than the default place (since you don't have access to it). However, if you have shell access to the system, then you can install it in your home directory. Say your home directory is "/home/fred", and you want to install the modules into a subdirectory called "perl". Download the Posy-*tar.gz file. tar -xzvf Posy-0.81.tar.gz cd Posy-0.81 perl Build.PL --install_base /home/fred/perl ./Build ./Build test ./Build install This will install the files underneath /home/fred/perl. You will then need to make sure that you alter the PERL5LIB variable to find the modules, and the PATH variable to find the script (posy_static). Therefore you will need to change: your path, to include /home/fred/perl/script (where the script will be) PATH=/home/fred/perl/script:${PATH} the PERL5LIB variable to add /home/fred/perl/lib PERL5LIB=/home/fred/perl/lib:${PERL5LIB} If you alter these in your setup files (e.g. .login) then they will be set when you log in, and you will be able to run the scripts without having to do anything special. However, please take note of the value you used for PERL5LIB -- you will need this when setting up the CGI script. == User With FTP-only Access == Okay, so you have an ISP/Web-Host, where you have your site, and you want to use Posy for it. You can ftp files from your PC to your site, but you don't have shell access. The most sensible thing I can think of is that you set up your entire site on your own PC at home, and then mirror it with FTP on your account with your ISP. If your ISP uses Linux, then it would probably be easier on you if you got Linux as well. (But how to install Linux is definitely beyond the scope of this document!) So follow the instructions for "User With Shell Access", but I can't guarantee that it will work, since if you don't have shell access on the system which has your web pages, it will be harder to troubleshoot if things go wrong. ==== AUTHOR ==== Kathryn Andersen (RUBYKAT) perlkat AT katspace dot com http://www.katspace.com ==== COPYRIGHT AND LICENCE ==== Copyright (c) 2004-2005 by Kathryn Andersen This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.