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
<P> -> <BR> 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 <P> -> <BR>
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.