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

John Rankin john.rankin at affinity.co.nz
Sun Feb 15 20:57:42 CST 2009


I have created a draft Creole-based introduction page at:
http://www.pmwiki.org/wiki/PmWikiCreole/EditingForNewcomers

May I make a few comments?

Choosing a suitable name was hard. Quite a few free software
projects offer a NewbieGuide page. I think "Newbie" is too
informal, but liked the idea of "something for newcomers".
The "something" could be "editing" or "text formatting".
I chose "editing" to refer to what the author does and
because it's shorter. More specifically, "editing" ties
to the "Edit" link on every page.

We may wish to consider enhancing the default pmwiki css:

- increase the contrast between !!, !!! and !!!; e.g. by
  applying a 1px border-top to !! or using different shades
  of dark grey

- adopt the widely-used design pattern that preformatted
  text is displayed inside a padded box with dotted border,
  often with a light grey background

It proved to be impossible to describe the Creole markup
set using only the Creole markup set. I stretched this
self-imposed rule and included the following:

- [[#anchor]] and [[#anchor | reference]] are covered in
  "Creole additions" [1] and are required to create a
  table of contents for the page

- including @@monospaced@@ markup was the only way I could
  find to represent preformatted text markup without using
  a (:markup:) directive:

[@
This text is preformatted.
@]

  However, this will not work correctly if the <pre> css
  suggestion is implemented. The other option was to use a
  zero width space character, but this is apparently not
  supported in all browsers. The problem is how to write:

[@
[@
This is preformatted text.
@]
@]

  and have it display as the example above.

I sometimes found myself wanting to follow the Creole 
documentation convention of putting examples on separate 
pages for each markup rule. 

The images section is blank at the moment.

The Creole documentation is inconsistent in a few places.
For example, table markup is included in the "elements"
but not in "all markup". I have included it with a note.
The rules are in a slightly different order in different 
places. I followed what seems to be the most widely-used.

JR
-- 
John Rankin
Affinity Limited
T 64 4 495 3737
F 64 4 473 7991
021 RANKIN
john.rankin at affinity.co.nz
www.affinity.co.nz

[1] http://www.wikicreole.org/wiki/Elements





More information about the pmwiki-users mailing list