PageBox: servlet running in sandbox on J2EE PageBox

for
Presentation FAQ Reference Customisation Runtime Forms Demo Math Verification Downloads Troubleshooting

Cuckoo Troubleshooting guide

Foreword

Disclaimer

In this section we mostly describe things that happen in products used by Cuckoo.

It aims to be useful but it can be inaccurate. Though we try to reproduce all problems, some information comes from user reports and couldn’t be checked.

Once you have fixed them, these environment problems don’t occur again.

Cuckoo has no hidden dependencies.

Beta

Our policy is to release tested versions only. Each version is at least as stable as the previous ones. It often includes performance enhancements, patches or usability improvements. Therefore we recommend to always using the last version.

Cuckoo is still in beta. It doesn’t mean that it breaks or can give unpredictable results. For its first alpha we used Cuckoo to write the pages of this site. Beta status means that:

  1. Cuckoo is packaged in an archive. The installation involves manual steps. You need at least to read the documentation and to adapt the XSL, XML and CSS examples to your needs.

  2. Cuckoo has not been tested in all combinations of Operating Systems and products. Because it is free, there were no team reviewing the documentation and making usability tests. We need your feedback to improve Cuckoo.

Known problems

In Word 2002 - at least in the French version - Cuckoo doesn’t detect comments. The reason is simple: Cuckoo checks for comments with:

If cr.Comments.Count > 0

Where cr is a character range. With Word 2002 cr.Comments.Count is zero even when there is a comment.

Common errors

Cuckoo macros not displayed

You must see toHTML and WordCount on the Word toolbar.

Starting with Cuckoo 0.1.1 you must also see Settings on the Word toolbar.

Possible causes:

  1. You are not using the cuckoo.dot template. To check if your Word document uses cuckoo.dot, use Tools | Templates and Add-ins.

  2. You disabled Word macros

  3. Your anti virus prevents running cuckoo.dot macros

There is a difference in term of function but no difference in term of mean between Cuckoo and a macro virus. Cuckoo starts commands and uses FileSystemObject, RegRead and RegWrite from WSH. Any Word macro can do that. Therefore Word allows disabling macros and anti virus can prevent running macros. To check your setting use Tools | Macro | Security. You should see this panel:

You can need to disable your anti virus to run Cuckoo.

We recommend setting the Security Level at medium.

Then when you open a document using the Cuckoo macro you get:

Click on the Enable Macros if you are sure that the document only includes the Cuckoo macros.

Note:

  1. cuckoo.dot doesn’t change normal.dot or global.dot

  2. Cuckoo code is only invoked when you click on a Cuckoo macro, toHTML, WordCount or Settings

Compile error

The error occurs when you run the toHTML macro and is displayed in a message box.

Compile error can be followed by:

  • User-defined type not defined

  • in hidden module XMLProcessor

Possible cause:

  • Anti virus

  • Required product not installed or referenced

Anti virus

An anti virus can prevent:

  • Using FileSystemObject from WSH: a malicious programmer could use it to create or remove files and directories

  • Using RegRead and RegWrite from WSH: a malicious programmer could use it to read or write on the registry

  • Using ShellExecute from Shell32: a malicious programmer could use it to start commands

You can either:

  1. Disable the macro checking in the anti virus or

  2. Comment the lines using these functions in Cuckoo

If you choose the second option:

  1. The core function of Cuckoo, creating a XML translation of your Word document, is preserved. Then you can run cuckoo-gen.js (cuckoo.bat and cuckooForPrinters.bat show how to use it) to generate the page.

  2. You lose convenience features: page displayed on your browser at the end of the translation and customization: you cannot change the name of the XSL, CSS and JavaScript file and your previous choices are not saved

Required products

Cuckoo requires:

  1. Windows Script Host (WSH). You can get it on the Microsoft site. This site uses dynamic pages, therefore we recommend making a search for WSH. We recommend WSH 5.6. The current URL is http://msdn.microsoft.com/downloads/default.asp?url=/downloads/sample.asp?url=/MSDN-FILES/027/001/733/msdncompositedoc.xml&frame=true. Actually the download URLs are http://download.microsoft.com/download/winscript56/Install/5.6/NT5/EN-US/scripten.exe for W2K and http://download.microsoft.com/download/winscript56/Install/5.6/W9XNT4Me/EN-US/scr56en.exe for Win 98, Me and NT 4. We only tested the English version.

  2. MSXML 3 or 4. You can get it on the Microsoft site. This site uses dynamic pages, therefore we recommend making a search for msxml 4.0 download. The current URL is http://msdn.microsoft.com/downloads/default.asp?URL=/downloads/sample.asp?url=/MSDN-FILES/027/001/766/msdncompositedoc.xml. Actually the download URL is http://download.microsoft.com/download/xml/SP/40SP1/WIN98MeXP/EN-US/msxml.msi. We only tested the English version.

The MSXML version has an impact:

  1. Internet Explorer uses MSXML 2

  2. You can change the default XML parser (used by Internet Explorer) to MSXML 3 with an xmslinst.exe utility. The documentation of the Microsoft XML SDK 4 says that "can often cause unintended side-effects for some applications".

  3. This utility is not available for MSXML 4

It matters because we cannot use a version-independent ProgID. To create an XML document in version 4, we use CreateObject("Msxml2.DOMDocument.4.0") whereas to create an XML document in version 3 we use CreateObject("Msxml2.DOMDocument.3.0").

The problem is complicated by the fact that you must add a reference on VBA. The library chosen here must match the ProgID used at CreateObject. The table below describes the behavior of Cuckoo.

Version

Behavior

MSXML 2 or 2.6

Not supported

MSXML 3

Use MSXML 3. On references use Microsoft XML, v3.0.

