Home   Info   DevZone   Wiki   UsersWeb  |  MainWeb  |  InfoWeb  |  DevZoneWeb  |  SupportWeb
[ NewFormattingRules ] [ not logged in ] [ Web: Main ] goto:  options [ get info on or edit ] [ login or new user ] [ list of topics, hubs & nodes, or recent changes ]

Well, you might want to begin your reading with sfWikiProblems. Or the JOS-general mailing list archives: http://www.geocrawler.com/lists/3/SourceForge/6687/0/.

With all that being said, I'll quote JamesFrasche, who summed things up well:

After playing with sfWiki a little bit and investigating the issues of the debate, I'm undecided.

The points seem to be:

• Why should the Wiki support HTML? It's ludicrous!

Note that the second con for the `pure' Wiki has been addressed. With all the `old wiki' pages in the Imported web, where HTML is passed through unadulterated, the `old wiki' pages render properly. The current set-up -- to which responses seem positive -- is to forbid editing of any kind in the Imported web. This produces two benefits: the division between old and new pages is made readily apparent (old pages are restricted to the Imported web), and it maintains the advantages of the `pure Wiki' approach for new, or newly edited, pages. It does, however, retain the disadvantage of not allowing some potentially useful forms of markup. However, I hope that this disadvantage can be addressed with an improved WikiFormat, which I propose below.

- ToddMiller ( 27 April 2001 )

NewFormattingRules

I think it's worth mentioning the goals in designing NewFormattingRules. First, I want to design a WikiMarkup so that it can be nested; that you can put tables inside other tables, multiple paragraphs within list items, list items and paragraphs within table cells, and the like. Second, I want to design a WikiMarkup which cleanly handles code and markup examples. Third, I want to eliminate the counter-intuitive behavior that comes from the regular expressions currently used to recognize the markup conflicting with each other. I've been trying for several months to squash all the bugs, but I am not sanguine about it being possible. Finally, it's important that the markup NOT become another fooML; simplicity in editing, as exemplified by the ASCII markup found in e-mail, is a design requirement.

This immediately leads to requiring the WikiRenderer to insert paragraph tags in the right place, recognizing paragraphs by the blank line separating them. Multiple blank lines should result in larger separation between parapraphs. The markup must conflict as little as possible with normal text; whenever it does, there must be a simple and consistent way of preventing it from doing so. I propose that no markup be recognized if prefixed with a back-slash, `'; `\' would escape backslash, if it's necessary to prefix markup with a backslash. That is, the backslash would escape something if and only if it would otherwise be valid WikiMarkup.

Code examples, on their own, raise several interesting issues. If you're coding in in a markup language, you'd want the WikiRenderer to convert <TAG> into &lt;TAG&gt; but you may also want to emphasize a portion of the code -- and if you're coding in C, using underscores for emphasis may well be ABADIDEA. (That is, A _ BAD _ IDEA, without the spaces. So you can see that why a new WikiMarkup might be a good idea!) So we have several questions to address: should the enclosed text be touched at all by the WikiRenderer? (e.g. [literal][/literal]) This is good, because You Get What You Type. This is bad, because YGWYT: <NOTHTML> will be suppressed, <SCRIPT="denial-of-source.js"> will work; et al. So [literal][/literal], or its equivalent, should turn off WikiMarkup but not tag conversion. (That is, <TAG> will be rendered as &lt;TAG&gt, and & as &amp;.) There is, however, an option which may be orthogonal: the PRE-formatted text HTML tag. That is, for code examples, you don't want

Some
 nicely
 indented code

turned into:

Some nicely indented code.

So we have a matrix of options: WikiMarkup on/off, PREformatted text on/off, tag-conversion on/off. Turning tag conversion off is, I think, a Bad Move -- it allows for arbitrary HTML (see above.) WikiMarkup is on by default, so we have three tags: WikiMarkup on, and PREformatted text on or off; and PREformatted text on or off. How about:

<literal></literal>	WikiMarkup off, PRE off
<code><code>	WikiMarkup off, PRE on
<pre><pre>	WikiMarkup on, PRE on

?

Nesting markup and preventing counter-intuitive rendering are, I think, closely related. If the markup nests cleanly, it will be harder for it to produce counter-intuitive results. Clearly, 4 * 5 * 6 should not bold 5; * word * (word) and * word word word * (word word word) -- eliminating the trailing and leading spaces -- should both be bolded. This aspect of intuitive markup will only be solved by properly restricting the contexts in which * is converted to (or ). I propose a spanning markup, which groups text for the WikiRenderer. By implementing this, we can restrict the non-spanned markup to the minimum that can be cleanly supported. In general, enclosing text in curly braces -- { text } -- forces the WikiRenderer to treat that text as a unit -- one which may have sub-units -- for the purposes of markup. *{ 4 * 5 * 6 * 7 = 840 } would bold that whole equation. (This won't conflict with code, because code can be enclosed in <code> tags.) A list item could contain whatever it wanted:

#{ | This | is a | table | in a list item |
   | which extends | over several lines |

 And has a paragraph attatched to it.
}

The same scheme would allow tables to be nested.

Unless I can come with a good reason, I don't see any reason not to carry forward the current markup. If it causes problems, we'll think of something. :) I'd also like to add some markup. (Incidentally, the WikiFormat page should only describe the most recent iteraration of the WikiMarkup/WikiFormatting.) I think /that/ should have been emphasized; GCHII wants, and I can't think of a reason to refuse him, the following markups, where ^ indicates beginning of line, and ... one or more of the preceding:

^*... item	unordered (bullet) list
^#... item	ordered (numbered) list
^:... term:definition:	definition list
^!... header	headers from H1 to H4

I'd also like to see [[citation-style]] links, which go from written-out URLs to [some number] links.

-- ToddMiller ( 17 June, 2001 )

The sfWiki team is not the first to face the markup dilemma. It might be appropriate to take a good look at The Wiki Way, a new book by Bo Leuf and Ward Cunningham, published by Addison-Wesley. It explains the original mark up for wiki text, including emphasis, strength and headings. It also suggests a basic renderer should not allow HTML tags and, if necessary, a custom renderer should allow tags explicitly on a tag-by-tag basis.

• Instead of [three spaces]* or [tab]* to indicate level one un-ordered list, it uses '*'.
• Instead of [six spaces]* or [tab][tab]* to indicate level two un-ordered list, it uses '**'.
• Instead of a pair of underscores (_) to indicate emphasis, it uses a pair of double single quotes (''sometext'').
• And instead of a pair of asterisks (*) to indicate strength, it uses a pair of trible single quotes ('''sometext''').
• Instead of <H2></H2> to indicate a level two heading, it uses two exclamation marks (!!sometext).
• Instead of <H3></H3> to indicate a level three heading, it uses three exclamation marks (!!!sometext).
• And instead of <H4></H4> to indicate a level four heading, it uses four exclamation marks (!!!!sometext).

I just bought The Wiki Way; an interesting book. I didn't find as much discussion of the philosophy of the WikiWay as I had hoped for, though I may just have read it too quickly. I rewrote the proposal above; comments are welcome.

-- ToddMiller ( 17 June 2001 )

Content of these pages are owned and copyrighted by the poster.
Hosted by: