XML::Comma INSTALL
XML::Comma is an XML information management framework. For an example of
this code "in the wild," check out http://allafrica.com. Over 500 articles
per day are added to the site from over 70 sources, and it is all managed
with HTML::Mason and XML::Comma.
XML::Comma is generally used in conjunction with the Apache web server
and the HTML::Mason web development system. XML::Comma requires a
database: either MySQL or PostgresSQL.
XML::Comma has been tested with Apache 1.3.x, mod_perl 1.2.x, HTML::Mason
1.0+ (0.86 and 1.0 are the same codebase), PERL 5.005_03+ (including 5.6.0),
MySQL 3.23+, and PostgresSQL.
For more information about XML::Comma, point a web browser at
http://xymbollab.com/tools/comma/, or read the tutorial included with
the XML::Comma distribution at docs/guide.html
-----------------------------------------------------------------------
Notes on Apache/mod_perl installation:
One ABSOLUTELY MUST install Apache with the built-in Expat stuff disabled.
Accomplish this by adding '--disable-rule=expat' to the APACI Apache
configure... in some cases, mod_perl may add this automatically when the
configuration for mod_perl is executed.
When you install perl (via Makefile.PL), it's probably best to add
EVERYTHING=1 in order to ensure that all the callbacks are installed. This
may not be necessary, but it's the only way we've tested it up to this
writing.
Lastly, DO NOT install mod_perl as a DSO. If you don't know what this
means, just ignore it and follow the instructions in the mod_perl
distribution for the statically linked module (this is the default, I
believe).
URLS: http://perl.apache.org, http://httpd.apache.org
-----------------------------------------------------------------------
Notes on HTML::Mason installation:
Just a couple notes. First off, make sure your DefaultType in httpd.conf is
set to text/html. This is important, and if you email any of the mailing
lists without having done this, you are probably an idiot ;)
URLS: http://www.masonhq.com
-----------------------------------------------------------------------
Notes on PERL installation:
As mentioned previously, we have tested this with PERL 5.005_03 and 5.6.0.
Other versions may work as well. The DBI modules for your database of
choice will need to be installed (via CPAN is fine - 'perl -MCPAN -e
shell'). There are a few other PERL modules that are needed to get things
smoking, including Apache::Util and Net::SMTP. I'll try to compile a
complete list of necessary modules some time soon.
-----------------------------------------------------------------------
Notes on database installation:
MySQL and Postgres work fine. You will need to have one database dedicated
to the XML::Comma indexing. You won't need to create any tables-- Comma
takes care of that all for you! All you'll need is the username and
password for the database.
-----------------------------------------------------------------------
Okay. Now you're probably ready for the XML::Comma installation. Simply
enter the XML directory, and execute:
perl Makefile.PL (doesn't take any args right now)
make
make install (you need to be root for this step).
The easiest way to test the installation is to now run the command 'perl
manual-test.pl' (after installation). If any of the tests fail, there
*should* be meaningful error messages that suggest installation of
additional modules, etc.
You DO need to configure XML::Comma and make some directories. The
following configurations are found in the file Comma.pm. In my
installation, this file is found in /usr/lib/perl5/site_perl/5.6.0/XML/.
Where it installs on your machine will depend upon how you have perl
configured.
1) comma_root -
This is the base directory for XML::Comma. I use the directory
/usr/local/comma (parallel to my htdocs directory). You can use
anything, but make sure it's a valid directory. Any application that
uses Comma will need to have read and write access to this directory.
2) document_root -
The document root directory is where Comma will store documents. Comma
will create subdirectories in this directory and populate them with XML
documents, so make sure there is a) enough space and b) read/write
access for the appropriate applications.
3) defs_directories -
XML::Comma's basic architecture relies on XML definitions which reside
in any of these directories. I use $base_directory/defs in my
installation, plus $base_directory/macros (for the macros, obviously)
and subdirectories of $base_directory/defs for application-specific
functions. You can have as many of these as necessary, but you should
probably avoid having defs of the same name in different directories.
4) defs_extention - (yes, it is spelled "wrong")
If you want, you can change this from the default .def. One reason you
might want to change this is if you are using emacs or vim, and want to
specify an extension that will make a syntax file or emacs mode load
automatically.
5) macro_extention -
See #4. These files are PERL code, not XML.
6) hash_module -
Any of the Digest:: modules from CPAN should work here. We use
Digest::MD5, which, of course, requires this module to be installed.
7) index_sql_syntax -
Right now, this is either Pg for Postgres or mysql for MySQL. Just
pick whichever one you are using.
8) index_dbi_connect_info -
This string is of the form 'DBI:mysql:database=______:host=______',
followed by the database username, then the password. Just fill in
the blanks.
These are the basic configurations. If you run into any problems, just drop
an email to comma@allafrica.com, and we'll try to be helpful.