README Table of Contents 1. INSTALLATION a. FIRST-TIME INSTALLATION b. SUBSEQUENT OR MANUAL INSTALLATION c. A COMPLETELY MANUAL INSTALL 2. SPACE-BAR POSITIONING 3. INSERTING AND UPLOADING IMAGES 4. MEDIA MANAGER IN MULTIPLE DOKUWIKI INSTALLATIONS 5. FCKEDITOR TOOLBAR DokuWikiFCK Tools and Toolbar Extensions 6. LOCK TIME OUT AND AUTO-DRAFT SYSTEM 7. SUPPORT FOR LARGE FILES 8. BACKUPS OF FCK FILES WHEN SWITCHING TO NATIVE DOKUWIKI EDITOR 1. INSTALLATION HTML::WikiConverter::DokuWikiFCK This package includes DokuWikiFCK.pm, a perl extension to DokuWik.pm and fckg, a plugin which supports the new syntax created by DokuWikiFCK.pm. a. FIRST-TIME INSTALLATION A first-time installation is best done using CPAN: perl -MCPAN -e 'install HTML::WikiConverter::DokuWikiFCK' This will install all of the Perl dependencies you need as well as the fckg DokuWiki plugin. Please Note: You should be prepared to provide the installer with the full path to your DokuWiki plugins, for instance: /var/www/html/dokuwiki/lib/plugins The fckg plugin will then be installed in your plugins directory. You will also be asked if you would like to replace the DokuWiki mediamanager with a revised version which is needed for the FCKeditor The revised version is entirely compatible with DokuWiki. Your original DokuWiki mediamanager.php will be backed up. b. SUBSEQUENT OR MANUAL INSTALLATION The DokuWikiFCK package can be downloaded from this web site or from CPAN at: http://search.cpan.org/search?module=HTML::WikiConverter::DokuWikiFCK To install, the standard instructions are: gzip -dc HTML-WikiConverter-DokuWikiFCK-0..tar.gz | tar -xvf - OR tar -xzf HTML-WikiConverter-DokuWikiFCK-0.XX.tar.gz perl Makefile.PL make make test make install c. A COMPLETELY MANUAL INSTALL DokuWikiFCK.pm subclasses DokuWiki.pm in order to give additional functionality to the FCK editor. First, place DokuWikiFCK.pm and DokuWikiFCKN.pm in the perl5 directory, where DokuWiki.pm is installed. This should be: usr/lib/perl5/site_perlHTML/WikiConverter. Then install the fckg plugin in the DokuWiki plugins directory. The following perl dependencies are required: HTML::WikiConverter HTML::WikiConverter::DokuWiki d. EXTRA CSS The file fckg/extra/style.css should be copied to your dokuwiki template directory, which is normally lib/tp/default 2. SPACE-BAR POSITIONING The FCKeditor supports positioning of text and images using the Outdent, Indent, and Justification toolbar items. Justification is left, right, and center. Outdent and Indent position elments at 40 pixel intervals. DokuWikiFCK has extended this functionality to enable positioning by use of the space-bar. The editor's toolbar functions have priority over space-bar positioning. Until version 3.0.1 of Firefox, Firefox ignored spaces when switching from the FCKeditor the browser; that is, it collapsed runs of contiguous spaces to a single space. Presumably, it treated spaces found in the editor like spaces in an HTML document instead of as non-breaking spaces, which have a width set by the current font and font-size. This meant, for example, that if you pushed something over from the left margin, using the space-bar, when you switched over to the browser it would be back at the left margin. To compensate, DokuWikiFCK saved runs of three or more spaces as medial dots. This required a great deal of book-keeping. First, since the middot is a printable character, DokuWikiFCK had to make sure that it didn't display; then it had to convert the middot to a non-breaking space when displaying in the browser; and it had to keep track of whether it was in IE or in Firefox, since the problem didn't exist in IE. Finally, it was not an ideal solution, because the middot is not the same width as a space character and since in non-Latin alaphabets the middot may have a valid orthographical use. Because of the changes in Firefox 3.0.1, this work-around is no long needed. Therefore, as of version 24 of DokuWikiFCK, the middot workaround is no longer supported. However, version 24 of DokuWikiFCK recognizes that there may still be users of DokuWiki who have not upgraded to Firefox 3 or who might be using browsers incompatible with the changes to version 24. The administrator can assign these users to a special DokuWiki group (or groups) using the Configuration Manager. The default name for this group is middot. Users assigned to this goup will use DokuiWikiFCKN instead of DokuWikiFCK. DokuWikiFCKN retains the middot protocol. In version 24, DokuWikiFCK and DokuWikiFCKN are as much as possible homogenous, and there should be little if any difference between documents edited using either of these modules when the documents are displayed in the browser. However, there is no guarantee that DokuWikFCKN will keep up with changes to DokuWikiFCK. One hopes that users will upgrade to compatible browsers. Version 24 of DokuWikiFCK has been tested on IE6 and 7, Firefox 3.0.1, Safari 3.1.2 (Windows). 3. INSERTING AND UPLOADING IMAGES The DokuWiki media manager is used for uploading files and the FCKEditor media manager is used for inserting files in the FCK editor's editing space. To implement inserting and uploading of images: a. replace the copy of DokuWiki's mediamanager.php in tpl/ with the one included in this package. b. create a userfiles directory in your document root directory. Inside userfiles, create a symbolic link that points to the dokuwiki media directory: userfiles image -> /data/media 4. MEDIA MANAGER IN MULTIPLE DOKUWIKI INSTALLATIONS If you are running more than one dokuwiki on your server,each using DokuWikiFCK, and if each has its own media directory, you will have to create a 'userfiles' directory for each installation, and each 'userfiles' will need an 'image' link to its own media directory. The way to do this is as follows: a. for each installation create a 'userfiles' directory b. in each 'userfiles' create a link to its media directory b. go to fckg/fckeditor/editor/filemanager/connectors/php.config.php and in config.php make the following edits: ADD: $UserFilesRealPath = /absolute/path/to/userfiles/'; CHANGE: Path to user files relative to the document root: $Config['UserFilesPath'] = '/userfiles/'; Note: 'path/to' does not include the document root directory itself! See the example below. //$Config['UserFilesAbsolutePath'] = ""; $Config['UserFilesAbsolutePath'] = $UserFilesRealPath; EXAMPLE: Your absolute path is: /var/www/html/dw_1/userfiles Your document root is: /html/ $UserFilesRealPath = '/var/www/html/dw_1/userfiles/'; $Config['UserFilesPath'] = '/dw_1/userfiles/'; $Config['UserFilesAbsolutePath'] = $UserFilesRealPath; The rest follows the instructions for a single userfiles directory in 3 above. 5. FCKEDITOR TOOLBAR The following FCKEditor Toolbar items are supported: FCKConfig.ToolbarSets["Dokuwiki"] = [ ['Bold','Italic','Underline','StrikeThrough','-','Subscript','Superscript'], ['OrderedList','UnorderedList'], ['Outdent','Indent'], ['JustifyCenter','JustifyLeft','JustifyRight'], ['Rule', 'Block_Q'], ['Smiley', 'SpecialChar'], [], ['Cut','Copy','Paste','PasteText', 'PasteWord', 'SpellCheck', 'Find'], ['Style'], ['FontFormat','FontName','FontSize'], ['Undo','Redo','RemoveFormat', '-','Table','Format_Table'], ['TextColor','BGColor', 'Plugin_Tool', 'Trim_Spaces','Delete_P'], ['Link','Unlink'], ['Image', 'Source' ], ['About'] ] ; The Quick Reference to the Standard toolbar items shows the toolbar icons of the tools supported by DokuWikiFCK, and it briefly describes the use of each tool. The toolbar can be customized. See the documentation on the FCKeditor site. DOKUWIKIFCK TOOLS AND TOOLBAR EXTENSIONS DokuWikiFCK implements a number of tools of its own and extensions to the standard toolbar items.Some of these are described fully on the features page of the web site. More briefly, they are: The plugin tool ('Plugin_Tool') a. This tool maintains the integrity of syntax plugins. b. It escapes plugin markup for plugins which use angle brackets, so that the brackets will not be mistaken for HTML syntax. c. It guarantees that plugin syntax which produces output will not be replaced by that output. This is essential for plugins that refresh their output when the page is refreshed. d. It guarantees that javascript scripts needed for the plugins will be sent to the browser. See the features page for details. The Table Formatting tool ('Format_Table') This tool supports an extended set of options for formatting tables. See the features page section on formatting tables. There is also a 'Styles' option which implements the creation of standard DokuWiki table headers. See table headers on the features page. The BlockQuote Tool ('Block_Q') This is an extended version of the Blockquote toolbar item that comes standard with the FCKEditor. Our extension supports border styles and colors, font selection and background colors. The Paragraph to LineBreak Tool ('Delete_P') The FCKeditor uses paragraphs as its basic unit of separation between text blocks. This tool will convert paragraphs to line-breaks, making it possible to create sequences of short single-spaced lines, as in I.b. above. Otherwise, single-spacing would happen only within paragraphs, and sequences of short lines would be double spaced (i.e. each it own paragraph). The ony other way in DokuWiki to get sequences of single-spaced lines is in lists. The Trim Spaces Tool ('Trim_Spaces') The FCKeditor often populates a page with blank paragraphs. This tool eliminates them. It was developed before the appearance of Firefox 3 when unnecessary inserted spaces also found their way into documents. The 'spaces' mode of this tool is operable only with the older protocol governing runs of spaces (see 2. above). Spell Checker DokuWikiFCK supports the FCKeditor SpellerPages facility. To use this facility, you must have GNU aspell installed and all required aspell dictionaries. The aspell binary must be in the web server's path. On Mac OS X, for instance, the ports command installs in the /opts directory and so /opts/bin will very likely not be in the web server's path; hence a symbolic link from /usr/bin to the aspell binary will be needed. Creating Code Blocks With the Style->Code Selection, when pasting text use this procedure, depending on which browser you use: FireFox: Use the 'Paste' Icon or right-click and then click on "Paste" Then Select Text and click on Style->Code Inserting a new-line when at the end of a line sometimes causes the code block to divide into two blocks. There are two techniques that help to prevent this. The first is to make sure there are no spaces at the end of the line. Or else, move the cursor to the beginning of the next line and then hit return. The new line is now above the current line and below the line above it. IF no text follows your code block, insert a few extra blank lines at the end of your page before creating the code block; otherwise the cursor gets stuck inside the block and you can't move on to the next line. IE Use the 'Paste' Icon, then select your text and click on the
->
tool (also available by right-click mouse). This
will remove the paragraphs (or double line spacing) which
can be restored after the code block has been created.
Then Select Text and click on Style->Code.
Safari:
Safari is similar to FireFox but also may require using the
->
tool, as in IE.
In all cases, you can create an empty code block and insert text into it using
Ctrl-C/Ctrl-V on Windows and Command-C/Command-V on the Mac.
To match the FCKeditor's handling of the Code styles, insert into your template
directory the style.css file found in fckg/extra.
Special Characters Tool ('SpecialChar')
The FCKeditor's Special Characters Tool comes with a table of chacters that can
be inserted into the text with a mouse click. DokuWikiFCK expands this by providing
a text box which will accept either an HTML character entity or entity number,
enabling the user to insert all potential character entities into the text.
Note on the Open Angle Bracket
The open angle bracket introduces an HTML tag and requires special treatment outside of a code
block. The open angle bracket should be converted to a variable, using the Style
menu. Highlight the bracket and select Style->variable. Initially and text following
may be converted to italic. To get rid of the italics after the bracket, use the eraser tool.
6. LOCK TIME OUT AND AUTO-DRAFT SYSTEM
With version 24 of DokuWikiFCK, the FCKeditor is fully tied into DokuWiki's auto-draft and
file locking systems. Until this tie-in, DokuWiki was unable to monitor the FCKeditor
editing space for keyboard activity. Unable to detect evidence of editing activity, it
would not save drafts and would would issue a lock time out warning every 14 minutes.
Version 23 of DokuWikiFCK dealt with the latter by disabling the time out warning, because
users found the warnings a nuisance. With version 24, this is no longer necessary; time
out warnings and the auto-drafts work as they should.
Issues:
1. Because making this tie-in took a bit of technological legerdemain, DokuWikiFCK
provides for the possibility that it might fail in untested browsers or under certain
browser conditions. If so, a check box will appear with the following label : Disable
editor time-out messsages. Administrators may not want to allow all users to have the
privilege; therefore, there is a setting in the Configuration Manager which enables the
administrator to set a group which has this privilege. The default setting for this group
is ANY, which means that all users have this privilege should they need it; there is no
need to create a group called ANY .
2. In cases where a draft file is recovered, the draft is not in DokuWiki format but in
HTML, which is how the FCKeditor sees it.
3. There is a Refresh button, which enables the user to renew the lock wthout having to
Save or switch to Preview.
See: http://www.dokuwiki.org/draft
http://www.dokuwiki.org/locking
7. SUPPORT FOR LARGE FILES
On some systems the shell cannot pass through large files between scripts, hence the files
would be lost. Large files are now saved to a tmp file by save.php
and reloaded for processing in saveFCK.pl The files are saved to a temp file ins Dokuiki's
data/tmp directory (this must be writable by the web server).
Configuration options for handling large files (found in Configuration Manager):
big_files: default=FALSE.
Must be set to TRUE for large files facility to take effect.
big_file_sz: default=65000 bytes.
Files larger than big_file_sz will be treated as Large Files;
big_file_tm: default=15 seconds.
If a large file takes longer big_file_tm seconds to be
processed, the procesing will be aborted and the original text will be saved--
which means that the current edits will be lost.
8. BACKUPS OF FCK FILES WHEN SWITCHING TO NATIVE DOKUWIKI EDITOR
The editing page gives the user the option of switching to the native DokuWiki Editor. It offers
two choices, to convert to standard DokuWiki markup or to save the current file and start with
a blank editor.