[pmwiki-users] RFC: refactored introduction to wiki markup

Pico pmwiki at ben-amotz.com
Wed May 10 08:11:28 CDT 2006

John Rankin wrote:
> This proposal is to alter the way PmWiki markup documentation 
> is organised, to make it easier for those new to PmWiki to 
> understand how to use PmWiki markup.
[snip throughout]
> The pages are: 
> - http://www.pmwiki.org/wiki/PmWiki/EditGettingStarted
> - http://www.pmwiki.org/wiki/PmWiki/CharacterMarkup
> - http://www.pmwiki.org/wiki/PmWiki/LineMarkup
> - http://www.pmwiki.org/wiki/PmWiki/LinkMarkup
> - http://www.pmwiki.org/wiki/PmWiki/BlockMarkup
> One thing I would like to propose is to restructure
> the TextFormattingRules under major headings Character,
> Line, Link and Block markup. Would that be useful?

A couple of comments about the page names, particularly as they relate 
to a proposed documentation page I am working on, which I initially 
called MarkupCharacters (an index style documentation organized by 
individual markup characters, ~ ! @ # etc)

1. Is it confusing to have two pages with the names CharacterMarkup and 

2. Setting aside the issue of what the page I am working on should be 
called, should I hold off on referencing to the pages that John drafted 
(in case the names are subject to change or reorganization)?

3. Would it be better, or worse, if names were structured to appear 
closer to eachother in alphabetical listings, for example:

BlockMarkup      => MarkupBlocks
CharacterMarkup  => MarkupCharacter
LineMarkup       => MarkupLine
LinkMarkup       => MarkupLink

I note that John has been a proponent of similar views in the past, see
and this view seems to be reflected in the way that documentation for 
tables has eveloved:

AdvancedTables  => TableDirectives
SimpleTables    => Tables

4. Is there a better name for the draft page I am working on (an index 
of markup characters), like MarkupCharacterIndex, or 
IndexOfMarkupCharacters, or...  (Which suggests whether index pages 
should be clustered by names)


More information about the pmwiki-users mailing list