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

[Sandy]

john.rankin at affinity.co.nz wrote:
>> 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 
place.

I know when editing a page's formatting, it's a pain to find the same 
place in the source and browse, so doing that for the bulk of initial 
learning would be offputting.

I'm tired tonight -- I think I've made the same points in more than one 
post. Please reduce the overkill as you read.

Would the "example of small powerful set" work better in the sandbox 
default page than EditingForNewcomers?

> Yes, it is a challenge to make a good page using just the
> newcomer set, but that is no reason not to try. So rather than
> "It didn't even occur to me to do so", the EditingForNewcomers
> ought to make it really clear that the reader can "see what this
> markup can do".

How long is the "creep list"? So far, only (:markup:) and (:include:) 
are "advanced" codes that are tempting to use on this page.

(: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.

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.


Sandy