Frequently Asked Questions

Q: I am a consultant customizing/extending XXE as described in "XMLmind XML Editor - Configuration and Deployment". However XXE seems to ignore all the files I have created in its addon/ subdirectory. What am I doing wrong?

A: As of v4.9, you need temporarily disable the Quick Start and Schema caches while you are customizing/extending XXE. This is done by unchecking the corresponding checkboxes in Options|Preferences, Advanced|Cached Data section. More information about these caches in "XMLmind XML Editor - Online Help", Cached data options.

Q: XMLmind XML Editor v4+ does not start when running latest Java^TM 1.7 runtime. Can you help?

A: There is no way to run XMLmind XML Editor v4+ using a Java^TM 1.7 runtime. Please upgrade to XMLmind XML Editor v5+.

Q: I cannot start XXE on Debian (Ubuntu, Fedora, etc) Linux. Any hints?

A: If, when you try to start XXE on Debian (Ubuntu, Fedora, etc) Linux, you get the following error messages printed on your terminal:

java.lang.NullPointerException
   at com.xmlmind.xmledit.util.FileUtil.fileToURL(java.io.File)
   (Unknown Source)
   at com.xmlmind.xmleditapp.start.Start.doScanAddonDir(java.io.File, 
   java.util.ArrayList) (Unknown Source)
... 
   at com.xmlmind.xmleditapp.start.Start.main(java.lang.String[])
   (Unknown Source)
   at gnu.java.lang.MainThread.call_main() (/usr/lib/libgcj.so.6.0.0)
   at gnu.java.lang.MainThread.run() (/usr/lib/libgcj.so.6.0.0)
[Loaded (pre-compiled) gnu.gcj.runtime.FileDeleter from <no code source>]

this means that you attempt to run XXE with a Java^TM runtime other than the one coming from Sun. The problem is that XXE really requires the Oracle (ex Sun) Java^TM runtime in order to run on Linux.

In order to fix this problem:

1. Download and install a JDK or a JRE from Oracle (generally the latest, the best).

   Personally, I always download the ``bin'' distribution, not the RPM one, and I install it in /opt. By doing this, I cannot break any application (such as OpenOffice) which relies of the ``official'' Java^TM runtime included in my Linux distribution (SuSE).

2. Edit the XXE_install_dir/bin/xxe shell script and change:

   java $mem $opt ...

   to (for example):

   /opt/jdk1.7.0_09/bin/java $mem $opt ...

   The above example assumes that you have downloaded JDK 1.7.0_09 and that you have installed it in /opt.

Q: I have successfully installed the setup.exe on my Windows® machine but after that, I cannot start the application. Can you help?

A: Which distribution have you installed?

If you have installed XXE using xxe-XXX-setup-nojvm.exe (which requires to have Java^TM runtime properly installed):

1. Make sure that a Java^TM runtime version 1.6+ has been installed on your machine. (If this is not the case, the icon/launcher created by the installer should have displayed a error dialog box clearly saying so.)

   To check this, open a command window (AKA DOS window) and execute the following command:

   C:\> java -version

2. Please take the time to send us a bug report as explained below.
3. As a workaround, try to start XXE using xxe.bat instead of the ``icon/launcher created by the installer''.

   xxe.bat is found in the bin/ subdirectory of the directory where you have installed XXE (by default C:\Program Files\XMLmind_XML_Editor\bin).

   In order to do this, edit xxe.bat using notepad and change the beginning of last line:

   start javaw

   to (following example assumes that you have installed the required Java^TM 1.5+ runtime in C:\Program Files\Java):

   start "XXE" "C:\Program Files\Java\jre1.6.0_07\bin\javaw"

   (Quotes are very important in above example.)

If you have installed XXE using xxe-XXX-setup.exe (which includes a private Java^TM runtime):

1. Please take the time to send us a bug report as explained below.
2. As a workaround, try to start XXE using xxe.bat instead of the ``icon/launcher created by the installer''.

   xxe.bat is found in the bin/ subdirectory of the directory where you have installed XXE (by default C:\Program Files\XMLmind_XML_Editor\bin).

   In order to do this, edit xxe.bat using notepad and change the beginning of last line:

   start javaw

   to (following example assumes that you have installed XXE in C:\Program Files\XMLmind_XML_Editor):

   start "XXE" "C:\Program Files\XMLmind_XML_Editor\bin\jre\bin\javaw"

   (Quotes are very important in above example.)

