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

H. Fox haganfox at users.sourceforge.net
Fri Dec 30 14:59:02 CST 2005


On 12/30/05, Hans <design at softflow.co.uk> wrote:
> From http://www.pmwiki.org/wiki/Test/READMEAndDocsDir
>
> 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/skins/      Layout templates (skins)
>   pub/css/        Local CSS stylesheet files
>   scripts/        Some scripts that are part of PmWiki
>   wikilib.d/      Some default wiki pages
>
> Comment:
> I hope it will be not necessary to create a docs/ directory, and
> keep just the minimal text information in the root, as at present.

Out of curiosity, what's bothersome about having only a helpful README
in the root and a few convenient, newbie-oriented docs in a
non-servable docs/ directory?

Having the docs/ directory opens up the possibility of bundling more
configuration samples and an INSTALL.txt that someone can use to get
their wiki running -- *then* the online docs take over.

> The main documentation exists in form of wiki pages within wikilib.d,
> which the above does not make clear. So perhaps it can read:
> wikilib.d/      Default wiki pages including main documentation

How do you read those if the wiki isn't installed?  What about someone
who's curious, but nervous about installing?

The text files in docs/ shouldn't replace the main documentation,
rather they should supplement and enhance it.  This will make PmWiki
more attractive to people who are installing for the first time -- or
maybe just considering doing so.

"""
  One of the things that I find really annoying about *most*
  GPL software is that authors seldom answer all of

      What does this program do?
      What are all these files / directories?
      How do I get started?

  in an easy-to-find README.txt file.
"""

> pub/css/ is not included in the default distribution, but needs to be
> created later if indeed needed at all. But perhaps it can be part of
> the default setup, even if it remains empty?

I agree that an empty pub/css/ directory should be included in the distribution.

Hagan




More information about the pmwiki-users mailing list