Wiki content at QuickStart Changed by someone at IP 212.248.12.68 :
@@ -0,0 +1,375 @@
+<?xml version="1.0"?>
+<!DOCTYPE article [
+<!ENTITY prompt "% ">
+]>
+<article>
+<artheader>
+ <title> </title>
+ <author>
+ <firstname>Kip</firstname>
+ <surname>Hampton</surname>
+ <affiliation>
+ <address><email>[EMAIL PROTECTED]</email></address>
+ </affiliation>
+ </author>
+ <abstract>
+ <para>
+ This document is a <emphasis>quick start</emphasis> guide designed to help
developers
+ deliver transformed XML with AxKit as quickly as possible. As such, many
of the
+ finer points of AxKit's extremely robust interface will not be covered.
For a more
+ descriptive introduction, please see Matt's <ulink url=
+ "http://axkit.org/docs/introduction.dkb";>Introduction to AxKit</ulink>.
+ </para>
+ <para>
+
+ </para>
+ </abstract>
+</artheader>
+<sect1>
+<title>Installing and Configuring AxKit</title>
+<para>
+This guide presumes that you already have an
+<ulink url ="http://www.apache.org/httpd.html";>Apache</ulink> httpd server
running
+<ulink url="http://perl.apache.org/";>mod_perl</ulink>. If this is not
+the case, please visit the <ulink url
+="http://www.apache.org/httpd.html";>Apache
+</ulink> and <ulink url="http://perl.apache.org/";>mod_perl</ulink> pages for
+more information.
+</para>
+<sect2>
+<title>Step 1 - Download and Install AxKit</title>
+<para>
+First, visit the AxKit <ulink url="http://www.axkit.org/download/";>
+download directory</ulink> and grab the latest tarball. Once you've
+downloaded the source, type the following:
+<informalexample>
+<programlisting>
+&prompt; <userinput>tar -zxvf AxKit-x.xx.tar.gz</userinput>
+&prompt; <userinput>cd AxKit-x.xx/</userinput>
+&prompt; <userinput>perl Makefile.PL</userinput>
+&prompt; <userinput>make</userinput>
+&prompt; <userinput>make test</userinput>
+&prompt; <userinput>make install</userinput>
+</programlisting>
+</informalexample>
+If <literal>perl Makefile.PL</literal> warns about missing modules, make a
note of these
+dependencies and install the corresponding Perl packages before proceeding
with the AxKit
+installation. AxKit will not be properly installed, otherwise.
+</para>
+</sect2>
+<sect2>
+<title>Step 2 - Edit Your httpd.conf File</title>
+<para>
+Add the following lines to your httpd.conf:
+<informalexample>
+<programlisting>
+PerlModule AxKit
+SetHandler perl-script
+PerlHandler AxKit
+AxAddStyleMap application/x-xpathscript Apache::AxKit::Language::XPathScript
+AxAddStyleMap text/xsl Apache::AxKit::Language::LibXSLT
+
+# add the following only if you intend to install Sablotron
+AxAddStyleMap text/xsl Apache::AxKit::Language::Sablot
+</programlisting>
+</informalexample>
+</para>
+<para>
+Don't worry that this looks like AxKit will deliver all of your files,
+if it doesn't detect XML at the URL you give it, it will let the httpd
+deliver it as normal. If you're still concerned, put <emphasis>all but the
first</emphasis>
+configuration directive in a <ulink
+url="http://www.apache.org/docs/mod/core.html#location";
+><literal><Location></literal></ulink> section. Note that the first
+line: <literal>PerlModule AxKit</literal> <emphasis>MUST</emphasis>
+occur in your httpd.conf so that it is parsed in the parent httpd
+process. This is because it adds configuration directives to the entire
+Apache httpd. If you do not do this you will get SEGFAULTs.
+</para>
+<para>
+Now, stop and restart your Apache server and assuming you've had no trouble
+with the steps above, you are now ready to begin publishing transformed XML
+with AxKit!
+</para>
+</sect2>
+</sect1>
+<sect1>
+<title>Installing the Sablotron XSLT Processor (Optional)</title>
+<para>
+This section assumes that you will be installing the Sablotron XSLT processor
along with
+AxKit. If you want to see AxKit in action but do not want to install Sablotron
you may safely
+skip to the <ulink url="quick_start.dkb?section=3">next section</ulink>.
+</para>
+<sect2>
+<title>Step 1 - Download and Install the Sablotron XSLT
+Processor</title>
+<para>
+Next, fetch either the source or appropriate binary distribution of the
+Sablotron XSLT Processor from <ulink url="http://www.gingerall.com/";>
+www.gingerall.com</ulink>. As of version 0.50, Sablotron requires the shared
library version
+of the Expat XML parser to be installed before installing Sablotron. Visit
<ulink url=
+"http://sourceforge.net/projects/expat/";>the Expat project page</ulink> for
sources and
+installation instructions.
+</para>
+<para>
+Installing Sablotron from the source:
+<informalexample>
+<programlisting>
+&prompt; <userinput>tar -zxvf Sablot-x.xx.tar.gz</userinput>
+&prompt; <userinput>cd Sablot-x.xx/</userinput>
+&prompt; <userinput>./configure</userinput>
+&prompt; <userinput>make</userinput>
+&prompt; <userinput>make install</userinput>
+</programlisting>
+</informalexample>
+Please note that Sablotron build process described here covers versions 0.50.
Consult the
+INSTALL and README files that shipped with the version you downloaded for
details
+and possible changes.
+</para>
+</sect2>
+<sect2>
+<title>Step 2 - Install the XML::Sablotron Perl Library</title>
+<para>
+Next, install XML::Sablotron. You can either install the package by hand or
use the CPAN
+shell. To install using the CPAN shell type:
+<informalexample>
+<programlisting>
+&prompt; <userinput>perl -MCPAN -e shell</userinput>
+&prompt; <userinput>install XML::Sablotron</userinput>
+</programlisting>
+</informalexample>
+To install the packages yourself, get the latest version of the XML::Sablotron
Perl package
+from <ulink url="http://www.gingerall.com/";>www.gingerall.com</ulink>, cd to
the
+directory you downloaded the tarball to and type:
+<informalexample>
+<programlisting>
+&prompt; <userinput>tar -zxvf XML-Sablot-x.xx.tar.gz</userinput>
+&prompt; <userinput>mv XML-Sablot-x.xx/ Sablot-x.xx/</userinput>
+&prompt; <userinput>cd Sablot-x.xx/XML-Sablot-x.xx/</userinput>
+&prompt; <userinput>perl Makefile.PL</userinput>
+&prompt; <userinput>make</userinput>
+&prompt; <userinput>make test</userinput>
+&prompt; <userinput>make install</userinput>
+</programlisting>
+</informalexample>
+</para>
+</sect2>
+</sect1>
+<sect1>
+<title>Sample Document Transformations</title>
+<para>
+Now, we're going to see how AxKit works by transforming an XML file containing
data about
+Camelids (note the dubious Perl reference) into HTML.
+</para>
+<sect2>
+<title>Step 1 - A Sample XML Document</title>
+<para>
+First, you will need a sample XML file. Open the text editor of your choice
+and type the following:
+<informalexample>
+<programlisting><![CDATA[
+<?xml version="1.0"?>
+ <dromedaries>
+ <species name="Camel">
+ <humps>1 or 2</humps>
+ <disposition>Cranky</disposition>
+ </species>
+ <species name="Llama">
+ <humps>1 (sort of)</humps>
+ <disposition>Aloof</disposition>
+ </species>
+ <species name="Alpaca">
+ <humps>(see Llama)</humps>
+ <disposition>Friendly</disposition>
+ </species>
+</dromedaries>
+]]></programlisting>
+</informalexample>
+Save this file as test.xml.
+</para>
+</sect2>
+<sect2>
+<title>Step 2 - Create a Stylesheet</title>
+<para>
+Now, create the stylesheet to transform your XML document. If you have chosen
to install
+Sablotron or one of the other XSLT processors that AxKit supports you may use
either the XSLT
+or XPathScript samples below. If you have not installed an XSLT processor skip
directly to
+the XPathScript example.
+</para>
+</sect2>
+<sect2>
+<title>Using XSLT</title>
+<para>
+Start a new file and type the following:
+<informalexample>
+<programlisting><![CDATA[
+<?xml version="1.0"?>
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform";
+version="1.0">
+<xsl:template match="/">
+ <html>
+ <head><title>Know Your Dromedaries</title></head>
+ <body>
+ <table bgcolor="eeeeee" border="1">
+ <tr>
+ <th>Species</th>
+ <th>No of Humps</th>
+ <th>Disposition</th>
+ </tr>
+ <xsl:for-each select="dromedaries">
+ <xsl:apply-templates select="./species" />
+ </xsl:for-each>
+ </table>
+ </body>
+ </html>
+</xsl:template>
+
+<xsl:template match="species">
+ <tr>
+ <td><xsl:value-of select="@name" /></td>
+ <td><xsl:value-of select="./humps" /></td>
+ <td><xsl:value-of select="./disposition" /></td>
+ </tr>
+</xsl:template>
+
+</xsl:stylesheet>
+]]></programlisting>
+</informalexample>
+Save this file as test.xsl.
+</para>
+</sect2>
+<sect2>
+<title>Using XPathScript</title>
+<para>
+Create a new file and type:
+<informalexample>
+<programlisting><![CDATA[
+<%
+$t->{'humps'}{'pre'} = "<td>";
+$t->{'humps'}{'post'} = "</td>";
+$t->{'disposition'}{'pre'} = "<td>";
+$t->{'disposition'}{'post'} = "</td>";
+$t->{'species'}{testcode} = sub {
+ my $node = shift;
+ my $t = shift;
+ $t->{pre} = '<tr><td>' . findvalue('@name', $node) . '</td>';
+ $t->{post} = "</tr>";
+ return 1;
+}
+%>
+
+<html>
+<head>
+ <title>Know Your Dromedaries</title>
+</head>
+<body bgcolor="white">
+ <table bgcolor="eeeeee" border="1">
+ <tr><th>Species</th><th>No. of Humps</th><th>Disposition</th></tr>
+
+ <%= apply_templates('/dromedaries/species') %>
+
+ </table>
+</body>
+</html>
+]]></programlisting>
+</informalexample>
+Save this file as test.xps.
+</para>
+</sect2>
+<sect2>
+<title>Step 3 - Associate the XML Document with your Stylesheet</title>
+<para>
+Next, re-open the test.xml file and add the following just after the <?xml
version="1.0"?>
+declaration. If you have selected the XSLT example, add:
+<informalexample>
+<programlisting><![CDATA[
+<?xml-stylesheet href="test.xsl" type="text/xsl"?>
+]]></programlisting>
+</informalexample>
+ Or, if you have chosen the XPathScript sample, use:
+<informalexample>
+<programlisting><![CDATA[
+<?xml-stylesheet href="test.xps" type="application/x-xpathscript"?>
+]]></programlisting>
+</informalexample>
+Note that this line is telling AxKit which stylesheet to use and
+which handler to use for that stylesheet. Now, save the test.xml
+file and quit your editor.
+</para>
+</sect2>
+<sect2>
+<title>Step 4 - Finishing Up</title>
+<para>
+You are now ready to deliver your little zoological XML data file as
+formatted HTML! Just copy or move the XML and stylesheet files into the
+same directory under your httpd DocumentRoot. Then, point your browser to
+http://your-server.com/path/to/test.xml and you should see your data nicely
+formatted in an HTML table.
+</para>
+<para>
+Congratulations, you are now well on the road to adding XML, XSLT, XPathScript
and AxKit
+to your developmental toolbelt. For more information about AxKit's advanced
+features, please visit the <ulink url="http://www.axkit.org/";>AxKit
homepage</ulink>.
+</para>
+</sect2>
+<sect2>
+<title>If Things Go Wrong</title>
+<para>
+As I stated in the introduction, this document is designed to walk someone
through the
+AxKit instalation process, then, on to serving transformed documents as
quickly and simply as
+possible. Depending upon your setup, installing AxKit may require some special
attention to
+get it to sanely co-exist with some of the other tools that you may be using.
If you've had
+any trouble while following the steps outlined here, please consult the <ulink
url=
+"http://axkit.org/faq.xml";>AxKit FAQ</ulink>, and the AxKit User's <ulink url=
+"http://axkit.org/cgi-bin/ezmlm-cgi/4";>mailing list archives</ulink>.
+</para>
+</sect2>
+</sect1>
+<sect1>
+<title>Other Resources</title>
+<sect2>
+<title>mod_perl</title>
+<para>
+ <itemizedlist>
+ <listitem><ulink url="http://perl.apache.org";>mod_perl Homepage</ulink>
+ </listitem>
+ <listitem><ulink url="http://perl.apache.org/guide/";>mod_perl Guide
+ </ulink>
+ </listitem>
+ <listitem><ulink url="http://www.modperl.com/";>Writing Apache Modules
+ with Perl and C</ulink>
+ </listitem>
+ <listitem><ulink url="http://take23.org/";>mod_perl News and
Information</ulink>
+ </listitem>
+ </itemizedlist>
+</para>
+</sect2>
+<sect2>
+<title>XSLT</title>
+<para>
+ <itemizedlist>
+ <listitem><ulink url="http://www.w3.org/Style/XSL/";>W3C Specification
+ </ulink></listitem>
+ <listitem><ulink url="http://www.domesticgear.com";>Domestics
+ </ulink></listitem>
+ <listitem><ulink url="http://www.xml.com/pub/Guide/XSLT";>XSLT Resources at
XML.com
+ </ulink></listitem>
+ <listitem><ulink
url="http://www.mulberrytech.com/quickref/index.html";>Mulberry
+ Technologies' XPath and XSLT quick reference card (PDF).</ulink></listitem>
+ <listitem><ulink
url="http://www.zvon.org/xxl/XSLTreference/Output/index.html";>An
+ expanded XSLT reference from zvon.org.</ulink></listitem>
+ <listitem><ulink url="http://www.xslt.com/";>XSLT.com</ulink></listitem>
+ </itemizedlist>
+</para>
+</sect2>
+<sect2>
+<title>XPathScript</title>
+<para>
+ <itemizedlist>
+ <listitem><ulink
url="http://axkit.org/docs/xpathscript/guide.dkb";>XPathScript - A Viable
+ Alternative to XSLT?</ulink></listitem>
+ </itemizedlist>
+</para>
+</sect2>
+</sect1>
+</article>
