> From: Oliver Betz <[email protected]> > 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 _______________________________________________ pmwiki-users mailing list [email protected] http://www.pmichaud.com/mailman/listinfo/pmwiki-users