Tracing what happens when the ``icon/launcher created by the installer'' is used to start XMLmind XML Editor

This launcher is file xxe.exe found in the bin/ subdirectory of the directory where you have installed XXE (by default C:\Program Files\XMLmind_XML_Editor\bin).

The launcher is parametrized by file xxe.jstart found in the same directory. This file is a text file using the UTF-8 encoding. (If you modify it using notepad, make sure to save it as UTF-8.)

1. Open a command window (AKA DOS window).
2. Change current directory to the bin/ subdirectory of the directory where you have installed XXE:

   C:\> cd C:\Program Files\XMLmind_XML_Editor\bin

3. Define an environment variable called VERBOSE_JSTART:

   C:\Program Files\XMLmind_XML_Editor\bin> set VERBOSE_JSTART=1

4. Start XXE using xxe.exe run from this command window:

   C:\Program Files\XMLmind_XML_Editor\bin> xxe.exe

5. When environment variable VERBOSE_JSTART has been set, xxe.exe creates a log file called xxe.jstart_log in the directory where you have installed XXE.

   C:\Program Files\XMLmind_XML_Editor\bin> type xxe.jstart_log

   Please send us () this file and also, please specify the exact version of Windows® you use, your locale and the exact version of Java^TM you use.

Q: I cannot download and install any add-on using Options|Install Add-ons. Is there another way to download and install add-ons?

A: Please try the following workarounds (in the order of this list):

1. May be your antivirus software is getting in the way by monitoring too aggressively the connections to our servers. Try to temporarily disable your antivirus software while you are downloading and installing add-ons.
2. May be you have problems with the proxy server which is used by your organization. This proxy server is typically used each time your Web browser (or XMLmind XML Editor) attempts to make connections to the Internet.
   1. Use Options|Options, select the Proxies section.
   2. Check that your proxy server is properly declared here. If you don't know how to fill this form, ask your network administrator to help you.
   3. Click OK. Try again to download and install add-ons using Options|Install add-ons.
3. May be XMLmind primary download site is temporarily down (this happens quite rarely).
   1. Use Options|Preferences, select the Install Add-ons section.
   2. Click button Reset.
   3. Select "Use the secondary add-on server".
   4. Click OK. Try again to download and add-ons using Options|Install add-ons.

   A few hours later, after XMLmind primary download site has been restarted, you may want to restore "Use the primary add-on server".

4. If the above workarounds have not solved your problem, we recommend this approach which should work in all cases:
   1. Use your Web browser to download from this page: http://www.xmlmind.com/xmleditor/addons.shtml, all the add-ons you are interested in.
   2. An add-on is packaged as a .zip file. Make sure to save all the downloaded .zip files to the same directory. For example, let's suppose this directory is C:\temp.
   3. Use Options|Preferences, select the Install Add-ons section.
   4. Turn "Download add-ons from these servers" off.
   5. Turn "Search add-ons in the directory" on and specify "C:\temp" in the corresponding text field.
   6. Click OK. Try again to download and install add-ons using Options|Install add-ons.

Q: When I use Options|Install Add-ons, the add-ons I'm interested in are not listed in the dialog box. I'm sure I've seen these add-ons listed there before. What happens and how can I download and install these add-ons?

A: You are almost certainly using a version of XMLmind XML Editor which is more than one version older than latest version. For example, latest version is v4.8 and you are using v4.6. In such case, the add-ons which match this version have been archived and cannot be downloaded and installed using the normal settings of Options|Install Add-ons.

The easiest way to download and install “old add-ons” from within XMLmind XML Editor is to proceed as follow:

1. Select menu item Options|Preferences, then select the Install add-ons section.
2. Click the Reset button and select "Use the add-on archive" from the popup menu.
3. Click OK to close the dialog box.

All this is done once for all. Install add-ons normally using Options|Install Add-ons. Now, you should see in the dialog box much more add-ons than before.

Where to find old versions of XMLmind XML Editor?

You'll find old versions of XMLmind XML Editor and also old versions of the add-ons in http://www.xmlmind.com/archive/xmleditor/. You can use your Web browser to browse this archive.

Directly downloading distributions from this directory may be useful if, for example, your enterprise proxy does not allow you to follow the above procedure.

