Read Me

slidePresenter - README

Contents:
1. GETTING HELP
2. INSTALLATION
3. CONFIGURATION
4. UPGRADING
5. USE
6. LICENSE

--------------------------------------
1. GETTING HELP
Email all questions and requests to: ashaw@users.sourceforge.net, or join
a mailing list for help:

    "slides-users" - general discussion for slidePresenter users:
    https://lists.sourceforge.net/lists/listinfo/slides-users.

    "slides-announce" - occassional announcements of patches and upgrades
    https://lists.sourceforge.net/lists/listinfo/slides-announce.

Please write the author at ashaw@users.sourceforge.net and tell me why you
decide to use slidePresenter, or why you don't.  And ask for improvements --
you will be heard.

In the spirit of "release early, release often," this code is posted as
soon as it's ready: it works, it's essentially free of bugs, and it's
reasonably readable. This way I can use it, and others can too -- right now.

However, there are lots of ways to improve this. I'm the kind of slacker
who could sit coding all day, so I have to limit myself, but by downloading
and using this software, you give me an excuse to get back in there and
improve it.

--------------------------------------
2. INSTALLATION

!! WARNING !!
    If you are upgrading from a previous version of slidePresenter,
    you MUST back up your data files or you risk losing all existing
    presentation data.  See Section 4: UPGRADING for details.  Make
    your backups, then come back and continue with the installation.

Install slidePresenter on your server in a few simple steps:

    1. Unzip the distribution archive, being sure to maintain directory
        structure.

    2. Upload all contents of the unzipped "slides" directory to your
        server in a publicly accessible location (here we'll assume it's
        http://example.com/slides/).

    3. Set permissions on the "data" directory, and all of its
        contents, so that they will be writable by the web server
        (e.g., use `chmod -R 757 data` from the Linux command
        line, or use the "apply to all sub-directories and files"
        option if setting permissions with an FTP program that
        provides such a feature).

    4. Give careful consideration to your hosting environment, and set up
        the "data" directory according to ONE of these two methods:

        "More Cautious":        You should definitely take this option if
        you are using a shared hosting package (any arrangement in which
        your server is shared by other users whom you don't know and/or
        don't trust):
            a. Move the "data" directory to a location above your web
                server's document root.  (Consult your web host's
                documentation on how to do this.)  You will need to enter
                the new location of this directory for the SLP_DATA_DIR
                setting in the config file (see step 5).
            b. In the config file (see step 5), set the SLP_SECURITY
                setting to "MoreCautious".

        "More Convenient":    You may choose this option if you are using
        a dedicated server (or virtual dedicated server, sometimes called
        "VPS" or "VDS"), or if you are otherwise confident in the system's
        ability to prevent other people from changing your files:
            a. Set permissions on the "presentations" directory, and all of
                its contents, so that they will be writable by the web server
                (e.g., use `chmod -R 757 presentations` from the Linux
                command line, or use the "apply to all sub-directories and
                files" option if setting permissions with an FTP program
                that provides such a feature).
            b. In the configuration file (see step 5), set the SLP_SECURITY
                setting to "MoreConvenient".

    5. Rename or copy the file "dist-config.php" to "config.php". See
        the section on CONFIGURATION below for details on editing
        this file.

    6. Test your installation by pointing your browser to
        http://example.com/slides (replacing "http://example.com/slides"
        with the actual location of the slidePresenter files, of course).
        See section 5. USE for details on how to use slidePresenter,
        especially if you chose the "MoreCautious" option for SLP_SECURITY
        above.

--------------------------------------
3. CONFIGURATION
Rename or copy the file "dist-config.php" to "config.php", and edit it
to configure your slidePresenter installation.  The comments in the file
should make it easy to understand, but here are some important points to
consider:
    1. You must enter a username and password for the settings
        SLP_ADMIN_USERNAME and SLP_ADMIN_PASSWORD.  If you don't do this
        you won't be able to sign in as admin.
    2. The setting SLP_USE_UPLOAD_PROGRESS_METER is set to FALSE by
        default, meaning that when you use slidePresenter to upload your
        slide images, you will not have the benefit of a real-time
        progress meter for your uploads.  If you want a real-time
        progress meter for your uploads, set this to TRUE, and keep in
        mind these points:
            a. This feature requires a working Perl installation on
                your server.  If you'd rather not deal with this,
                you can safely skip this section and use slidePresenter
                without this feature.
            b. Be sure to set the settings SLP_UPLOAD_CGI_URL and
                SLP_CGI_BIN_PATH as described in config.php
            c. Edit the file extras/cgi-bin/upload_settings.inc.php to
                configure this feature.
            d. Copy the files upload_settings.inc.php and upload.cgi
                from extras/cgi-bin/ to the directory named in
                SLP_CGI_BIN_PATH
            e. Ensure that the file SLP_CGI_BIN_PATH/upload.cgi is
                executable by your web server (eg., use `chmod 755
                upload.cgi` from the Linux command line)
            f. Ensure that the file SLP_CGI_BIN_PATH/upload_settings.inc
                is readable by your web server (eg., use `chmod 755
                upload.cgi` from the Linux command line)