MSXML 4

Use MSXML 4. On references use Microsoft XML, v4.0.

MSXML 3 and 4

Use MSXML 4. On references use Microsoft XML, v4.0.

MSXML above 4

You can need to change the ProgID to a supported value.

Note:

We found that we had to register MSXML SP 4. We used this command:

Regsvr32 msxml4

Image handling

The safest way to add an image to a Cuckoo document is Insert | Picture | From file...

Word supports images in many different ways:

  • Linked to another file

  • Managed by another application

  • Floating

  • Inserted in the text

Cuckoo only manages images inserted in the text.

The reasons are:

  • For each image Cuckoo generates an image file (.jpg or .gif) and a tag <img src="myDocumenti.gif"/>. This model implies that Cuckoo knows where to create the img tag in the text stream. Generated html can be displayed properly even with the oldest browsers

  • It allows setting a comment for an image. Then Cuckoo can translate this comment in an alt tag. alt tag is an accessibility requirement and helps search engines to index your documents.

In some cases it is also possible to add an image to a Cuckoo document with Copy | Paste.

The reason why it doesn’t work all the time is related to the clipboard.

When you copy an image on the clipboard, it is actually your source application that makes the real work. It typically provides the image in different formats. When you paste the image, the target application imports the image in the most advanced format that it supports.

When you click on the Cuckoo document if the image is in a valid format, then you should see black handles around the image. We checked that the following operations are valid:

  • Alt Prnt Scrn | Paste

  • Ctrl Alt Prnt Scrn | Paste

  • Click on an image displayed by Internet Explorer | Copy | Paste

You can use another application to downgrade the quality of the clipboard. You paste in this application, you copy again and then you paste in the Cuckoo document.

Cuckoo customisation

You customize Cuckoo using the Setting macro.

Your settings are saved in the registry in HKEY_CURRENT_USER\Software\PageBox\Cuckoo.

toHTML manages the following values:

Value name

Value data

toHTML

file

Name of the XHTML file to generate

File name

site

Directory where to get the CSS, the JavaScript file and the XSL

Style directory

By default the XHTML file generated for an xxxx.doc file is xxxx.html.

By default Cuckoo looks for the CSS, JavaScript file and XSL in the directory of xxxx.doc.

Setting manages the following values:

Value name

Value data

Setting

Default

xsl

XSL file used to convert the XML stream generated by Cuckoo in XHTML

XSL file name

cuckoo.xsl

css

CSS file used to render the XHTML file

CSS file name

cuckoo.css

js

JavaScript file used to render comments with mouseover

JavaScript file

cuckoo.js

normal

Name of the normal style (no class set in HTML)

Standard style mapping

Normal

heading1

Name of the Header 1 style (<h1> in HTML)

Standard style mapping

Heading 1

heading2

Name of the Header 2 style (<h1> in HTML)

Standard style mapping

Heading 1

heading3

Name of the Header 3 style (<h1> in HTML)

Standard style mapping

Heading 3

heading4

Name of the Header 4 style (<h1> in HTML)

Standard style mapping

Heading 4

heading5

Name of the Header 5 style (<h1> in HTML)

Standard style mapping

Heading 5

heading6

Name of the Header 6 style (<h1> in HTML)

Standard style mapping

Heading 6

comment

Translated in title, alt... depending on the context

Standard style mapping

Comment Text

table

HTML tags to use for <table>

Table customisation

cuckoo-table...

td

HTML tags to use for <td>

Table customisation

cuckoo-td...

th

HTML tags to use for <th>

Table customisation

cuckoo-td...

invisible-table

HTML tags to use for <table> with InvisibleTable style

Table customisation

cuckoo-itable...

invisible-td

HTML tags to use for <td> with InvisibleTable style

Table customisation

cuckoo-itd...

For Table customisation values, all tags are set. For clarity we only show the CSS class that is used.

Settings also manages custom styles.

Cuckoo creates a key custom i for each custom style. This key contains:

Value name

Value data

Wstyle

Style name in Word (can be Unicode)

CSSclass

CSS class

You can export HKEY_CURRENT_USER\Software\PageBox\Cuckoo in a reg file. It allows a team to use the same settings.

Troubleshooting and bug report

If you get a problem not listed above such as a Word crash we recommend following the procedure that we present below.

In all bug reports, please indicate the Operating System, the Word version and the XML version.

If possible send us

  1. The Word file where the problem took place

  2. The list of the generated files

  3. The generated XML file

Check the status line

In case of error the File Selection form is not hidden and a message is displayed on the bottom line.

Bug report:

Send us the exact message.

If the File selection form was not refreshed, try the plan B below.

Reproduce the problem with the VBA editor opened

To open the VBA editor, use Tools | Macro | Visual Basic Editor.

For some errors the VBA Editor will point the line where the error occurs.

Bug report:

Send us the name of the class, form or module and the line where the problem happens. Send us also the exact error message.

Note:

If the VBA editor points that code in the FileSelection form:

If ActiveDocument.Type = wdTypeDocument Then

wr.process ActiveDocument, proc

End If

It just means that an exception occurred in a function called by wr.process and that it wasn’t catched.

In that case, set the trace.

Generate a trace

To set the trace on, click the Settings macro and check the Trace checkbox.

Bug report:

Send us the trace file.

Cuckoo forum

We created a forum for Cuckoo users at http://sourceforge.net/forum/forum.php?forum_id=191582.

We copied there some interesting mails in the hope that they will be useful even if some issues are now addressed in a better way in Cuckoo.

Please use now the Cuckoo forum to submit your problems. Other users will get a chance to read the responses and perhaps to answer your questions.

Contact:support@pagebox.net
2001-2004 Alexis Grandemange. Last modified .