Q: XXE freezes when I try to open large XML files. Is there a workaround for this problem?

A: This is probably an out-of-memory error due to the fact that your XML file is very, very, large or contains loads of high-resolution images.

By default, XXE is configured to use at most 512 megabytes. This limit can be increased but this requires you to edit a script file using a text editor.

On Windows,

• If you start XXE using the ``icon/launcher created by the installer'' (file xxe.exe) in the Start menu:
  1. Go to the bin/ subdirectory of the directory where you have installed XXE, for example C:\Program Files\XMLmind_XML_Editor\bin.
  2. Edit xxe.jstart using notepad. Make sure to use a version of notepad which supports the UTF-8 encoding.
  3. Change line:

     -Xss1m -Xmx512m

     to:

     -Xss4m -Xmx1024m

  4. Make sure to save your changes using the UTF-8 encoding.
• If you start XXE using the xxe.bat script:
  1. Go to the bin/ subdirectory of the directory where you have installed XXE, for example C:\Program Files\XMLmind_XML_Editor\bin.
  2. Edit the xxe.bat script file using notepad.
  3. Change line starting with:

     start javaw -Xss1m -Xmx512m ...

     to:

     start javaw -Xss4m -Xmx1024m ...

On Linux/Unix:

1. Go to the bin/ subdirectory of the directory where you have installed XXE, for example /opt/xxe/bin.
2. Edit the xxe script file using a text editor.
3. Change line:

   mem="-Xss1m -Xmx512m"

   to:

   mem="-Xss4m -Xmx1024m"

On the Mac:

1. Using the Finder, Ctrl-click or right-click on the XMLEditor icon and then choose "Show Package Contents" from the pop-menu in order to open the application bundle.
2. From there, go to the Contents folder.
3. Edit the Info.plist file using the Property List Editor (which is the default application to do that).
4. In the Java section, change line:

   VMOptions String -Xss1m -Xmx512m

   to:

   VMOptions String -Xss4m -Xmx1024m

Q: XXE crashes when I try to convert large XML files to PDF. Is there a workaround for this problem?

A: See answer to previous question.

Q: XXE seems to freeze when I do such and such action. What's going on?

A: You have probably found a bug and a low-level error message (an exception stack trace) has probably been printed on the console.

Please take the time to send an email to , describing what you did and containing a copy of this low-level error message. A screen shot of the console is fine but note that it is the start of the error message which is meaningful, and not its end.

Now the question is how the display the console on which XXE prints its low-level error messages.

On Windows, you need to force XXE to use java.exe rather than javaw.exe.

In order to do this, please edit xxe.jstart using notepad and change this line:

start jre\bin\javaw.exe

to:

start jre\bin\java.exe

Make sure to save xxe.jstart using the UTF-8 encoding (normally this is done automatically by notepad).

On the Mac, open the Console application which is found in /Applications/Utilities/, then start XXE.

On Linux, simply start XXE from an xterm.

Q: I just downloaded XXE and opened a few of my XML documents with it. It works fine except that all I can see is a tree view. How can I get a word processor-like view for my documents?

A: Please take the time to read the Configuration and Deployment document. This document explains how to write a configuration file for XXE.

Writing a simple configuration file plus a few template documents for a custom DTD takes 10 minutes. Specifying a custom menu and/or custom tool bar buttons is also quick and easy. Writing a CSS style sheet may take several hours but it's worth doing it.

Q: I get a lot of errors when I open one of my XHTML documents. I'm sure these documents are valid. Why does XXE report such false errors?

A: You have opened an XHTML document conforming to the Transitional DTD and this document, not having the proper <!DOCTYPE> at the top of it, is considered by XXE as conforming to the Strict DTD. More information in XMLmind XML Editor - XHTML Support.

Q: How can I view in the XML source of my document?

A: XMLmind XML Editor has a tree view, a styled view but no source view. Therefore, you need to use a third party tool, for example a text editor, for that.

As of XXE v3.7, the Tools menu has two entries allowing to do just that:

Open Document in Help Application

Use this entry if you simply need to view the document, not to edit it.

Edit Document in Help Application

Keyboard shortcut Ctrl+Shift-D. Use this entry if you want to edit the document and then, if modified, to automatically reload it in XXE.

Alternatively, you can drop the icon looking like a small file, found in the node path bar, directly on the text editor.

