[pmwiki-users] Re-thinking Intro to markup pages

John Rankin john.rankin at affinity.co.nz
Thu Feb 19 21:08:44 CST 2009

>Date: Thu, 19 Feb 2009 20:57:42 -0500
>From: Sandy <sandy at onebit.ca>
>Subject: Re: [pmwiki-users] Re-thinking Intro to markup pages
>>> I really haven't understood why using the (:markup:) markup is so
>>> terrible.  Maybe I'm strange, but when I was first using PmWiki and
>>> reading the documentation, I was reading the documentation, not looking
>>> at the documentation source.  It didn't even occur to me to do so.
>>> Thus I consider it very unlikely that beginners will be confused by the
>>> (:markup:) markup.
>> In my view, the EditingForNewcomers page ought to work really
>> hard to demonstrate to newcomers not just "this is a good
>> starter markup set" but also "and this page is an example of
>> what you can do with it -- see how powerful this small set of
>> rules is."
>Aha! the point of difference. You expect newbies to see the source of 
>this page. That's probably how I learned about (:markup:) in the first 

Even if newcomers *don't* look at the page source, I think the
EditingForNewcomers page ought to send a strong message that the
newcomer set is sufficient to do really useful things.

Those who *do* inspect the page source ought not to be given the
impression that there are other things they need to learn, perhaps
before they feel comfortable.
>How long is the "creep list"? So far, only (:markup:) and (:include:) 
>are "advanced" codes that are tempting to use on this page.

And now (:title:). One of the reasons I suggested that the default
skin should use $Titlespaced is that it reduces the need for (:title:)
directives if one is running a plain PmWiki, as a newcomer may well do.
Or set SpaceWikiWords = 1 by default, so {$Title} is spaced.
>(:title:) is the solution to a very common problem for newbies, so 
>belongs on EditingForNewcomers. Even though I knew long page names 
>worked, it still went against early training, (and ease of typing links) 
>so I was stuck with short and uninformative page titles. And then we 
>have the time after making lots of links to the page, that I realized it 
>was a bad title.
>A few simple and useful directives show how easy it is to use the power, 
>especially when using only the basic set would be difficult.

Creole handles this with the concept of "Additions" -- they keep the
core set fixed, but identify optional additions.

My suggestion would be to create PmWikiCreole.DirectivesForNewcomers, 
referenced from EditingForNewcomers, which explains there are some rules 
that would have been very useful in making the newcomers page, but were 
deliberately excluded. This would introduce "one big new idea" of a 
directive, with examples. Those who are comfortable can look at it;
those who are not can continue to use the newcomer set, confident that
they will be able to do useful things.

I think the idea of a directive warrants a newcomers page to itself
and should not appear on EditingForNewcomers. So far, there are 3
examples proposed: (:markup:), (:include:) and (:title:). These are all
excellent! I suggest a limit of 7 examples (generally-accepted practice) 
for DirectivesForNewcomers.

If people support this proposal, I will make a page for comment.
However, I will not do anything while a number of people are expressing
a strong preference for using directives on EditingForNewcomers.

What do others think?
>Is monotype part of the Newbie set? If so, you could use that instead of 
>  (:markup:) to show the code and the results. It's not as convenient as 
>(:markup:), and the final page will have lots of duplicated source code, 
>but it's conceptually easy to understand.

Yes it is; see
This is how I built the newcomers page.

John Rankin
Affinity Limited
T 64 4 495 3737
F 64 4 473 7991
john.rankin at affinity.co.nz

More information about the pmwiki-users mailing list