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

[john.rankin at affinity.co.nz]

> 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."

On the other hand, if the page uses markup from outside the
newcomer set, first (:markup:) and now possibly (:include:),
the page is sending a subtle message that "of course, to do
anything useful, you are going to have to learn more".  It is
undesirable (and incorrect) to imply that the newcomer set
is not enough to do anything useful.

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".

What I found in writing the page is that the newcomer set is
really good for *structuring* the content (which I believe was
one of the Creole design goals), but the default PmWiki css
file does not provide sufficient contrast between the elements,
so the structure gets a bit lost in the presentation. The solution,
in my view, is to enhance the css, not use additional markup to
increase the contrast.

I understand and support the reasons for keeping the default
PmWiki css as light as possible, but wonder if it may be time to
revisit this. So before introducing non-newcomer markup to
describe the newcomer markup set, I would like to see if we
can improve the page by improving the css.

I have another question: should ! for a heading 1 be included?
I left it out; Peter added it. There are arguments for and against.
What led me to leave it out is that there is no gui button for h1.

JR