A helper application allowing to edit plain text file "helper(text/plain)" is declared by default. You can change this default text editor (e.g. notepad on Windows) by modifying the "text/plain" item in the Preferences dialog box, Helper Applications section, File types list.

Using the same dialog box, you can also associate a specialized editor to the filename extension of your XML document. For example, you can specify to always use Inkscape to open and edit XML documents having a ".svg" extension.

Q: Certain elements seem impossible to select when displayed in the styled view. Is there a way to select them without switching to the tree view?

A: Please take the time to follow at least the first few lessons of the XXE tutorial.

Q: I've inserted an emphasis element and typed some text in it. Now I would like to type plain text but I'm stuck in this emphasis element. What can I do?

A: You need to insert a text node after the emphasis element. The quickest way to do so is simply to press on the Insert key (the F1 key on the Mac, which has no Insert key). This kind of tip is described in the XXE tutorial.

Q: The Edit tool is tedious to use. Is there a quicker way to insert elements?

A: Please take the time to follow at least the first few lessons of the XXE tutorial.

Q: Why is XXE so hard to use?

A: XXE is simple to use once you have taken the time to learn how it works. In other words, unless you follow at least the first few lessons of the tutorial, you'll loose your time with XXE.

Q: How can I change the charset of the HTML files generated when I convert a DocBook document to HTML? This charset is ISO-8859-1. I would prefer it to be UTF-8.

A: The charset used by default for HTML is ISO-8859-1 for historical reasons. The charset used by default for XHTML is UTF-8. Therefore if you don't mind generating XHTML rather than HTML, the simplest thing to do is to switch to XHTML.

Procedure:

1. Open the document you want to convert to activate its configuration.
2. Select menu item Options|Customize Configuration|Document Conversion Preferences.
3. Check "Generate XHTML rather than HTML".
4. Click OK.

If you really want to generate HTML and not XHTML, then this becomes more complicated.

• You want to generate multi-page HTML:
  1. Open the document you want to convert to activate its configuration.
  2. Select menu item Options|Customize Configuration|Change Document Conversion Parameters.
  3. Select "Convert to multi-page HTML" using the combobox found at the top of the dialog box.
  4. Click on Add
  5. Specify "chunker.output.encoding" as the name of the parameter and "UTF-8" as the value of the parameter.
  6. Click OK.
  7. Click OK.
• You want to generate single-page HTML:

  You are out of luck because this requires customizing the DocBook configuration by hand. How to do this is explained here: Customizing the XSLT style sheets used in the Convert Document submenu.

Q: When I convert documents written in Russian (or Polish or Czech or any non-western language) to PDF, almost all characters are replaced by the "#" character. Is there a workaround for this problem?

A: By default, PDF uses its 14 built-in fonts: Times, Helvetica, Courier, Symbol and ZapfDingbats. These fonts have glyphs only for the western (AKA Latin1) languages. Therefore you need to substitute to these built-in fonts truly multilingual fonts. Fortunately, such multilingual fonts are widely available. For example, the Times New Roman, Arial and Courier New fonts are available in standard not only on Windows, but also on the Mac and on most flavors on Linux (msttcorefonts package).

Procedure: Requires Professional (or Evaluation) Edition v4.2+.

• If you want to use Times New Roman, Arial and Courier New instead of Times, Helvetica, Courier:
  1. Select menu item Options|Preferences.
  2. If you have installed the Apache FOP plug-in, select Add-on|FOP. If you have installed the RenderX XEP plug-in, select Add-on|XEP.
  3. Click Use Windows® standard fonts.

     Note that the Use Windows® standard fonts button is grayed if the Arial font is not found in the standard fonts folder of your system.

  4. Click OK.
