[Pmwiki-users] notes on pmwiki documentation
Patrick R. Michaud
pmichaud at sci.tamucc.edu
Fri Feb 28 15:49:41 CST 2003
Following up on the previous messages, I've decided to just
write down a list of standard pages that I think ought to be
provided with the basic PmWiki distribution, but without
displaying the group memberships. Perhaps this will make
a useful organization scheme more obvious. The [...]'s
on some items below indicate that the word might or might not
be part of the title.
WikiWord
WikiWikiWeb
WikiSandbox
TextFormattingRules
WikiGroups
WikiStyles
[PmWiki]WikiStylesAdmin
WikiTrails
FreeLinks
EditQuickReference (appears at bottom of Edit Page)
QuickReference
InterMap
WikiHelp
SearchWiki
HomePage
[PmWiki]Configuration[Guide] or [PmWiki]Setup[Guide]
[PmWiki]BasicConfiguration[Guide] (?)
[PmWiki]AdvancedConfiguration[Guide] (?)
[PmWiki]Installation[Guide] or [PmWiki]Install[Guide]
[PmWiki]Variables (documents variables avaible for use)
[PmWiki]Upgrades (how to do upgrades)
[PmWiki]Philosophy
[PmWiki]Passwords or [PmWiki]PasswordGuide
WikiGroupsHowTo
[PmWiki]Files or [PmWiki]FilesOrganization
[PmWiki]ReleaseNotes
[PmWiki]ChangeLog
PmWiki
[PmWiki]Scripts or [PmWiki]Modules
WikiReferences (references to other WikiWikiWeb resources)
[PmWiki]AddingCustomMarkup
One could also replace "Guide" with "HowTo" in each of the above cases
and perhaps that would be more self-explanatory (e.g.,
PmWikiConfigurationHowTo).
I can't figure out where to include things like making backups and
restores, installing PmWiki outside of the public_html space, suggesting
PmWiki improvements, etc. I'm not sure if these topics should be separate
pages or if they should be included as part of other pages. Especially
for guide documents, I like to have all of the steps available on
a single page that can be printed out, and not have to browse through
multiple pages.
Any further comments or ideas greatly appreciated.
Pm
On Fri, 28 Feb 2003, Patrick R. Michaud wrote:
> On 1 Mar 2003, John Rankin wrote:
>
> > Although most pagenames are {{free link}}s, Group/[[$Title]] works everywhere because we have redefined the $PageNamePattern. We have *not* changed $WikiWordPattern.
>
>
> > Also, it might be useful to come up with some consistent naming choices
> > about when to include "PmWiki" in the document. For example, I've documented
> > some features like "PmWikiConfiguration" and "PmWikiPasswords", while other
> > features do not contain PmWiki in the title, as in WikiStyles, WikiTrails,
> > InterMap, etc.
> > --
> > Why do terms need PmWiki in the title? What is wrong with just {{configuration}} and {{password}}s? And is there a convention for favouring singular or plural page names?
>
> Well, if the pages are in the PmWiki group, we probably don't need
> PmWiki in the title. I.e., a page named "PmWiki.Configuration" works
> for me. But if the pages go in another group, such as Main, then I
> think that PmWiki belongs in the title to denote that we're talking about
> configuring PmWiki as opposed to some other component (i.e.,
> "Main.PmWikiConfiguration").
>
> It still leaves me with the question of where pages should go, while
> "PmWiki.Configuration" clearly makes sense to me, "PmWiki.WikiWord"
> seems wrong because it's a definition that isn't specific to just PmWiki.
> And "PmWiki.WikiGroup" is uncertain--it has clear connections as a
> definition but it's also fairly specific to PmWiki.
>
> Also, I've thought a bit about whether authors should favor singular or
> plural page names, and I haven't come up with a good answer. Part
> of me wants to use whichever version is more likely to appear in text,
> thus do "WikiStyles" and "WikiWord" as page names, and then use
> {{WikiStyle|s}} and {{WikiWord}}s when the opposite sense is needed. The
> downside to this is that one has to remember which pages are named by
> plurals and which are named by singulars, which argues for
> consistently using one or the other in all names. (Not that this will
> happen anyway.) So, I dunno.
>
> Pm
>
>
> _______________________________________________
> Pmwiki-users mailing list
> Pmwiki-users at pmichaud.com
> http://pmichaud.com/mailman/listinfo/pmwiki-users_pmichaud.com
>
More information about the pmwiki-users
mailing list