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

Patrick R. Michaud pmichaud at pobox.com
Fri Dec 30 13:32:05 CST 2005


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

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

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

* If we have a "docs/" directory, then COPYING.txt can go there,
  otherwise it remains in the base directory.

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

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

Pm





More information about the pmwiki-users mailing list