Frequently Asked Questions

Q: Following your instructions, I managed to install your software on my Mac running macOS Catalina 10.15 (using your .dmg distribution for that), however the File|Open dialog box and the File|Folder pane do not display any of the files found in my Documents folder. Is this a known bug?

A: Please download and install the .dmg distribution of XXE v9.2+.

If installing XXE v9.2+ does not solve this issue or if you want to install a version older than v9.2, please refer to this known problem.

Q: XMLmind XML Editor looks “fuzzy” on the HiDPI screen of my Windows 10 computer. I thought HiDPI screens were well supported by XXE. How to fix this problem?

A: If this happens, it's probably because you are still running Java™ 1.8 on your computer. If this is the case then please try any of the following solutions to your problem:

• Recommended. Upgrade to XXE v9+ using the corresponding setup.exe distribution. This distribution includes a private Java 12+ runtime.
• OR Upgrade your Java runtime to Java 11+.
• OR Instruct Windows 10 not to “enhance” XXE by using the following procedure:
  1. Using Windows 10 file manager, right-click file XXE_install_dir/bin/xxe.exe and select Properties from the contextual menu. This displays the following dialog box:
     
  2. Click "Change high DPI settings". This displays the following dialog box:
     
  3. Check "Override high DPI scaling behavior" and select "Application" from the "Scaling performed by" combobox.
  4. Restart XXE and use Options|Preferences, General section to set "Display scaling" to your likings.

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 anti-virus software is getting in the way by monitoring too aggressively the connections to our servers. Try to temporarily disable your anti-virus 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|Preferences, 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 server is temporarily down (this happens quite rarely). When this is the case, simply wait for a few hours until our server is restarted.
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: 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: 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.zip, please make sure to have a Java 8+ installed on your computer.

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

C:\> java -version

Besides Oracle Java and OpenJDK, an excellent resource for obtaining easy-to-install Java™ distributions is AdoptOpenJDK.

If you have installed XXE using xxe-XXX-setup.exe (which includes a private Java™ runtime found in XXE_INSTALL_DIR\bin\jre64\ ):

• XXE_INSTALL_DIR\bin\jre64\ contains a 64-bit version of the Java runtime which cannot be used on a 32-bit version of Windows. Therefore, on a 32-bit version of Windows, you'll still have to download and install a 32-bit Java™ 8+ runtime on your computer in order to use XXE.
• Otherwise, please take the time to send us a bug report as explained below.

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: 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:

     -Xss4m -Xmx512m

     to:

     -Xss4m -Xmx1024m

  4. Make sure to save your changes using the UTF-8 encoding.
• If you start XXE using the xxe-c.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-c.bat script file using notepad.
  3. Change line starting with:

     start "" /b "%java%" -Xss4m -Xmx512m ...

     to:

     start "" /b "%java%" -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="-Xss4m -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/MacOS folder.
3. Edit the xxe-mac.sh file using any text editor, for example,TextEdit.
4. Change the last line as follows:

   exec "$java" -Xss4m -Xmx512m

   to:

   exec "$java" -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, simply start XXE using XXE_install_dir/bin/xxe-c.bat rather than using xxe.exe (which is the “icon/launcher created by the installer”).
• 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 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 XHTML5. More information in XMLmind XML Editor - XHTML Support.

Q: I opened a modular DocBook 4 book in XXE comprising a number of chapters, each chapter being stored in its own file. "Edit|Reference|Edit Referenced Document" (keyboard shortcut: Ctrl+Shift-E) is always grayed out. Moreover, when I use "File|Open" to open to open a chapter file in XXE, it displays a tree view and not the styled view as expected. What's wrong with my DocBook 4 document?

A: Your modular DocBook 4 book includes a number of chapters by the means of references to external entities. Your chapter files being external entities, they cannot start with the DocBook <!DOCTYPE> and as such, are not stand-alone documents XXE can open. For example, if a chapter contains "&nbsp;", then opening it in XXE would cause the editor to report a "non well-formed XML" error.

For all these reasons, XMLmind has given up support for creating modular documents using entity references since XXE v4. You can open such legacy modular documents in XXE, but basically that's it.

If you want to keep using XXE, you need to convert all the entity references to XIncludes:

1. Add a DOCTYPE at the top of each module file (chapter, appendix, section, preface, etc). For example, add:

   <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" 
   "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> 

   at the top of Introduction.xml. Make sure to add the DOCTYPE after: <?xml version="1.0" encoding="ENCODING"?>.

2. In the book, replace each entity reference by the corresponding XInclude. For example: &Introduction; becomes:

   <xi:include href="Introduction.xml"
               xmlns:xi="http://www.w3.org/2001/XInclude" /> 

3. In the book, remove the now useless internal DTD subset. That is, remove:

   [
   <!ENTITY Introduction SYSTEM "Introduction.xml">
   <!ENTITY Installation SYSTEM "Install.xml">
   <!ENTITY Config SYSTEM "Config.xml">
   ...
   <!ENTITY AppendixConfigFileFormat SYSTEM "AppendixConfigFileFormat.xml"> 
   ] 

Q: I've used the "setup.exe" distribution (the ".dmg" distribution on the Mac) of XXE to install it on my computer. This distribution includes a private Java™ runtime. How can I stop XXE from using this private Java runtime? I have a more recent Java runtime installed on my computer.

A: On Windows, simply delete folder XXE_install_dir\bin\jre64\. Depending on where XXE has been installed, you may need administrator rights to do so.

On the Mac, simply delete folder XMLmind.app/Contents/Resources/xxe/bin/jre/ (jrea/ for a Mac having an ARM® processor).

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 when using any of the menu items of the "Convert Document" menu.

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 "DocBook|Convert Document|Convert to PDF".
3. Click "Document conversion parameters" to expand the conversion parameters pane.
   
4. Click Add.
5. Type:

   Name:	paper.type
   Value:	USletter

   
6. Click OK to convert your document using the paper.type parameter you have just specified.

   This setting is specified once for all, and not each time you'll have to convert a DocBook document. More information in XMLmind XML Editor - Online Help, The "Document conversion parameters" panel.

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). This can be done from within XMLmind XML Editor. More information in XMLmind XML Editor - Online Help, Apache FOP options and RenderX XEP options.

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|Customize Document Conversion Stylesheets.
3. Select "Convert to multi-page HTML" using the combobox found at the top of the dialog box.
4. Choose one of the items starting with "Generate XHTML" from the "XSLT stylesheet" combobox.
5. 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 DocBook|Convert Document|Convert to HTML. This displays a dialog box allowing to specify the output directory.
  3. Click Document Conversion Parameters. This expands a form in the dialog box. This form allows to specify conversion parameters.
  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. This setting is done once for all.
• 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: I'm supposed to be allowed to upgrade Professional Edition for free. How can I do that?

A: Please use this form: www.xmlmind.com/store/download.php , generally accessed through this page: 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: www.xmlmind.com/mailman/listinfo/xmleditor-announce .