[pmwiki-users] Re: Root README.txt With a docs/ Directory

[christian.ridderstrom at gmail.com]

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
for that...)

> * 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
>   "documentation".

I'd like to suggest (again) that it's placed as

	scripts/examples/config.php

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 
at least...

> * 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.

Double yay!

> * 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.

regards
/Christian

-- 
Christian Ridderström, +46-8-768 39 44               http://www.md.kth.se/~chr