[Pmwiki-users] suggestions for the new documentation structure

[Robert P. J. Day]

  now that i'm up and running with pmwiki 2, i noticed that the
documentation pages are still a work in progress, so i thought i'd
make some suggestions.  (basically, i was also about to post a lengthy
diatribe against the current configuration file setup, so i thought
i'd lead into that by first contributing something useful. :-)

  when i was reading the docs pages out of pmwiki 1, it seemed that
the pages were in a fairly erratic order, which had closely-related
topics spread across more than one page at times, and forced me to do
a fair bit of jumping around.  to make it easier for me, i just
started a file in emacs "outline" mode to represent what i thought
would be a more logical ordering of topics -- more of a
simple-to-complex, top-down approach.  here's what i have so far (in
emacs outline mode, as i said, and some of what's here is clearly for
my benefit alone):

* pmwiki
** Overview
*** What's a wiki, anyway?
*** The PmWiki philosophy
*** The intended audience
*** Support
- mailing lists(s)
- FAQ
- others??
*** Contributors
** Basic installation
- give root priv:
  - unload pmwiki tarball into /var/www/html (ideally), rename to pmwiki/
  - chmod 2777 pmwiki, just long enough to browse once to create wiki.d/
  - chmod 755 pmwiki afterwards
  - get to work
** The PmWiki files
*** The directory hierarchy
short explanation about the following, and their functions:
pmwiki/
  pmwiki.php	(top-level PHP file)
  scripts/	(lower-level PHP programs)
  local/	(for local files and scripts, initially empty)
    config.php  (personal, based on sample-config.php)
  pub/
    css/	(generic .css files)
    skins/	(layout templates)
  wikilib.d/	(some default pmwiki files)
  wiki.d/	(generated content, initially empty, format of pages)
*** What's a wiki page?
  - initial wiki pages in wikilib.d/
  - additional pages you create in wiki.d/
  - file format and name format, all in one flat directory,
    that's how you link
  - mention group idea here *briefly*
*** The basic configuration files
  - simple list of top-down config files
** Starting a new page
** Introductory text formatting
*** Headings and separators
*** Comments
*** Paragraphs
*** Emphasis
*** References and links
*** Escape sequences
*** Lists
**** Bulleted lists
**** Numbered lists
**** Definition lists
*** Tables
*** Colors and styles
*** Special characters
** Special markup

... from here down, i'm still working on this stuff ...

** Groups
** The customization process in detail
- lots of subsections about how to customize, including per-page,
  per-group, headers/footers, etc, etc.
** Wiki security
** Common cookbook features
*** Live sidebar, etc.


obviously, a fair bit of stuff is missing, but the above seems to
represent what the vast majority of users would want to see fairly
quickly.

  thoughts?

rday