[pmwiki-users] Delete EditGettingStarted, CharacterMarkup, LineMarkup (and more)?

john.rankin at affinity.co.nz john.rankin at affinity.co.nz
Wed Feb 11 01:23:04 CST 2009


> From: Oliver Betz <list_ob at gmx.net>
> Subject: Re: [pmwiki-users] Delete EditGettingStarted,
> 	CharacterMarkup,	LineMarkup (and more)? (Oliver Betz)
>
> [Creole as selectable standard markup]

This is *not* what I (and now a few others) are proposing. Let me
recap.

The EditGettingStarted, CharacterMarkup, LineMarkup (and more)
pages were an attempt to address the problem that PmWiki's
feature-rich markup set now presents a high barrier to entry for
new users, especially those who are non-technical.

You have convincingly argued that these pages are not really fit
for purpose and ought to be either re-written or deleted.

The proposal is that the Creole standard defines a core set of
wiki *functionality* regardless of the markup used. We should
therefore consider organising PmWiki's end-user documentation
around this core set. This does *not* require using Creole's
markup, although as Pm noted in a separate post, he may align
PmWiki markup with Creole markup in future.

A couple of examples will illustrate this idea.

1. TextFormattingRules

This might have 2 sections under the proposal:

- Basic PmWiki functionality
This would list the PmWiki markup rules covering the functionality
defined in the Creole standard. No more, no less.

- Advanced PmWiki functionality
This would list links to other pages for other PmWIki markup, i.e.
forming a mini documentation trail (or it could all be covered in
a single page).

2. EditQuickReference

This would summarise the PmWiki markup covering the functionality
defined in the Creole standard. I would be inclined to have a separate
AdvancedQuickReference page that can be optionally included, covering
some of the more advanced PmWiki markup.

I would also update the default set of GUI buttons to omit any
functions that are not part of the Creole standard and perhaps add
some which are part of the standard, but are at the moment disabled.


You can see that under this proposal, the documentation pages
would be extensively refactored, and potentially the entry points to
the documentation would also change.

This approach will also make it much easier for a site that wishes to
adopt the Creole *markup* to "flick a switch" and have everything
point to the Creole *markup* equivalents of the affected documentation
pages. As you point out, this should be possible with XLPage.

As Pm suggested, I am inclined to test this idea in a separate
PmWikiCreole group and re-create a core set of documentation
pages using the Creole functionality to distinguish "basic"
markup from "advanced" markup.

So I think I disagree with the rest of your post, because I disagree
with the core assumption that existing documentation pages are
largely unaffected.

>
> 1. IMO the relevant pages shouldn't be re-factored but there should be
> a second, parallel version for wikis using Creole as recommended
> markup. Therefore I would prefer to say "extending" instead of
> "refactoring". Only few pages will refer to both markup variants.

Disagree. However, I would test the proposal in a separate PmWikiCreole
group first.

See above. The proposal is to use the *functionality* that Creole
defines as the organising principle, regardless of whether a site
enables the Creole *markup*.
>
> 2. The pages you mentioned are _not_ the very basic entry points to
> the documentation tree. It's not even EditQuickReference as I wrote,
> it's the edit and upload form - usually Site.EditForm (but can be
> redefined in XLPage or preferences), and any sidebars, headers,
> footers etc. defined in the skin: Likely *.SideBar, maybe
> $DefaultGroup.$DefaultName, less likely header/footer pages.
>
> Before any change, you need to know the tree starting from these
> pages.
>
> To make maintenance easy, the two markup clusters shouldn't have too
> many links incoming and outgoing.

I agree that one needs to design entry points to the documentation
and that to some extent this will shape the documentation. However,
I also think one needs an organising principle for the documentation
itself and this will in turn affect the entry points one needs to provide.
>
>
> Again - there is not a lot to be refactored. Only a small fraction of
> the documentation pages are even affected from the default markup to
> be used. These pages have to be made new.

Disagree. See above.
>
> At least (!) for existing wikis, you need the same structure as now.

Disagree. See above.
>
> Look at the internationalizations. A lot of the problems to maintain
> localized versions of the documentation are identical to the task to
> include two sets of markup.

Agree. If PmWiki's documentation pages are organised as proposed
above, all the documentation pages that are affected by a switch to
Creole *markup* will be fully isolated, because the pages are
organised around Creole's *functionality*. So switching on Creole
*markup* can switch documentation really easily. For example:

BasicFunctionality   --> BasicFunctionalityCreole
EditQuickReference --> EditQuickReferenceCreole

These pages describe *exactly* same functionality, using different
markup rules.

I hope this long post makes the proposal clearer.

I have no opinion about the suitability or otherwise of the Creole
standard. The important thing is that it is a standard, so adopting
it to define the core *functionality* provides an easy way in for new
PmWiki users.

JR






More information about the pmwiki-users mailing list