• If you want to choose specific fonts: For example, you want to replace Times fonts by Georgia fonts.
  1. Select menu item Options|Preferences.
  2. If you have installed the Apache FOP plug-in, select Add-on|FOP. If you have installed the RenderX XEP plug-in, select Add-on|XEP.
  3. Click Add.
     1. Choose the .ttf file containing font Georgia.
     2. Specify the following alias: serif.
     3. Click OK.
  4. Click Add.
     1. Choose the .ttf file containing font Georgia Bold.
     2. Specify the following alias: serif, Bold.
     3. Click OK.
  5. Click Add.
     1. Choose the .ttf file containing font Georgia Italic.
     2. Specify the following alias: serif, Italic.
     3. Click OK.
  6. Click Add.
     1. Choose the .ttf file containing font Georgia Bold Italic.
     2. Specify the following alias: serif, Bold, Italic.
     3. Click OK.
  7. Click OK.

  Notes:

  • It is recommended to also specify fonts replacing Helvetica, that is, fonts having a sans-serif alias and fonts replacing Courier, that is fonts having a monospace alias.
  • Some fonts have licensing restrictions that forbid embedding them in a PDF file. RenderX XEP enforces these licensing restrictions, not Apache FOP. XMLmind XML Editor has currently no way to detect these licensing restrictions, therefore you may follow the above procedure and end up with glyphs still missing in the generated PDF.

Q: How do I customize the HTML, PDF, RTF, etc, generated using the "Convert Document" menu?

A: This is done by customizing the XSLT stylesheet which is used to generate the HTML, PDF, RTF, etc, deliverable. Note that, for HTML-based deliverables (Web Help, HTML Help, EPUB, etc), you'll have to customize the CSS stylesheet used to style the generated pages.

As of XMLmind XML Editor v5.3, this can be done from within the application without modifying configuration files by hand and without prior knowledge of XSLT. This facility is implemented by menu item Options|Customize Configuration|Customize Document Conversion Stylesheets and by XMLmind XSL Customizer, a specialized editor.

Now your next question is almost certainly: which XSLT attributes, XSLT parameters, CSS styles do I need to specify to get the result I want?

Well, you'll find these answers in the following reference manuals:

• DocBook: DocBook XSL Stylesheet Reference Documentation by Norman Walsh; DocBook XSL: The Complete Guide by Bob Stayton.
• DITA: XMLmind DITA Converter Manual (the alternative to the DITA Open Toolkit which is integrated in XXE), XSLT stylesheets parameters.
• XHTML: XMLmind XML Editor - XHTML Support, Parameters of the XSLT stylesheets used to convert XHTML to XSL-FO.

Also, if you are a customer and send us a support request, we'll try to tell you which XSLT attributes, XSLT parameters, CSS styles, you should specify.

However, please keep in mind that XMLmind XML Editor is an authoring tool. It does not pretend to be a complete publishing solution. Therefore the answer to your question may be: this cannot be done simply by declaring XSLT attributes, XSLT parameters, CSS styles. Instead, the XSLT stylesheet which is used to generate the deliverable needs to be modified or extended by programming. When this is the case, you, as a technical writer, should consider hiring a consultant or leaving this responsibility to a ``local guru''.

Simplest customization

This being said, there are a few common cases for which you can customize what's generated by the "Convert Document" menu quite easily. This is done by using the Options|Customize Configuration|Change Document Conversion Parameters menu item.

For example, let's suppose you want to convert your DocBook document to PDF and want to change the paper type from A4 to US Letter.

In order to do that, you need to specify XSLT stylesheet parameter paper.type as USletter. (The reference manual of DocBook XSLT stylesheet parameters is DocBook XSL Stylesheet Reference Documentation.)

Procedure:

1. Open your DocBook document.
2. Select "Options|Customize Configuration|Change Document Conversion Parameters".
3. Select a group of parameter using the combobox. For this use case, it's "Converter to PDF, PostScript".
   
4. Click Add.
5. Type:

   Name:	paper.type
   Value:	USletter

   
6. Click OK twice.

This setting is specified once for all and not each time you'll have to convert a DocBook 4 or 5 document. More information in XMLmind XML Editor - Online Help, The "Change Document Conversion Parameters" dialog box.

Q: Is there a way to extend the evaluation period of XMLmind XML Editor?

A: No, this is technically not possible. You must either:

• Reinstall the product on a different machine.
• Or use a different user account to reinstall the product on the same machine.
• Or wait for the next release, uninstall the old copy, download and install the new release.

Q: I'm supposed to be allowed to upgrade Professional Edition for free. How can I do that?

A: Please use this form: http://www.xmlmind.com/store/download.php , generally accessed through this page: http://www.xmlmind.com/xmleditor/upgrade.html.

Tip: If you want to be sent an email each time a new version of XMLmind XML Editor is released, please subscribe to the xmleditor-announce mailing list. This is done by using the form found in this page: http://www.xmlmind.com/mailman/listinfo/xmleditor-announce .