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

[Pico]

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 
MarkupCharacter?

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
http://www.pmwiki.org/wiki/PmWiki/DocumentationGuidelines-Comments
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)

Pico