[pmwiki] Re: [Pmwiki-users] Whitepaper about markup strategy

[Patrick R. Michaud]

All-

I have literally *dozens* of responses to the many ideas that are
being generated, and I'm greatly enjoying the discussion.  As the 
creator and current "PmWiki master" I'm a little reluctant to respond 
to everything because I don't want to intimidate others from
expressing their opinions and perhaps contributing an idea I wouldn't
have thought of.  So, unless I hear a clamor for great detail I'm going
to restrain many of my comments for a while.

That said, I do think I should give some indication of my thinking on
where this all might be headed, so that people aren't concerned that
the PmWiki-world is about to undergo a major shift.

First, while PmWiki's current markup may seem somewhat "ad-hoc" or "fuzzy",
it's not as if I made it up out of thin air.  Most of the markup comes from
"The Wiki Way" by Leuf and Cunningham, and if nothing else it does have
the advantage of having been shown to be viable (almost a decade of wikis)
where many alternatives have not.  So, I don't have any plans to make 
substantial changes to PmWiki's basic markup anytime soon.

Second, while structured markup is good, most (non-technical) authors do 
not write in a structured manner.  For such an author to be comfortable 
with editing a page, the markup has to look something like the page itself.  
And somehow I have trouble seeing that

	.b_list bullet="#"
	.b_item
	this is my list item

	it can comprise of multiple paragraphs
	
	.e_item
	.b_item
	and this is the second item

	.e_list

looks anything like what would actually be output.  

Third, as I often tell others, I fairly strongly reject the claim that 
"authors don't have to use the advanced markup if they don't want to".
I don't think that's true in a collaborative environment.  If complicated 
markup is available, someone will find it and use it, and if one author
uses it, then all subsequent authors must be able to understand it, or at
least not be frightened by it when they encounter it.  So, from a 
general PmWiki perspective, complex markup sequences are something to 
be avoided entirely, except for very specific applications and audiences 
where they are needed (and in these cases they should be local customizations, 
but not part of PmWiki).  Janice makes this point very well when she says:

JH> If my users were forced to learn complex code, I'd
JH> *still* be doing the website all by my lonesome.  :-(

I'm also having some problem seeing how the proposed markup is any
different from (or better than) XML or HTML itself.  I.e., I don't 
quite see how the .b_list ... .e_list markup above is substantially 
different from:

	<ol>
	<li>
	this is my list item

	it can comprise of multiple paragraphs
	
	</li>
	<li>
	and this is the second item

	</li>
	</ol>

Maybe I'm just missing the point.  But if we're willing to allow things
like [.b_name]...[.e_name] in the markup, then why bother with a whole
new markup syntax?  Let's just use XML/HTML directly and say <name>...</name>.

Finally, to directly respond to one of the excellent questions that
Janice posed...

BW> Yes, so it should be /italic/ *bold* _underline_ */bolditalic/*

JH> I think you raise a good point, and I concur. Your suggestion would make
JH> formatting easier to remember. In addition, this is markup that many people
JH> use for emphasis in text-only emails. 
JH> Question for PM: would it cause problems with the * used for lists?

The problem with /italic/ and *bold*, and which must be remembered in 
defining any sort of markup sequence, is that markup sequences have to be 
things that aren't likely to occur in "normal" text.  For example, if I 
write 

	On 05/20/2003 we are going to the beach, on 05/21 we will be
	flying first to Dallas / Ft. Worth International Airport and then
	landing at Seattle/Tacoma airport.  

then what should be italicized?  A naive parsing would italicize "20" and
"21 we will be flying first to Dallas" and lose the slashes, which is
obviously wrong.  We could try a rule like "slash means italics except 
when it appears in the middle of two words", but that's really 
non-intuitive and generates all sorts of surprises for authors 
("...why didn't my slashes make italics?").  I can come up with 
similar examples for using inlined asterisks as markup.

The nice thing about the '' and ''' markup is that they are fairly
unobtrusive when reading the markup text (unlike <b>...</b> and <i>...</i>,
which make it hard to read) and the quote sequences don't occur in 
normal text so they're fairly unambiguous about what is intended.  

Of course, PmWiki makes it easy for someone to introduce *bold*, /italic/,
_underline_ into the markup if desired, and I'll even include it as
an optional module in the distribution if people want.  But because 
of the potential for surprises and problems like the ones I described 
above I don't want it to become a PmWiki-default (once it's available
as a default it'll get used, and once used everyone's stuck with it).

BW> !Headline1 would IMHO be easier to recognize as
BW> .H1 headline1

JH> IMHO, I disagree. The current markup means fewer keystrokes, until you get
JH> to H5. I don't know about everyone else, but I rarely get that far. The
JH> exclamation mark makes sense to me for something you want to "exclaim."
JH> (Bad, bad pun, I know. And I'm just referring to the use of the !, as the
JH> logic of my extremely bad pun would follow that H1 should have more !!!!!!
JH> Than H6.)

This is another case where I chose ! !! !!! based on "The Wiki Way",
which also discussed the concept that H1 should have more !!!!! :-)

As I indicated at the beginning of this message, I can go for quite a 
while on these topics, and I'll be happy to do so (perhaps in a wiki page
instead of email) if others express an interest in hearing it.
Ultimately I'm fairly happy with PmWiki's current markup, and 
it really does have the advantage of a proven history from other
wiki engines.  However, I also recognize some of Bernhard's comments
about difficulty with adding new structural markup sequences to PmWiki,
and I'm quite willing to make changes to pmwiki.php to facilitate
the addition of such sequences, even if I don't plan to use any of them
in PmWiki's "default" configuration.

Pm