[pmwiki-users] INSTALL.txt and UPGRADE.txt

H. Fox haganfox at users.sourceforge.net
Mon Jan 2 02:50:06 CST 2006


Imagine you've downloaded the pmwiki-latest archive and unpacked it
for the first time.  You've just read README.txt and your interest is
piqued.  Now you're going to open docs/INSTALL.txt and proceed with
the installation.

What needs to be in that file?  How about the following?

~~~
This is the INSTALL.txt file for PmWiki.  The purpose of this document
is to provide convenient steps so an administrator can have a PmWiki
site up and running quickly.  Once your site is running you can read
the bundled documentation pages.

More extensive information about installing PmWiki is available at
    http://www.pmwiki.org/wiki/PmWiki/Installation

Here are some quick steps to start you on your path to a complete,
customized installation.:

1) Put the software in a location accessible by your webserver.

2) Point your browser to pmwiki.php.

3) You may see an error message saying that PmWiki needs to have
   a writable wiki.d/ directory.  If so, follow the directions to
   establish one.

4) Create an index.php file that contains the following single line
   (with no closing "?>" on purpose):

<?php include('pmwiki.php');

5) Copy the sample configuration file from docs/sample-config.php to
   local/config.php and edit it to suit your preferences.

That's it.  Next you'll probably want to browse your new site and
read the bundled documentation.

Enjoy!
~~~

Keep in mind that INSTALL.txt will not be a comprehensive installation
document, rather it's oriented toward getting a reasonably experienced
administrator up and running with minimum hassle.

Some thoughts...

* The idea should be to keep it brief and hand the user over to the
main documentation

*  It should be clear that the main documentation is distributed as wiki pages.

* Not much, if anything, about downloading needs to be included, since
obviously the INSTALL.txt file isn't readable unless the archive has
already been downloaded.

* I doubt anyone will want to *start* with a farm installation, so
nothing about farms needs to be included.

 * If no writable wiki.d/ directory exists, PmWiki automatically
generates instructions for creating one.  Is it OK to rely on those as
part of the quick-install procedure?

* I think two optional steps should be included:
    - writing a one-line index.php file and
    - copying the sample-config.php file to local/.
Are those enough, but not too much?

There's a note at the bottom of PmWiki.Installation referring Windows
users to the SimuleditWithoutPopen recipe.  Is that out-of-date or is
it still required?

On 12/29/05, DaveG <pmwiki at solidgone.com> wrote:
> H. Fox wrote:
> > A docs/UPGRADE.txt document could be ... *very* handy to have around,
> > if only to remind someone of the command syntax necessary to copy the
> > files (cp -a ...).
> Don't assume only Unix... :)

The PmWiki.Upgrades page appears to do that, so what brief, helpful
non-Unix reminder text do you think should be included in
docs/UPGRADE.txt?

Hagan




More information about the pmwiki-users mailing list