[pmwiki-users] User level for this forum? a cry for help (was Blogging support?)

[Patrick R. Michaud]

On Thu, Aug 17, 2006 at 05:43:57PM +1200, mike moller wrote:
>    Having said that there is a real gap for newcomers, especially if they are
>    having to climb a mixed learning curve of PmWiki, PHP and maybe a web
>    server as well. We all experience difficulties with the "how do I do ...?"
>    type questions when all that is needed is really a pretty trivial piece of
>    basis usage info. One really glaring problem is the absence of a few pages
>    of technical overview docs to relate the pieces of the jigsaw to each
>    other at a pretty elementary level. eg
>    a) the flow from pmwiki.php through the other distributed scripts?

I thought for certain that this information was in a page on pmwiki.org
somewhere, but now for the life of me I just cannot find it.  I know
it's been discussed on this mailing list in the past, but you're
correct that it needs to be made more prominent.  I'll try to find
it and re-post it soon.

>    b) how do the .tmpl files get into the act?
>    c) where do .css files fit in?
>    d) how do all the above come together to generate a page of html?

At the moment the docs for these are in 

    http://www.pmwiki.org/wiki/PmWiki/Skins
    http://www.pmwiki.org/wiki/PmWiki/SkinTemplates

but I admit they don't really answer the question of how it all works.
Essentially, a skin's template is loaded as part of the standard
configuration, and then when it's time to generate a page of html
the template is sent to the output with the skin directives
<!--HeaderText--> and <!--PageText--> replaced by the contents
of $HTMLHeaderFmt[] and the body of the page, respectively.

>    e) what are the opportunities for personalised mods/extensions?
>    f) how do these hang together with the standard distro bits?
>    h) custom markups?

These are generally handled by defining custom markup rules or
actions.  The documentation starts at 
http://www.pmwiki.org/wiki/PmWiki/LocalCustomizations and
http://www.pmwiki.org/wiki/PmWiki/CustomMarkup .

Some of the best examples of how to do things are in the scripts/
directory itself -- each file in scripts/ can be thought of as
a customization that adds another piece of functionality to PmWiki,
and is in general written that way.  (It's also written such that
someone could completely replace one of the components if desired.)

>    g) the roles and limitations of config.php?

Config.php is the administrator's primary hook into customizing
PmWiki, most things can be overridden or customized from here.
I'm not aware of many limitations to it -- it really depends on
what is meant by "limitation".

>    i) how to define variables and pass their values among the php scripts?
>    j) how to expose and test those same variables within wiki page markups?

Internally, PmWiki does most of its value passing via global variables
of one sort or another.  While I completely recognize that this is
frowned upon from a software maintenance perspective, from a
ease-of-configuration-and-understanding perspective it works well for
most administrators.  

To expose variables within wiki page markups, you'll probably want to
look at page variables (http://www.pmwiki.org/wiki/PmWiki/PageVariables),
especially the section called "Custom page variables".

>    Unfortunately the people who need this stuff haven't got the knowledge
>    (yet :-) to write it. For instance anything I might try to put together on
>    the basis of my present knowledge would likely be mistaken, confused and
>    incomplete.  ( strikeout likely and read certainly :-)

Yes, but an incorrect or incomplete description will tend to be
corrected much more quickly than trying to create a perfectly
correct one from scratch.  Even if we just had a good outline
of topics to cover (your list above is excellent, btw) then it'll
be easier to fill things in.

I remember that many devices in the past would come with "Theory of
Operation" documents that attempted to describe how the device was
put together.  Perhaps we could have a similar document for PmWiki,
or perhaps an "ArchitecturalRoadMap" of some sort in the Design
section.

Long-time community members can tell you that I tend to respond best
to things posed as questions (as demonstrated above), so just asking
questions and then using my responses to build up documentation pages
may be a good way to go.

Pm