The Long Version

What it is

This recipe provides two things:

• A set of scripts which convert HTML written on an edit page into PmWiki markup.
• A wrapper which allows the TinyMCE rich text editor (or, with minimal effort, another editor) to appear on PmWiki edit pages.

Together, these scripts allow users to choose between the original PmWiki editing interface and a new, word processor-style editing interface.

Goals

My goals were:

• To provide a word processor-like interface for editing PmWiki documents.
• To provide a quality mechanism for pasting from desktop word processors.
• To continue permitting the use of the plain text editor and conventional PmWiki markup.

To get there, I built a more sophisticated and, hopefully, user-friendly document editor for PmWiki.

I specifically was not attempting to provide a complete replacement for PmWiki's plain text editor, which remains the solution of choice for administrator tasks such as writing markup documentation or producing very sophisticated pages.

Backwards-compatibility was the most challenging goal; if I had decided that wikis using this recipe must use a subset of HTML, the task and code would have been much simpler.

Audiences

My primary audience was the dozen or so people who contribute to my own wiki. These are people who are often adapting their own content from other sources, such as word processing documents. The secondary audience was people who read my wiki, but don't contribute because the markup is confusing or annoying.

Both of these audiences are most concerned with easy document creation and editing.

Design

The design is fairly simple, and has two parts:

1. PHP scripts that enable PmWiki to output HTML for editing and then to convert that HTML back on save. This is the bulk of the recipe.
2. PHP and JavaScripts that replace PmWiki's editing textarea with a rich text editor when the edit page is loaded. Beyond asking these scripts for information to add to the HTML header, the scripts in 1 have no knowledge of these scripts. In theory, it should be fairly simple to replace the included TinyMCE editor with any other rich text editor.

The Included Editor- TinyMCE

TinyMCE 2.0RC1 is included with this recipe. The following modifications have been made to the distribution found in the cookbook/richedit/tinymce directory:

• A popup window for adding links within the wiki has been added in the directory cookbook/richedit/tinymce/jscripts/tiny_mce/plugins/wikilinker . This plugin is loaded by default in the cookbook/richedit/tinymce_config.js script.

Bugs

Paste

The paste feature, while very useful, has some bugs which I haven't been able to correct. Some of these are artifacts of the convoluted HTML that Word and OpenOffice.org tend to output. Others have to do with the relative naievete of my HTML->WikiStyle conversion.

TinyMCE Bugs

Since we use the TinyMCE control, we're stuck with TinyMCE bugs. Fortunately, however, these aren't exceedingly numerous or annoying.

WikiStyles

I've done my best to troubleshoot WikiStyles, but I sometimes they won't display correctly in the editor. They should save correctly, however, even when they won't display.

Limitations

Although the rich text editor is very handy for editing articles, it has some limitations, particularly from the standpoint of Administrator tasks.

Although this list looks scary-long, that's mainly because I'm trying to be very specific.

Things It's Not Good For

These are things you should probably use the plain text editor for.

• Editing markup documentation. The limitations on handling [= =] markup (described in Design Problems) make this awkward.
• Editing pages with fancy wikistyles or similar. If you're spending a lot of time using PmWiki's markup as a presentation language, the editor scripts probably won't fit your needs.

Incompatible Text Formatting Rules

I made great efforts to stay compatible with existing markup, but some Text Formatting Rules had to be bent.

• Multiple newlines with no text between them may be removed. To create the same effect, use the plaintext editor and insert \\ or [[<<]] markup.
• The use of whitespace at the beginning of lines to indicate preformatted text was simply impractical to maintain (see Design Problems). The rich text editor strips beginning-of-line whitespace. Further, when using the RichEdit recipe, significant-whitespace markup is disabled.

Recipe Incompatibilities

Recipes which change link output

The rich text editor is likely to mangle links from any recipe which changes PmWiki's link handling or formatting. Also, although I haven't tested this, it's likely to mangle Url Approvals.

BreakPage and SectionPage

This recipe is incompatible with the SectionPage or BreakPage recipes, because of the ways they use a modified version of the HandleEdit() function.

However, a modified version of SectionPage has been integrated into this recipe. It supports the same configuration options as the original recipe, and is enabled by default. Located in cookbook/richedit/sectionpages.php, it integrates the sectioning and recombining of pages into $EditFunctions.

Design Limitations

These are issues that are obvious problems with or limitations of the algorithms I picked.

• In the rich text editor, editing and saving Directives or Page Variables inside [= =] markup results in new markup being saved around the directive. This is because the simple replacement algorithm used in RichEdit_BoxMarkup() has no way of knowing whether text is inside [= =] or not.
• Leading spaces are stripped from the beginnings of lines when saved in the rich text editor. This is deliberate, as both IE and Firefox produce extraneous whitespace which can trigger preformatting inappropriately.
• Page variables inside links are made literal on save.
• Relative (groupless) wikilinks are made absolute on save.
• Nesting of style attributes (often present in pasted HTML) doesn't work very well. This is pretty much because WikiStyles, like other PmWiki markup, don't nest. A token effort has been made at preserving them, but I didn't consider this a high priority. A real solution would be, I think, as tough as getting WikiStyles to nest in PmWiki itself.
• Even style values that do not have WikiStyle equivalents will be transformed into WikiStyles when first saved. This is to maintain forwards-compatibility with the ever-expanding variety of effects permitted by WikiStyles.

Code Quality

I had a relatively small quantity of time to do this in, and it involved two languages I haven't worked in extensively: PHP and Perl. My Perl skills, particularly, are very weak. As a result, I know there are some ugly hacks in there, and I'm sure I've been naïve or reinvented the wheel in a few places. There's also a lot of code prettification to be done; the code I was integrating came in a lot of different styles, so I mostly stuck to my own preferences.

Contributions, criticisms, and cleanups would be very welcome.

Contributors

• Russell Bailey: The “me” of this document, Russell searched out, picked, and glued together the software needed to create the rich text editor. His work consisted primarily of substantially extending the HTML->Wiki converter and writing a lot of wrapper and postprocessing code for PmWiki.
• David Diberri: David wrote the original Perl HTML2Wiki script(sitios aprobados) and PmWiki dialect. This work saved Russell weeks of time and hair-tearing.
• The Xinha and HTMLArea teams: The original editor supported by this recipe was Xinha(sitios aprobados) , a descendent of HTMLArea(sitios aprobados) . Xinha is a big project and a huge achievement, and these folks deserve some accolades.
• The TinyMCE team: After working with Xinha for several weeks, I decided to switch to TinyMCE as my own editor of choice. The recipe can be configured to use either one.