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

[H. Fox]

On 12/29/05, Patrick R. Michaud <pmichaud at pobox.com> wrote:
> On Thu, Dec 29, 2005 at 03:06:18PM -0700, H. Fox wrote:
> >     This is the README.txt file for PmWiki, a wiki-based system for
> >     collaborative creation and maintenance of websites.  PmWiki is
> >     distributed with the following directories:
> >
> >       docs/           Documentation and sample configuration files
> >       local/          Local configuration scripts
> >       cookbook/       Recipes (add-ons) obtained from the Cookbook
> >       pub/            Publicly accessible files
> >       pub/css/          CSS stylesheet files
> >       pub/skins/        Layout templates (skins)
> >       scripts/        Some scripts that are part of PmWiki
> >       wikilib.d/      Some default wiki pages
>
> I think I would add the following:
>
>       In addition, once PmWiki is running the following directories
>       may also exist:
>
>         wiki.d/         Files containing local wiki pages
>         uploads/        Directory for attachments

Good idea.

Actually, pub/css/ should probably go with those since it doesn't
exist in the tarball...

> Also, do we need to mention pub/guiedit/, since it's part of the
> distribution?

Probably so.  I used Pmwiki/Installation as a starting point, and it's
not there.

I pulled all this together in a draft and put it here:
http://www.pmwiki.org/wiki/Test/READMEAndDocsDir

> >     For installation advice, see  docs/INSTALL.txt or visit
> >     http://www.pmwiki.org/wiki/PmWiki/Installation
>
> I'm wonder if docs/INSTALL.txt will get to be out of date/sync
> with the wiki page version. (OTOH, the installation instructions
> haven't changed much over PmWiki's history, so perhaps this isn't
> an issue.)

docs/INSTALL.txt should be a general enough so it doesn't need
frequent updating.  At the simplest level it could just refer to a
page or two on pmwiki.org.

I could come up with an INSTALL.txt if this looks like it might
happen, otherwise I don't want to waste my time.  I think the style
should be that of a quick but helpful note you'd write to someone
who's just about to get started -- or maybe just deciding whether to
do so.

> > * The docs/ directory would have files like
> >
> >     docs/
> >       .htaccess
> >       COPYING.txt
> >       INSTALL.txt
> >       cms-config.php
> >       sample-config.php
> >       secure-config.php
> >       [...]
>
> Since I don't have a cms-config.php

This whole thing came about from discussion about of adding
purpose-specific sample configuration files.  Maybe I should have come
up with better names like

      sample-config.php
      sample-cms-config.php
      sample-secure-config.php

IOW this is different than a scripts/secure-config.php that wold be
includ()ed to tighten up default settings.

Including scripts/secure-defaults.php (IMHO a better name for it)
would probably be the first thing in sample-secure-config.php file.

I think it would be *very* helpful to have a lot more configuration
samples in a well-organized set of files.

> or an INSTALL.txt, and I think
> (from previous discussions) that secure-config.php will properly
> belong as scripts/secure.php, I think we end up with:
>
>     docs/
>       .htaccess
>       COPYING.txt
>       sample-config.php
>
> I'm not sure that these 2 (3 if we create an INSTALL.txt) files
> deserve their own directory.  Perhaps there are a number of other
> things that will go in the docs/ directory, but following
> PmWikiPhilosophy #3, until we do have them I think it's better
> to stick with what we have now.
>
> However, I entirely agree that if we identify any more text-ish
> files that are to be part of the distribution, then we'll create the
> separate docs/ directory and structure it as proposed above.

Wonderful.

Again, Discussion of such extra text-ish files was what got me started on this.

Hagan