[pmwiki-users] Re: Root README.txt With a docs/ Directory
christian.ridderstrom at gmail.com
christian.ridderstrom at gmail.com
Fri Dec 30 16:15:48 CST 2005
On Fri, 30 Dec 2005, Patrick R. Michaud wrote:
> Let me recap the way things appear to me on this issue at the moment,
> to invite comment/confirmation/condemnation. :-)
> * I think the distribution should definitely have a useful README.txt
> in the pmwiki base directory. Hagan's version (with small modifications
> discussed on the list) is what we'll start with.
I've just suggested elsewhere that you/we extract it's content from a wiki
page such as PmWiki/README. This would make maintenance easier.
> * I don't know if we need a separate INSTALL.txt or if this should
> just be part of the README.txt file. If we create a separate
> "docs/" directory to hold text files, then we can place an INSTALL.txt
> there, otherwise I think we just make it part of README.txt to
> reduce clutter in the base directory.
Makes sense to me. (I'd say INSTALL isn't necessary, but I use subversion
> * We'll continue to have a sample-config.php file, but it's not
> clear where this file belongs. Currently it's in the base directory,
> which means it's quickly spotted by newbie admins (a good thing),
> but adds more overhead to the base directory. The sample-config.php
> could go into local/, where it's little less likely to be seen
> (how much less likely?) but more likely that the admin will then
> properly put config.php in its desired location. It could also
> go into a docs/ directory, but I'm not entirely sure it's really
I'd like to suggest (again) that it's placed as
The docummentation must clearly say where the examples can be found. If we
write this in several places PmWiki/Installation, README, then that should
be enough. The person installing PmWiki must read some of the documenation
> * One possible point of confusion with having a "docs/" directory
> is that a quick file perusal might seem to indicate that PmWiki
> doesn't come with a lot of documentation (since the bulk of the
> documentation is really being stored as wiki pages in wikilib.d/).
> Also, some things that we're talking about putting into "docs/"
> are really scripts and not documentation (albeit the scripts
> are heavily commented).
You could ship a HTML-copy of all documenation pages if you really felt
like it (please make that optional then :-)
I don't think that's a big problem though.. a big README and/or index.html
should take care of it.
> * If we have a "docs/" directory, then COPYING.txt can go there,
> otherwise it remains in the base directory.
To be honest, and in my personal opition, having somewhere to place
COPYING.txt seems the best motivation for docs/ so far.
I assume it's not ok to place COPYING in scripts/ or pub/?
> * I think we may need a sample-farmconfig.php somewhere, probably
> in the same location as sample-config.php. This probably argues
> against keeping sample-config.php in the base directory -- i.e.,
> they should go in either local/ or docs/ .
Yay for a sample-farmconfig.php!
> * PmWiki needs a scripts/secure.php that (re)sets PmWiki's defaults
> to their most "secure" settings. This script can also be heavily
> commented to explain what each setting is changing.
> * I don't yet see a need for a sample-secureconfig.php file, or
> at least I don't see how it would substantially differ from
> sample-config.php (which will reference scripts/secure.php above).
Guess I'll have to trust you on this. Personally I can see how it'd feel
safer to start from a sample-secureconfig.php and then modify that if you
want a really secure installation.
Christian Ridderström, +46-8-768 39 44 http://www.md.kth.se/~chr
More information about the pmwiki-users