[Pmwiki-users] Thoughts about good markup (was: Suggestions for [[<<]] replacement)

Patrick R. Michaud pmichaud
Mon Jan 5 08:25:19 CST 2004


Here's the criteria I generally use for choosing markup...

1.  If there's a "natural" markup, then use that.  Examples of natural
markup sequences include:
    a.  Blank lines to separate paragraphs
    b.  '*' at the beginning of a line for bullet lists
    c.  '||' to represent column lines in a table
    d.  table cell justification:  
        ||left-justified  ||  centered  ||  right-justified||
    etc.

2.  If there's not a natural markup, then something more visible has
to be chosen.  It should be
    a.  Easy to type (relative to frequency of use)
    b.  Easy to read -- i.e., it should minimally interrupt the "flow" 
        of the surrounding text
    c.  Unlikely to occur in normal text
    d.  Not lead to ambiguous/surprising output

This helps explain why I avoid HTML as an authoring language:
There's very little that is "natural" about writing HTML, except maybe
for programmers, and although HTML excels at #2c and #2d above, it
fails miserably at #2a and #2b.  As an example, I find that ''italic''
and '''bold''' are much easier to read or write than <i>italic</i> and 
<b>bold</b>, and clearly '''http://www.pmichaud.com''' is superior to
<b><a href='http://www.pmichaud.com'>http://www.pmichaud.com</a></b>.  :-)

#2c and #2d are also why I've rejected wiki markup such as *bold*
and /italic/, although local customizations can be created to enable them.
See the discussion thread beginning at 
http://pmichaud.com/pipermail/pmwiki-users_pmichaud.com/2003-August/001282.html
for more details (and this should probably go into a wiki page somewhere).

Also, people may want to take a look at 
http://pmichaud.com/pipermail/pmwiki-users_pmichaud.com/2003-August/001084.html
for more of my musings on wiki markups in general.

On Mon, Jan 05, 2004 at 04:30:41AM +0100, Christian Ridderstr?m wrote:
> Speaking of the normal users... is PmWiki primarily intendend for
> e.g. American English? E.g. the use of a colon might differ (I've no idea)
> in German or French etc. If so, I don't know how much we can rely on
> 'details' of how a language works?

A good point, and thanks for bringing this up.  I've never intended that 
PmWiki should be limited or primarily targeted to American English audiences, 
and I've always tried to keep the needs of international audiences in mind 
when designing things.  After all, it is the "world" wide web.  :-)
Unfortunately my experience in such areas is sometimes a bit limited, 
such as knowing other keyboard layouts / keystroke combinations and conventions.
Still, I'd prefer to keep PmWiki's reach as global as we can, consistent 
with the other PmWiki Philosophies... :-)

Pm



More information about the pmwiki-users mailing list