--------------------------------------
4. UPGRADING
If you are upgrading or otherwise installing the slidePresenter files over
an existing installation, you MUST backup the contents of certain directories
before installing the contents of the slidePresenter distribution.  Without
this step you will lose all existing presentations and their contents when you
unzip the installation files.

    Upgrading from...    backup this directory
    ----------------     ---------------------
    before 0.30          presentations/
    0.30 or higher       data/

Once you have completed this step, continue with the installation as normal.

After you have completed the installation, you may import your backed-up
data into the new installation, using one of these two methods, depending
on the value of the SLP_SECURITY option in the config.php file (see
Section 2: INSTALLATION, step 4):

        "More Cautious":        If SLP_SECURITY is set to "MoreCautious",
        you will only be able to import data from the command prompt (the
        "DOS Prompt" on Windows, or SSH / telnet on *nix systems).  From the
        command prompt, type the equivalent of this command:
            php /path/to/slidePresenter/cli/importData.php
        The command-line interface will walk you through the steps of
        importing your old presentation data into the new installation.

        "More Convenient":      If SLP_SECURITY is set to "MoreConvenient",
        you will only be able to import data from the Web-based interface.
        Open your browser to the slidePresenter installation and sign in
        as the administrator.  Select the "Import Data" link from the
        main screen, and slidePresenter will walk you through the steps
        of importing your old presentation data into the new installation.

--------------------------------------
5. USE
You can use slidePresenter to deliver any number of presentations. The
presentation "Sample" is already included as an example.  Without
administrative priveleges, users will only see a "View" link for each
presentation; by signing in as administrator, you will also see links to
"Edit" and "Deliver" for each presentation, as well as links for adding a
new presentation.

NOTE: When SLP_SECURITY is set to "MoreCautious" (see INSTALLATION above),
the functionality of adding and removing slides and presentations can only
be achieved from the command-line with the PHP scripts in the cli/
directory.

    1. To edit an existing presentation:
        1. Sign in as administrator.  See the INSTALLATION section above
            for important notes about administrator username and password.
        2. Click the "Edit" link for the presentation you wish to edit.
        3. The next screen will allow you to edit the presentation by
            adding and/or deleting slides, arranging slides in the order
            you prefer, changing the public name or description of the
            presentation, or deleting the presentation altogether.
        4. Click "Save" to save your presentation changes.
        NOTE: When SLP_SECURITY is set to "MoreCautious" (see INSTALLATION
            above), this functionality can be achieved from the command-
            line with the PHP scripts importSlideFile.php, delSlide.php,
            and delPresentation.php.  From the command prompt, type the
            equivalent of the appropriate command:
            php /path/to/slidePresenter/cli/importSlideFile.php
            php /path/to/slidePresenter/cli/delSlide.php
            php /path/to/slidePresenter/cli/delPresentation.php

    2. To add a new presentation:
        1. Sign in as administrator.  See the CONFIGURATION section above
            for important notes about administrator username and password.
        2. Click the "Add New Presentation" link, and then enter a
            nickname, public name, and description for the presentation.
        3. Click the "Create" button to create the presentation.
            slidePresenter will alert you if the nickname you've chosen
            is already in use, in which case you'll need to choose another.
        4. The next screen will allow you to edit the presentation as
            described above.
        NOTE: When SLP_SECURITY is set to "MoreCautious" (see INSTALLATION
            above), this functionality can be achieved from the command-
            line with the PHP script addPresentation.php.  From the command
            prompt, type the equivalent of:
            php /path/to/slidePresenter/cli/addPresentation.php

    3. To add images to a presentation:
        1. You may upload images, either one-by-one or in a single Zip
            archive, from within the "Import" section of the Edit Presentation
            screen.  Select the "My Computer" tab to upload and import files
            from your desktop computer.
        2. If you wish to avoid uploading large files through the Web interface,
            you can instead upload them via FTP to the directory
            "data/server_files/".  Then, in the "Import" section of the Edit
            Presentation screen, select the "On Server" tab to choose files
            located in that directory for importing into the presentation.
            The "On Server" import option was added in slidePresenter-0.30
        NOTE: When SLP_SECURITY is set to "MoreCautious" (see INSTALLATION
            above), this functionality can be achieved from the command-
            line with the PHP script importSlideFile.php.  From the command
            prompt, type the equivalent of:
            php /path/to/slidePresenter/cli/importSlideFile.php

    4. To deliver or broadcast a presentation to your audience:
        1. Sign in as administrator.  See the CONFIGURATION section above
            for important notes about administrator username and password.
        2. Click the "Deliver" link for the presentation you wish to
            deliver.
        3. Move forward or backward through the slides with the control
            arrows appearing below the slides, or by using your keyboard's
            left and right arrow keys.

    5. Your viewers can access the presentation as you deliver it by
        clicking the "View" link for that presentation.


--------------------------------------
6. LICENSE AND COPYRIGHT
See the file LICENSE.txt for a copy of the GNU General Public License (GPL),
version 2.

    slidePresenter Copyright (C) 2006  Allen Shaw

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License along
    with this program; if not, write to the Free Software Foundation, Inc.,
    51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.

Some portions of this package are distributed under other licenses, as
follows.
    Contents of directory 'extras':  (See file extras/README.txt)

$Id$