[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