[pmwiki-users] RFC: refactored introduction to wiki markup
John Rankin
john.rankin at affinity.co.nz
Wed May 10 17:27:29 CDT 2006
On Thursday, 11 May 2006 1:11 AM, Pico <pmwiki at ben-amotz.com> 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?
Potentially, yes. I chose "character markup" rather than "inline markup"
on the basis that those from a work processing background will be
familiar with the idea of "character styles" and so can perhaps relate
wiki markup to what they already know.
However, I think as long as the pages contain an explanation and are
cross-referenced, hafving a page called MarkupCharacters should be OK.
>
>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)?
It's so easy to refactor wiki pages, or add (:tile:) markup, and a list
of markup characters will be so useful, that I suggest you keep going.
>
>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
>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. <copied>
IMHO worse for newer readers. I chose the names so that they produce
readable sentences: "there is a choice of [[line markup]] to give
pages structure" -- in general, I prefer "natural" page names.
Sometimes, I write what I want to say first, then go back and put in the
links. That way the right names can emerge from the context.
>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. <copied>
Yes, IMHO it would be better to put all the pages in the [[!markup]]
category and use natural names.
>
>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)
FWIW I like IndexOfMarkupCharacters.
--
JR
--
John Rankin
More information about the pmwiki-users
mailing list