source: gs2-extensions/ngramj/src/wiki/wikipedia2text/wiki2xml/php/README@ 25141

=pod

=head1 INTRODUCTION

You can read this document better with:

    perldoc README

Otherwise, please just ignore the funny characters.

=head1 NAME

WIKI2XML - Wikitext to XML converter

=head1 INSTALLATION

=head2 Download/Checkout

Check out the current release from SVN:

    svn co http://svn.wikimedia.org/svnroot/mediawiki/trunk/wiki2xml

=head2 Extension or cgi-bin?

There are two ways to install wiki2xml:

    As extension: Special::Wiki2XML
    As cgi-bin: http://example.com/wiki/wiki2xml/w2x 

The former should be prefered.

=head2 As Extension

To enable wiki2xml as extension, put all files in the C<< php >> directory into a
C<< wiki2xml >> subdirectory of your MediaWiki extensions directory.

    htdocs
        \- wiki
            \- extensions
         \- wiki2xml        <-- create this directory
                     \- w2x.php     <-- copy files here
                     \- wiki2xml.php    etc.

Then add

        require_once ("extensions/wiki2xml/extension.php");

to your C<< LocalSettings.php >>. The extension can then be accessed as
C<< [[Special:Wiki2XML]] >>.

=head2 cgi-bin - Copy files

The alternative method is to install wiki2xml as cgi-bin script:

Copy the subdirectory C<< ./php/ >> to your server's C<< wiki/ >>
directory as a subdirectory named C<< w2x >>:

    htdocs
        \- wiki
            \- w2x                <-- here
                \- w2x.php
                \- wiki2xml.php        etc

Access it as C<< http://example.com/wiki/w2x/w2x.php >>.

=head2 Configuration

The configuration is stored in C<< default.php >> and C<< local.php >>.

There is a C<< sample_local.php >> file, copy it to C<< local.php >>
and then edit it to match your configuration.

On a Unix/Linux server the following can be used as a starting point:

    # Directory for temporary files:
    $xmlg["temp_dir"] = "/tmp";

    # Path to the zip/unzip programs; can be omitted if in default
    # executable path:
    #$xmlg["zip_odt_path"] = "";

    # Command to zip directory $1 to file $2:
    $xmlg["zip_odt"] = 'zip -r9 $1 $2';

    # Command to unzip file $1 to directory $2:
    $xmlg["unzip_odt"] = 'unzip -x $1 -d $2';
 
=head1 USAGE

Open the correct URL (depending on install type, see above) in your browser.

Wiki2xml should present you with a form with a textarea and several buttons.

=head2 Using URL parameters

Parameters:

    doit=1
    text=lines_of_text_or_titles
    whatsthis=wikitext/articlelist
    site=en.wikipedia.org/w
    output_format=xml/text/xhtml/docbook_xml/odt_xml/odt

Optional:

    use_templates=all/none/these/notthese
    templates=lines_of_templates
    document_title=
    add_gfdl=1
    keep_categories=1
    keep_interlanguage=1
 


=head1 TROUBLESHOOTING

If you get errors like the following:

    Warning: fopen(/tmp/ODD6Rq1qt-DIR/content.xml): failed to open stream:
    No such file or directory in /.../wiki/wiki2xml/w2x.php on line 112

then make sure that the tmp directory you selected is really writable by
your webserver.

=head2 OpenOffice Output

For OpenOffice output, the converter will extract a file called C<< template.odt >>
into the temp directory. It will then replace/modify the files in it, zip it
up again and then offer the browser the resulting file as a download.

=head1 AUTHOR

Copyright 2005-2006 by Magnus Manske <[email protected]>

Released under the GPL.

=cut