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

Pico pmwiki at ben-amotz.com
Wed May 10 08:40:21 CDT 2006


Pico wrote:
> 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

Ok, before you say anything, I just got it: everything is markup.  Run 
with my suggestion and every page could start with MarkupTables, 
MarkupTrails, etc.  In fact, the page called MarkupHandling is 
redirected to CustomMarkup.

> 
> 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)
> 

Or not.  Pages should be clustered by their subject matter, e.g. 
pagelists, tables, etc, not by their organizational scope or format, 
e.g. index.  Note, however, that we still have some pages organized by 
their audience or levels, e.g. basic editing, basic variables, which had 
made me think that perhaps John's pages should be similarly organized as 
Basic..., or Introduction...  But that clustering can be done elsewhere, 
by categories or documentation index pages.

Pico




More information about the pmwiki-users mailing list