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

[Oliver Betz]

John Rankin wrote:

>>BTW: Why do you change (slightly) the subject each posting? This
>>breaks thread view in my newsreader.
>
>I'm sorry about that; I receive a Digest and reply to that, so 
>copy the title from the digest into the subject line. I make 

I see.

>mistakes. If you cc me in your reply to the list, I can
>reply directly and this will retain the subject line.

I read the list vie NNTP (gmane gateway). Even if you would keep the
Subject, the new references qould probably break the thread, anyway.
We shouldn't bother.

[Creole as selectable standard markup]

>>Since there are only few entry points to the existing documentation
>>(e.g. EditQuickReference and the sidebar), an administrator could
>>simply replace these to Creole versions.
>
>I think it may be bigger than this. At least the following pages
>will need to be re-factored:
>
>- DocumentationIndex
>- TextFormattingRules
>- BasicEditing
>- EditQuickReference
>- MarkupMasterIndex

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.

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.

>>Maybe this could be even configurable. The i18n mechanism (XLPage)
>>could be also used.
>
>Sounds good to me.
>>
>>There should be an appropriate naming scheme for the Creole pages,
>>what about CreoleQuickReference? I don't think that it's worth another
>>group.
>
>Choosing the wrong names could cause confusion. We need to make sure
>we distinguish the Creole markup set as a structure for documentation
>from the Creole markup rules themselves. My inclination, I think,
>would be to reserve the word "Creole" for pages that refer to Creole
>markup rules. However, I strongly agree that as the documentation is
>being re-factored, we need an easy way to distinguish pages being
>worked on from the current stable versions.

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.

One of the first steps is to identificate the affected pages (see
"tree" above).

>One way would be to use a category: use [[!creole]] to refer to pages 
>structured around the Creole-based core markup set and use a Creole 

A Creole Category _could_ be useful to get a quick list of all
affected pages, but I think a simple full text searchis enough and we
don't need a new category.

>name prefix to refer to pages that describe Creole markup rules.
>However, then we couldn't use XLPage to switch. OTOH, I'm reluctant 

As far as I see, you need to switch only the entry points.

>to embark on a path that requires maintaining 2 sets of docuemntation.
>I would rather see one set, structured around a Creole core set. 

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

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.

Oliver