Xmlmind Word To XML Manual
Xmlmind Word To XML Manual
Explains how to install and use XMLmind Word To XML (w2x for short) , how to customize
the output of w2x and how to embed a w2x processor in a Java™ application.
Hussein Shafie
XMLmind Software
35 rue Louis Leblanc,
78120 Rambouillet,
France,
Phone: +33 (0)9 52 80 80 37,
Web: http://www.xmlmind.com/w2x/
Email: mailto:[email protected] (public mailing list)
XMLmind Word To XML Manual
Contents
1 Introduction .......................................................................................................................................... 4
2 Installing w2x ....................................................................................................................................... 5
2.1 Contents of the installation directory ........................................................................................... 6
3 Alternatives to using the w2x command-line utility ............................................................................. 9
3.1 The w2x-app graphical application ............................................................................................... 9
3.2 The “Word To XML” add-on for XMLmind XML Editor ................................................................ 9
3.2.1 Installing the “Word To XML” add-on ................................................................................ 10
3.3 The “Word To XML” servlet ........................................................................................................ 10
3.3.1 Contents of the servlet software distribution..................................................................... 10
3.3.2 Installing the servlet ............................................................................................................ 11
3.3.3 Configuring the servlet ........................................................................................................ 11
3.3.4 Using the servlet to convert DOCX files .............................................................................. 12
3.3.5 Non interactive requests..................................................................................................... 13
4 Getting started with w2x .................................................................................................................... 15
4.1 How to generate useful multi-page HTML.................................................................................. 17
5 Going further with w2x ....................................................................................................................... 19
5.1 Stock XED scripts ......................................................................................................................... 21
6 Customizing the output of w2x ........................................................................................................... 24
6.1 Customizing the XHTML+CSS files generated by w2x ................................................................. 24
6.1.1 Using a XED script to modify the styles embedded in the XHTML+CSS file ........................ 24
6.1.2 Appending custom styles to the styles embedded in the XHTML+CSS file......................... 24
6.1.3 Using an external CSS file rather than embedded CSS styles ............................................. 25
6.1.4 Combining all the above methods ...................................................................................... 26
6.2 Customizing the semantic XML files generated by w2x ............................................................. 27
6.2.1 Converting custom character styles to semantic tags ........................................................ 27
6.2.2 Converting custom paragraph styles to semantic tags ....................................................... 28
6.2.3 The general case ................................................................................................................. 30
6.3 Generating XML conforming to a custom schema ..................................................................... 33
7 The w2x command-line utility ............................................................................................................ 34
7.1 Variables substituted in the parameter values passed to the –p and –pu options .................. 36
2
XMLmind Word To XML Manual
3
XMLmind Word To XML Manual
1 Introduction
Microsoft® Word is an amazing popular writing tool. However, its main drawback is that, once your
document is complete, you cannot do much with it: print it, convert it to PDF or send it as is by email.
XMLmind Word To XML aims no less than to suppress Microsoft® Word main drawback. This 100%
Java™ software component allows to automate the publishing —in its widest sense— of contents
created using Microsoft® Word 2007+.
More precisely, XMLmind Word To XML (w2x for short) allows to automatically convert DOCX files to:
Clean, styled, valid XHTML+CSS, looking very much like the source DOCX files.
Because the generated XHTML+CSS file is clean and valid, you can easily restyle it, extract
metadata or an abstract from it before publishing it.
Unstyled, valid, semantic XML (DITA, DocBook, XHTML, your custom schema, etc).
In this case, most styles are converted to semantic tags. For example, numbered paragraphs are
converted to proper ordered lists.
Generating semantic XML out of DOCX files is useful for interchange reasons (e.g. implement
open data) or because you want to port your existing documentation to a structured document
format where form and content are completely separated (e.g. implement single source
publishing).
Of course, deploying w2x does not require installing MS-Word on the machines hosting the software.
Also note that w2x does not require the authors to change their habits while using MS-Word: no strict
writing discipline, no specific styles, no specific document templates, no specific macros, etc.
4
XMLmind Word To XML Manual
2 Installing w2x
Requirements
XMLmind Word To XML (w2x for short) requires the Oracle Java™ runtime 1.6+. However, w2x is
officially supported by XMLmind only on Windows XP to 10, macOS 10.13 (High Sierra), 10.12 (Sierra)
and and Linux.
On Linux, make sure that the Java bin/ directory is referenced in the $PATH and, at the same time, check
that the Java runtime in the $PATH has the right version:
$ java -version
java version "10" 2018-03-20
Java(TM) SE Runtime Environment 18.3 (build 10+46)
Java HotSpot(TM) 64-Bit Server VM 18.3 (build 10+46, mixed mode)
On Windows and on the Mac, this verification is in principle not needed as the java executable is
automatically found in the $PATH when Java has been properly installed.
Install on Windows
1. Download the setup.exe distribution.
This setup.exe files includes a very recent, generally the most recent, Oracle® private Java™
runtime. Therefore, you don't need to install Java on your computer. Moreover, if you have Java
already installed on your computer, then your public Java runtime will be ignored by w2x.
2. Double-click on the setup.exe file to launch the installer.
3. Follow the instructions of the installer.
The .dmg distribution includes a very recent, generally the most recent, Oracle® private Java™
runtime. However, this private runtime is not necessarily the one which will be used to run
w2x-app:
5
XMLmind Word To XML Manual
- If you have an Oracle Java runtime at least as recent as the bundled one installed on your
computer, this runtime will be used to run w2x-app.
- Otherwise, it's the bundled runtime which will be used to run w2x-app.
Manual install on any Java 1.6+ platform (Windows, Mac, Linux, etc)
Unzip the .zip distribution in any directory you want.
C:\> cd w2x-1_5_0
C:\w2x-1_5_0> dir
... <DIR> bin
... <DIR> doc
... <DIR> legal
...
XMLmind Word To XML is intended to be used directly from the w2x-1_5_0/ directory. That is, you can
run the w2x command by simply executing (in a Command Prompt on windows, a terminal on Linux):
C:\w2x-1_5_0> bin\w2x
Usage: w2x [-version] [-v|-vv] [Options] [-liststeps] in_docx_file out_file
-version
Print version number and exit.
-v|-vv
Verbose.
-liststeps
List the conversion steps to be executed and exit.
If the .dmg distribution has been used to install XMLmind Word To XML on the Mac, the
following subdirectories are found in WordToXML.app/Contents/Resources/w2x/.
bin/w2x, w2x.bat
Scripts used to run XMLmind Word To XML (w2x for short). Use w2x on any Unix system. Use
w2x.bat on Windows.
bin/w2x-app.exe, w2x-app.jstart
File w2x-app.exe is used to start w2x-app, a graphical application easier to use than the w2x
command-line utility, on Windows. This .exe file is a home-made launcher parameterized by
xxe.jstart, an UTF-8 encoded, plain text file.
6
XMLmind Word To XML Manual
bin/w2x-app, w2x-app-c.bat
Scripts used to run w2x-app, a graphical application easier to use than the w2x command-line utility.
Use w2x-app on any Unix system. Use w2x-app-c.bat on Windows , but only when you need to
start w2x-app with a console. On Windows, a console is needed to be able to see low-level error
messages.
doc/index.html
Contains the documentation of w2x.
doc/manual/
Contains XMLMIND WORD TO XML MANUAL. This document is available in source DOCX format, in
PDF format and in all the output formats supported by w2x.
doc/manual/conv_manual.sh, conv_manual.bat
Scripts allowing to convert XMLMIND WORD TO XML MANUAL to all the output formats supported by
w2x. The files generated by these scripts are found in doc/manual/out/.
doc/xedscript/
Contains THE XED SCRIPTING LANGUAGE .
doc/w2x_app_help/
Contains the online help of w2x-app, a graphical application which is easier to use than the w2x
command-line utility.
doc/api/
Contains the reference manual of the Java™ API of w2x (generated using javadoc).
legal/, legal.txt
Contains legal information about w2x and about third-party components used in w2x.
lib/
All the (non-system) Java™ class libraries needed to run w2x:
w2x_all.jar: self-contained JAR containing everything needed to run w2x, that is, all the other JAR
files and also all the scripts and the stylesheets found in subdirectories xed/ and xslt/.
w2x_rt.jar: contains a runtime needed by the w2x engine. All these classes come from XMLmind
XML Editor.
wmf2svg.jar: WMF to SVG Converting Tool & Library; needed to support the WMF picture format.
7
XMLmind Word To XML Manual
xed/
Contains the XED scripts used to convert styles to semantic XHTML tags.
xslt/
Contains the XSLT 1.0 stylesheets used to generate semantic XML.
8
XMLmind Word To XML Manual
9
XMLmind Word To XML Manual
Because it’s a server-side component and not a desktop application, please do not attempt to
deploy the “Word To XML” servlet if you are an end-user of “Word To XML”. Please ask your
IT personnel to do that for you.
10
XMLmind Word To XML Manual
w2x.war
Ready-to-deploy Web application ARchive (WAR) containing the servlet.
src/
src/build.xml
The Java™ source code of the servlet. Run ant in src/ in order to use src/build.xml to rebuild
w2x.war.
w2x/
Directory containing unpacked w2x.war. Needed to rebuild w2x.war.
lib/
Contains Java™ libraries needed to rebuild w2x.war.
Though copying file w2x.war to the webapps/ folder of the servlet container and then restarting the
servlet container is generally sufficient to deploy the “Word To XML” servlet, please refer to the
documentation your servlet container to learn about the best deployment procedure.
All these init-param parameters are documented in web.xml. Example, parameter workDir:
Value: this directory and its contents must be readable and writable
by the operating system account used to run the Word To XML servlet.
<init-param>
<param-name>workDir</param-name><param-value></param-value>
</init-param>
11
XMLmind Word To XML Manual
Figure 2 The Convert DOCX form (servlet container running on host 192.168.1.202 and using port 8080)
If the name of the DOCX input file contains non-ASCII characters (e.g. accented characters),
please make sure to use Zip extractor software supporting .zip files having UTF-8 encoded
filenames.
12
XMLmind Word To XML Manual
Note that most Zip extractor software do not support .zip files having UTF-8 encoded
filenames1. Such extractors will succeed in unpacking the .zip file, but will generate files
having incorrect names.
cURL2 example:
curl -s -S -o manual_docbook5.zip \
-F "[email protected];type=application/vnd.openxmlformats-
officedocument.wordprocessingml.document" \
-F "conv=docbook5" \
http://localhost:8080/w2x/convert
Other example:
curl -s -S -o manual.epub \
-F "[email protected];type=application/vnd.openxmlformats-
officedocument.wordprocessingml.document" \
-F "conv=epub" \
-F "params=-p epub.identifier urn:x-mlmind:w2x:manual -p epub.split-before-level 8" \
http://localhost:8080/w2x/convert
docx
Emulated <input type=”file”> field. Required. Contains the DOCX input file.
conv
Emulated <input type=”text”> field. Required. Contains the name of one of the
conversionN.name init-param defined in WEB-INF/web.xml.
xhtml_css (single page styled HTML), frameset (multi-page styled HTML, split on Heading 1), frameset2 (multi-
page styled HTML, split on Heading 1, 2), frameset3 (multi-page styled HTML, split on Heading 1, 2, 3), webhelp (split
on Heading 1), webhelp2 (split on Heading 1, 2), webhelp3 (split on Heading 1, 2, 3), epub (split on Heading 1),
epub2 (split on Heading 1, 2), epub3 (split on Heading 1, 2, 3)
1
However, “jar xvf converted.zip” works fine. jar is a command-line utility which comes with all Java
Development Kits (JDK).
2
curl is an open source command line tool and library for transferring data with URL syntax.
13
XMLmind Word To XML Manual
params
Emulated <input type=”text”> field. Optional. Contains some w2x command-line options,
generally -p parameters. These options are appended to the options of the conversion specified in
the conv emulated form field.
The response to a successful conversion request is a .zip (or .epub) archive containing the result of the
conversion.
14
XMLmind Word To XML Manual
Note that Evaluation Edition is useless for any purpose other than evaluating XMLmind Word
To XML. This edition generates output containing random words replaced by string
"[XMLmind]". (Of course, this does not happen with Professional Edition!)
We’ll use this manual to explain the basic uses of the w2x command-line utility. This manual is found in
DOCX format in w2x_install_dir/doc/manual/ and the w2x command-line utility is found in
w2x_install_dir/bin/.
C:\w2x-1_5_0> cd doc\manual
C:\w2x-1_5_0\doc\manual> mkdir out
If you want to generate XHTML which is treated by Web browsers as if it were HTML, simply use
a .html file extension for the output file:
Doing this automatically turn on options3 which remove the XML declaration (<?xml
version=”1.0” encoding=”UTF-8”?>) normally found at the top of an XHTML file and insert a
<meta content=”text/html; charset=UTF-8” http-equiv=”Content-Type”/> into the
html/head element of the output document.
3
This option is “-p convert.charset UTF-8”. See charset parameter.
15
XMLmind Word To XML Manual
The above command generates multiple “.xhtml” files in the out\frameset directory which is
automatically created4 if needed to.
Note that out\frameset\manual.xhtml contains a frameset. While an obsolete HTML feature,
a frameset makes it easy browsing the generated XHTML+CSS pages. Moreover the table of
contents used as the left frame, found in out\frameset\manual-TOC.xhtml, is a convenient
way to programmatically list all the generated XHTML+CSS pages.
Convert manual.docx to out\webhelp\manual.html, containing a Web Help looking very much
like manual.docx:
The above command generates multiple “.html” files in the out\webhelp directory which is
automatically created if needed to.
Convert manual.docx to out\manual.epub, containing a EPUB 2 book looking very much like
manual.docx:
By default, the generated DocBook files contain HTML tables. If you prefer DocBook to contain
CALS tables, please use the following options:
..\..\bin\w2x –o docbook5
-p convert.set-column-number yes -p transform.cals-tables yes
manual.docx out\manual.xml
4
But not automatically made empty if the output directory already exists.
16
XMLmind Word To XML Manual
..\..\bin\w2x –o topic
-p transform.topic-type task -p transform.root-topic-id MyTask
manual.docx out\manual.dita
A new part is created each time a paragraph having an outline level less than or equal to specified
split-before-level parameter is found in the source. An outline level is an integer between 0 (e.g.
style “Heading 1”) and 8 (e.g. style “Heading 9”). The default value of parameter split-before-level
is 0, which means: for each “Heading 1”, create a new page starting with this “Heading 1”.
Frameset example: for each “Heading 1” and “Heading 2”, create a new page (out/frameset/manual-
1.xhtml, out/frameset/manual-2.xhtml, ..., out/frameset/manual-N.xhtml) starting with this
“Heading 1” or “Heading 2”:
..\..\bin\w2x -p split.split-before-level 1
–o frameset manual.docx out\frameset\manual.xhtml
EPUB example:
17
XMLmind Word To XML Manual
..\..\bin\w2x -p epub.split-before-level 1
–o epub manual.docx out\manual.epub
..\..\bin\w2x -p webhelp.split-before-level 1
–o webhelp5 manual.docx out\webhelp\manual.html
Important tip
Generating any of the multi-page, styled HTML formats should work great if, for the DOCX
document to be converted, you can use MS-Word's "References > Table of Contents" button
to automatically create a table of contents.
Note that the source DOCX document is not required to have a table of contents, but MS-
Word should allow to automatically create a good one.
In other words, automatically creating a table of contents using MS-Word is the best way to
check that your outline levels are OK.
18
XMLmind Word To XML Manual
1. Convert the DOCX file to a styled, valid, XHTML 1.0 Transitional document, looking very much
like the input DOCX file.
2. Apply a number of XED scripts to this document to convert CSS styles into semantic tags. For
example, numbered paragraphs are converted to proper ordered lists .
The entry point of these “semantic” XED scripts is found in w2x_install_dir/xed/main.xed.
The XED scripts edit in place the input XHTML document. Therefore, the result of this step is the
same XHTML document, still valid, but this time, containing no CSS styles whatsoever.
3. Apply an XSLT 1.0 stylesheet to the unstyled, valid, XHTML 1.0 Transitional document in order to
generate the desired semantic XML format.
The XSLT stylesheets are all found in w2x_install_dir/xslt/. In the above case, we want to
generate DocBook v5, therefore we use w2x_install_dir/xslt/docbook5.xslt.
This sequence of conversion steps can be made visible in every detail by specifying the –vv option (very
verbose) :
In fact, option –o docbook5 is a shorthand for the following w2x command-line options:
-c
Execute a Convert step called “convert”.
-p convert.xhtml-file C:\w2x-1_5_0\doc\manual\out\manual.xhtml
Pass the above xhtml-file parameter to the conversion step called “convert”.
19
XMLmind Word To XML Manual
-e
Execute an Edit step called “edit”.
-p edit.xed-url-or-file file:/C:/w2x-1_5_0/xed/main.xed
Pass the above xed-url-or-file parameter to the conversion step called “edit”.
-t
Execute a Transform step called “transform”.
-p transform.xslt-url-or-file file:/C:/w2x-1_5_0/xslt/docbook5.xslt
-p transform.out-file C:\w2x-1_5_0\doc\manual\out\manual.xml
Pass the above xslt-url-or-file and out-file parameters to the conversion step called
“transform”.
If you need to learn about the details of the conversion steps to be executed, the simplest is
to use the –liststeps command-line option.
Example: w2x –o docbook5 –liststeps.
The order of the –c, -e and –t options is significant because it means: first convert, then edit and finally
transform. The order of the –p (and –pu) options is not important, as a parameter name must be
prefixed by the name of the step to which it applies.
The Convert, Edit and Transform steps are the most important steps. There are other conversion steps
though, which are all documented in chapter Conversion step reference. Moreover a Java™ programmer
may implement its own custom conversion steps5 and instruct the w2x command-line to give them
names (required to pass them parameters) and to execute them. See option –step.
A w2x processor executes a sequence of conversion steps whatever the output format. Simply the
conversion steps, their order, number and parameters, depend on the desired output format. This is
depicted in the figure below.
5
A custom conversion step derives from abstract class com.xmlmind.w2x.processor.ProcessStep.
20
XMLmind Word To XML Manual
X M Lm in d W or d To X M L Pr oce ssor
XHTML+ XHTML+
CSS Edit CSS
Save XHTML+
(m ain-st yled.xed)
CSS
XHTML+ XHTML+
CSS Edit CSS Mult i-page
Split
(m ain-st yled.xed) XHTML+
CSS
XHTML+ XHTML+
CSS Edit CSS Web Help
(m ain-st yled.xed) generat or Web Help
DOCX Convert
XHTML+ XHTML+
CSS Edit CSS EPUB
(m ain-st yled.xed) generat or EPUB
DITA
bookm ap
The first sequence of in the above figure reads as follows: in order to convert a DOCX file to styled
XHTML, first convert the DOCX file to a XHTML+CSS document, then “polish up” this document (e.g.
process consecutive paragraphs having identical borders) using XED script w2x_install_dir/xed/main-
styled.xed, and finally save the possibly modified XHTML+CSS document to disk.
w2x_install_dir/xed/main-styled.xed
Invokes XED scripts used to “polish up” the styled XHTML 1.0 Transitional document created by the
Convert step (e.g. process consecutive paragraphs having identical borders).
w2x_install_dir/xed/main.xed
Invokes XED scripts used to prepare the generation of semantic XML of all kinds: XHTML, DocBook,
DITA. These scripts leverage the CSS styles and classes found in the styled XHTML 1.0 Transitional
document created by the Convert step. They translate these CSS styles and classes (e.g. numbered
paragraph) into semantic tags (e.g. ol/li).
Both the above “main” XED scripts are organized as sequences of simpler, short, XED scripts. Using –p or
–pu options, these short scripts may be replaced or removed and may be passed parameters. It’s also
possible to insert custom scripts before or after any of these short scripts.
21
XMLmind Word To XML Manual
script(defined("before.init-styles", ""));
script(defined("do.init-styles", "init-styles.xed"));
script(defined("after.init-styles", ""));
script(defined("before.title-styled", ""));
script(defined("do.title-styled", "title-styled.xed"));
script(defined("after.title-styled", ""));
script(defined("before.remove-pis", ""));
script(defined("do.remove-pis", "remove-pis.xed"));
script(defined("after.remove-pis", ""));
script(defined("before.expand-tabs", ""));
script(defined("do.expand-tabs", "expand-tabs.xed"));
script(defined("after.expand-tabs", ""));
script(defined("before.borders", ""));
script(defined("do.borders", "borders.xed"));
script(defined("after.borders", ""));
script(defined("before.number-footnotes", ""));
script(defined("do.number-footnotes", "number-footnotes.xed"));
script(defined("after.number-footnotes", ""));
script(defined("before.finish-styles", ""));
script(defined("do.finish-styles", "finish-styles.xed"));
script(defined("after.finish-styles", ""));
Examples:
-p edit.do.title-styled “”
-p edit.finish-styles.css-uri css/manual.css
By convention (this is not strictly required), the name of a parameter which applies to a given
XED script is prefixed with the basename without any file extension of this script. Hence the full
names of most parameters of Edit steps have the following syntax:
step_name.script_name.parameter_name. Examples:
-p edit.prune.preserve “p-ProgramListing”
22
XMLmind Word To XML Manual
23
XMLmind Word To XML Manual
<style type="text/css">
body {
counter-reset: n-1-0 0 n-1-1 0 n-1-2 0 n-17-0 0 n-20-0 0;
font-family: Calibri;
font-size: 11pt;
}
...
</style>
A XED script allows to modify, not only the nodes of an XHTML document, but also its “CSS styles”.
These “CSS styles” may be either style properties contained in the style attribute of an element or class
names found in the class attribute of an element or the CSS rules of the document.
Therefore, when the desired customization is limited, suffice to execute a XED script in order to modify
the XHTML+CSS document created by the Convert step. Example:
The above line adds CSS property “white-space: pre;” to the CSS rule having “.p-ProgramListing” as
its selector. This CSS rule corresponds to custom paragraph6 style called “ProgramListing”.
Besides XED command set-rule, the following commands allow to edit the CSS styles contained in the
XHTML+CSS document created by the Convert step: add-class, add-rule, remove-class, remove-
rule, set-style.
6.1.2 Appending custom styles to the styles embedded in the XHTML+CSS file
XED script w2x_install_dir/xed/finish-styles.xed has a optional custom-styles-url-or-file
parameter which makes it easy customizing the automatically generated CSS styles.
6
It’s a paragraph style because the CSS style name has a “p-“ prefix.
24
XMLmind Word To XML Manual
This parameter may be used to specify the location of a CSS file. The custom CSS styles found in
specified file are simply appended to the automatically generated CSS styles. Example:
Example:
body {
font-family: sans-serif;
}
.p-Heading1,
.p-Heading2,
.p-Heading3,
.p-Heading4,
.p-Heading5,
.p-Heading6 {
font-family: serif;
color: #17365D;
padding: 1pt;
border-bottom: 1pt solid #4F81BD;
margin-bottom: 10pt;
margin-left: 0pt;
text-indent: 0pt;
}
.p-Heading1 {
border-bottom-width: 2pt;
}
...
.c-FootnoteReference,
.c-EndnoteReference {
font-size: smaller;
}
6.1.3 Using an external CSS file rather than embedded CSS styles
XED script w2x_install_dir/xed/finish-styles.xed has a optional css-uri parameter which allows
to specify the CSS file where all CSS rules, whether automatically generated or custom, are to be saved.
Same example as above but using an external CSS file rather than embedded CSS styles:
25
XMLmind Word To XML Manual
All the CSS styles, whether automatically generated or the custom ones found in
customize\custom.css, end up in manual_restyled_css\manual.css. Moreover,
out\manual_restyled.html contains a link to manual_restyled_css\manual.css.
<link href="manual_restyled_css/manual.css"
rel="stylesheet" type="text/css"/>
for-each /html/body/p[get-class("^p-Heading\d$")] {
set-variable("class", get-class("^n-\d+-\d+$"));
if $class != '' {
set-variable("selector", concat(".", $class, ":after"));
if find-rule($selector) >= 0 {
remove-rule($selector);
.n-1-0:after {
clear: both;
content: "";
display: block;
}
.n-1-0:before {
content: counter(n-1-0);
26
XMLmind Word To XML Manual
counter-increment: n-1-0;
float: left;
width: 21.6pt;
}
which becomes:
.n-1-0:before {
content: counter(n-1-0) " ";
counter-increment: n-1-0;
display: inline;
}
This script is useful because otherwise adding a bottom border to headings gives an ugly result. While
the contents of the heading is “underlined”, the CSS float containing the numbering value of the
heading is not.
Besides get-class, the following XPath extension functions may be used to access the CSS styles
contained in the XHTML+CSS document created by the Convert step: find-rule, font-size, get-rule,
get-style, lookup-length, lookup-style, style-count.
The answer is: because all class attributes have been removed by XED script
w2x_install_dir/xed/init-styles.xed.
This script “interns” the CSS rules found in the html/head/style element of the XHTML+CSS
document, the CSS styles directly set on some elements and the CSS classes set on some
elements.
27
XMLmind Word To XML Manual
Example 1: convert text spans having a “Code” character style to XHTML element code:
Notice that the name of character style in the generated XHTML+CSS file is always prefixed
by “c-“.
Example 2: in addition to what’s done in above example 1, convert text spans having a “Abbrev”
character style to XHTML element abbr having a title=”???” attribute:
What if the semantic XHTML created by the Edit step is then converted to DITA or DocBook by the
means of a Transform step?
In the case of XHTML elements code and abbr, there is nothing else to do because the stock XSLT
stylesheets already support these elements:
The general case which also requires using custom XSLT stylesheets is explained in section The general
case.
Example 1.a: convert paragraphs having a “ProgramListing” paragraph style to XHTML element pre:
28
XMLmind Word To XML Manual
Notice that the name of paragraph style in the generated XHTML+CSS file is always prefixed
by “p-“.
If you use the above blocks.convert specification, it will work fine, except that you’ll end up with
several consecutive pre elements (one pre per line of program listing). This is clearly not what you want. You
want consecutive pre elements to be merged into a single pre element. Fortunately implementing this
too is quite simple.
Example 1.b: convert paragraphs having a “ProgramListing” paragraph style to XHTML element span
(having grouping attributes; more about this below):
When any of the target XHTML elements have grouping attributes (g:id='pre'7, g:container='pre',
in the above example), then w2x_install_dir/xed/blocks.xed automatically invokes the group()
command at the end of the conversions. This has the effect of grouping consecutive <span g:id='pre'
g:container='pre'> into a common pre parent element.
Given the fact that XED command group() automatically removes grouping attributes when done and
that w2x_install_dir/xed/finish.xed discards all useless span elements, this leaves us with clean
pre elements containing text8.
Example 3: in addition to what’s done in above example 1.b, convert paragraphs having a “Term”
paragraph style to XHTML element dt, convert paragraphs having a “Definition” paragraph style to
XHTML element dl and group consecutive dt and dl elements into a common dl parent:
7
Any value would do (e.g. g:id=”foo” would have worked as well). Suffice for consecutive elements to be
grouped to all have the same g:id attribute.
8
Unless you specify:
-p edit.prune.preserve "p-ProgramListing"
script w2x_install_dir/xed/prune.xed will cause open lines to be stripped from the generated pre element.
29
XMLmind Word To XML Manual
What if the semantic XHTML created by the Edit step is then converted to DITA or DocBook by the
means of a Transform step?
In the case of XHTML elements pre, dt, dd and dl, there is nothing else to do because the stock XSLT
stylesheets already support these elements.
The general case which also requires using custom XSLT stylesheets is explained in section The general
case.
For example, let’s suppose we want to group all the paragraphs having a “Note” paragraph style and to
generate for such groups DocBook and DITA note elements.
The following blocks.convert parameter would allow to very easily create the desired groups:
a. A paragraph having a “Note” paragraph style often starts with bold text “Note:”. We want to
eliminate this redundant label.
b. The stock XSLT stylesheets will not convert XHTML element <div class=”role-note”> to a
DocBook or DITA note element.
namespace "http://www.w3.org/1999/xhtml";
namespace html = "http://www.w3.org/1999/xhtml";
namespace g = "urn:x-mlmind:namespace:group";
for-each /html/body//p[get-class("p-Note")] {
delete-text("note:\s*", "i");
if content-type() <= 1 and not(@id) {
delete();
} else {
remove-class("p-Note");
set-attribute("g:id", "note_group_member");
set-attribute("g:container", "div class='role-note'");
}
}
30
XMLmind Word To XML Manual
group();
The “Note:” label, if any, is deleted using XED command delete-text. If doing this creates a useless
empty (content-type() <= 1) paragraph, then delete this paragraph using XED command delete.
The above script is executed after stock script w2x_install_dir/xed/blocks.xed by the means of the
following w2x command-line option:
<xsl:stylesheet version="1.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:h="http://www.w3.org/1999/xhtml"
exclude-result-prefixes="h">
<xsl:import href="w2x:xslt/topic.xslt"/>
This stylesheet, which imports stock w2x_install_dir/xslt/topic.xslt, is used for the topic, map
and bookmap output formats (see –o option). Similar, very simple, stylesheets have been developed for
the docbook and docbook5 output formats.
The above stylesheet replaces the stock one by the means of the following w2x command-line option:
-o topic -t customize\custom_topic.xslt
Do not forget to specify the –t option after the –o option, because it’s the –o option which implicitly
invokes stock w2x_install_dir/xslt/topic.xslt (this has been explained in chapter Going further with w2x)
and we want to use –t to override the use of the stock XSLT stylesheet.
31
XMLmind Word To XML Manual
Tip: You’ll find a template for custom XED scripts and several templates for custom XSLT
stylesheets in w2x_install_dir/doc/manual/templates/.
32
XMLmind Word To XML Manual
-c
Execute a Convert step called “convert”.
-e
Execute an Edit step called “edit”.
-pu edit.xed-url-or-file w2x:xed/main.xed
Pass this stock XED script (converting the styled XHTML 1.0 Transitional created by the Convert
step to “semantic” XHTML) to the conversion step called “edit”.
-t
Execute a Transform step called “transform”.
-pu transform.xslt-url-or-file "C:\Users\John\foo\xsl\xhtml_to_foo.xsl"
Pass your custom XSLT 1.0 stylesheet to the conversion step called “transform”.
Stock XED script w2x:xed/main.xed creates a number of semantic XHTML elements having a class
attribute starting with “role-“. Examples: <div class=”role-section1”>, <div class=”role-
section2”>, <div class=”role-figure”>, <div class=”role-figcaption”>, <a class=”role-
footnote-ref”>, <div class=”role-footnote”>, <a class=”role-xref”>, <span class=”role-
index-term”>, etc. To learn how to process these elements, the simplest is to look how this is done in a
stock XSLT stylesheet such as “w2x_install_dir/xslt/topic.xslt” or
“w2x_install_dir/xslt/docbook.xslt”.
33
XMLmind Word To XML Manual
If the .dmg distribution has been used to install XMLmind Word To XML on the Mac, the w2x
command-line utility is found in WordToXML.app/Contents/Resources/w2x/bin/.
Options are:
-o format
This option automatically adds all the steps needed to convert input DOCX file to an output file
having specified format.
Possible formats: docbook, docbook5, topic, map, bookmap, xhtml_css (single-page styled HTML, that is,
single-page XHTML+CSS), xhtml_strict, xhtml_loose, xhtml1_1, xhtml5, frameset (multi-page styled
HTML), frameset_strict (multi-page XHTML 1.0 Strict), frameset_loose (multi-page XHTML 1.0 Transitional),
frameset1_1 (multi-page XHTML 1.1), frameset5 (multi-page XHTML 5.0), webhelp (Web Help containing styled
HTML), webhelp_strict (Web Help containing XHTML 1.0 Strict), webhelp_loose (Web Help containing
XHTML 1.0 Transitional), webhelp1_1 (Web Help containing XHTML 1.1), webhelp5 (Web Help containing
XHTML 5.0), epub (EPUB 2 containing styled XHTML 1.1), epub1_1 (EPUB 2 containing semantic XHTML 1.1).
The default output format is: xhtml_css (single-page styled HTML, that is, single-page XHTML+CSS).
-p name value
Set parameter name to value.
Because they are used to parameterize named steps, the order of –p and –pu options relatively to
options specifying conversions steps (-c, -e, -t, -step, etc) is not significant. For example: “-p
convert.charset UTF-8 -c” is equivalent to “-c -p convert.charset UTF-8”.
URL_or_file is an absolute or relative URL (relative to current -f options file if any, to current
working directory otherwise) or the filename of an existing file or directory.
-c
Add or replace “convert” step. This step converts input DOCX file to an in-memory XHTML +CSS
document.
-l
Add or replace “load” step. This step, mainly used to test XED scripts, loads input XML file.
34
XMLmind Word To XML Manual
-e xed_URL_or_file
Add or replace “edit” step. This step edits in place input XHTML document using XED script
xed_URL_or_file.
-e2 xed_URL_or_file
Add or replace “edit2” step. This step edits in place input XHTML document using XED script
xed_URL_or_file.
-t xslt_URL_or_file
Add or replace “transform” step. This step transforms input XML document or file using XSLT
stylesheet xslt_URL_or_file.
-t2 xslt_URL_or_file
Add or replace “transform2” step. This step transforms input XML document or file using XSLT
stylesheet xslt_URL_or_file.
-s
Add or replace “save” step. This step saves to disk input XHTML document.
-step:java_class_name:step_name
Add or replace step called step_name by an instance of Java™ class java_class_name deriving from
com.xmlmind.w2x.processor.ProcessStep.
-f options_URL_or_file
Load one or more of the above options from options_URL_or_file, a plain UTF-8 text file
-v
-vv
-vvv
Verbose. More Vs means more verbose.
-version
Print version number and exit.
-liststeps
List the conversion steps to be executed and exit. This option is useful to determine how to
customize the conversion steps. Example:
35
XMLmind Word To XML Manual
-step:com.xmlmind.w2x.processor.ConvertStep:convert
-p convert.create-mathml-object no
-p convert.set-column-number yes
-step:com.xmlmind.w2x.processor.EditStep:edit
-p edit.xed-url-or-file file:/opt/w2x/xed/main.xed
-step:com.xmlmind.w2x.processor.TransformStep:transform
-p transform.out-file %{~pnO}.dita
-p transform.single-topic no
-p transform.xslt-url-or-file file:/opt/w2x/xslt/topic.xslt
-step:com.xmlmind.w2x.processor.TransformStep:transform2
-p transform2.xslt-url-or-file file:/opt/w2x/xslt/bookmap.xslt
-p transform2.topic-type %{transform.topic-type}
-p transform2.output-path %{~po}
-step:com.xmlmind.w2x.processor.DeleteFilesStep:cleanUp
-p cleanUp.files %{~pnO}.dita
7.1 Variables substituted in the parameter values passed to the –p and –pu
options
The following variables are substituted in the parameter values passed to the –p and –pu options.
Variables %{I}, %{O}, %{i} and %{o} may all contain one or more of following modifiers. First modifier
must be preceded by character “~”.
Modifier Description
n The name of the file or URL without any extension.
x The extension of the file or URL. Starts with “.”.
p The full path of the parent directory of the file or URL.
Note that combinations of modifiers other than “~nx”, “~pn”, “~pnx” do not make sense and that, for
example, %{~pnxI} is equivalent to %{I}.
36
XMLmind Word To XML Manual
-c
-e
-p edit.xed-url-or-file w2x:xed/main-styled.xed
-s
The above options convert the input DOCX file to clean, styled, valid XHTML. The resulting output file is
not indented.
If the last conversion step is a Save step, Transform step, Split step, Web Help step or EPUB step the
following parameters are automatically added by w2x (unless, of course, they have already been specified by the
user):
37
XMLmind Word To XML Manual
However when you’ll pass any of the following parameters to w2x, please do not forget this
prefix. Example: -p convert.resource-directory images.
Parameters:
38
XMLmind Word To XML Manual
9
Because only XHTML 5 documents may embed MathML. With any other version of XHTML, this would cause the
document to become invalid.
39
XMLmind Word To XML Manual
40
XMLmind Word To XML Manual
This step is used for example when generating a DITA map or bookmap. It is used to delete the
intermediate topic file created by the first Transform step.
Parameters (for clarity, the “cleanUp.” parameter name prefix is omitted here):
However when you’ll pass any of the following parameters to w2x, please do not forget this
prefix. Example: -p edit.ids.generate-section-ids yes.
41
XMLmind Word To XML Manual
Parameters:
Any other parameter is passed to the XED script as a XED global variable.
XMLmind Word to XML (w2x for short) comes with two stock “main” XED scripts:
w2x:xed/main-styled.xed
Invokes XED scripts used to “polish up” the styled XHTML 1.0 Transitional document created by the
Convert step (e.g. process consecutive paragraphs having identical borders).
w2x:xed/main.xed
Invokes XED scripts used to prepare the generation of semantic XML of all kinds: XHTML, DocBook,
DITA. These scripts leverage the CSS styles and classes found in the styled XHTML 1.0 Transitional
document created by the Convert step. They translate these CSS styles and classes (e.g. numbered
paragraph) into semantic tags (e.g. ol/li).
42
XMLmind Word To XML Manual
yes
Add a <script> element loading MathJax to
the <html>/<head> element of the generated
XHTML file.
auto
Same as “yes”, but add <script> only when
the generated XHTML file contains MathML.
finish- String. Global variable defined in w2x:xed/finish-
styles.mathjax-url
Default value: the URL styles.xed.
pointing to the The URL allowing to load the MathJax engine
MathJax CDN, as configured for rendering MathML.
recommended in the Ignored unless parameter mathjax is set to “yes”
MathJax or “auto”.
documentation.
title.keep-title “yes” | “no” Global variable defined in w2x:xed/title.xed.
Default: “yes” when Default value “no” specifies that paragraphs
generating styled or having “p-Title” and “p-Subtitle” styles (to
semantic XHTML of all make it simple; see also parameters
kinds (single-page, title.title-style-names and
43
XMLmind Word To XML Manual
44
XMLmind Word To XML Manual
45
XMLmind Word To XML Manual
46
XMLmind Word To XML Manual
47
XMLmind Word To XML Manual
48
XMLmind Word To XML Manual
Above parameter blocks.convert (respectively inlines.convert) provides the user of w2x with a
simple mean to convert p (respectively span) elements having certain paragraph (respectively
character) styles to XHTML elements possibly having attributes.
49
XMLmind Word To XML Manual
Note that when specifying a XHTML_element_qname, you must restrict yourself to XHTML 1.0
Transitional elements. Specifying for example, XHTML 5.0 elements such as mark, aside, section, etc,
will not give you the results you’ll expect.
/Emphasis$/ em !
c-Strong strong !
c-BookTitle cite !
/((IntenseReference)|(SubtleReference)|(QuoteChar))$/ em !
/((itleChar)|(Heading\d+Char))$/ strong
c-Code code
Automatic grouping of the XHTML elements which are the results of the styled paragraph conversions
In the above examples, attributes having names prefixed with “g:” are in the “urn:x-
mlmind:namespace:group” namespace. These attributes are called grouping attributes. Examples:
g:id, g:container.
When parameter blocks.convert is used to create XHTML elements having grouping attributes,
command group() is automatically invoked at the end of all the styled paragraph conversions. To make
it simple, this command groups consecutive XHTML elements having the same g:id attribute into a
common parent element. The parent element is specified by attribute g:container.
50
XMLmind Word To XML Manual
By default, when generating styled HTML (that is, XHTML+CSS), some JavaScript™ code
(w2x_install_dir/xed/expand-tabs.js) is added to the output file. This code computes
and gives a width to all <span class=”role-tab> </span>. This allows to decently emulate
tab stops in any modern Web browser. More information in About tab stops.
However, this cannot work in the case of the EPUB 2 output format because scripting is
disabled in the styled HTML pages comprising an EPUB book.
Same parameters as the Split step, plus the following EPUB specific parameters (for clarity, the “epub.”
parameter name prefix is omitted here):
51
XMLmind Word To XML Manual
Note that if loaded file starts with a <!DOCTYPE> pointing to a DTD, then a document loader created by
this step will not attempt to load this DTD. The document loader will behave as if the <!DOCTYPE> was
absent.
No parameters.
Parameters (for clarity, the “save.” parameter name prefix is omitted here):
out-file A file path. Specifies the path of the save file. A relative file
No default (required). path is relative to the current working directory.
This step also generates a frameset and a table of contents used as the left frame of the frameset.
While an obsolete HTML feature, a frameset makes it easy browsing the generated pages. Moreover the
table of contents used as the left frame is a convenient way to programmatically list all the generated
pages.
52
XMLmind Word To XML Manual
The result of the this step is the file containing the frameset.
However when you’ll pass any of the following parameters to w2x, please do not forget this
prefix. Example: -p split.split-before-level 8.
Parameters:
out-file A file path. Specifies the path of the file containing the
No default (required). frameset. A relative file path is relative to the
current working directory.
This step always generates several files, all in the
same directory as file out-file.
This output directory is created on the fly if
needed too. However, the output directory, if it
already exists, is not automatically made empty.
The file specified by out-file contains
the frameset. Let’s suppose out-file is
temp\foo.html.
The table of contents of the frameset, its
left frame, is created in temp\foo-
TOC.html.
Unless parameter use-id-as-filename
has been specified as true, the styled
HTML pages are created in temp\foo-
53
XMLmind Word To XML Manual
use-id-as-filename A boolean: true (same By default, the save files of the generated pages
as: yes | on | 1) | false have the same basename as out-file, except
(same as: no | off | 0). that a number is appended to this basename.
Default: false. Example: out-file is temp\foo.html; the save
files of the generated pages are thus: temp\foo-
0.html, temp\foo-1.html, temp\foo-2.html, …,
temp\foo-N.html.
In a MS-Word document, a heading is often given
a bookmark. The Convert step translates this
bookmark to an ID. When use-id-as-filename
is specified as true, the save file of a page is
given a basename corresponding to the ID of the
heading used to start this page. When this
heading ID is missing, the Split step fallbacks to
the default behavior.
Unlike the load step, if the input XML file starts with a <!DOCTYPE> pointing to a DTD, then the
document loader created by a Transform step will silently skip this DTD.
For clarity, the “transform.” or “transform2.” parameter name prefix is omitted here.
54
XMLmind Word To XML Manual
However when you’ll pass any of the following parameters to w2x, please do not forget this
prefix. Example: -p transform.cals-tables yes.
Parameters:
Any other parameter is passed to the XSLT stylesheet as an XSLT stylesheet parameter. Which XSLT
stylesheet parameters are supported depend on the XSLT stylesheet being used.
55
XMLmind Word To XML Manual
56
XMLmind Word To XML Manual
Table 7 Parameters of w2x:xslt/map.xslt, bookmap.xslt, which are used to convert input DITA
topic file to a map or bookmap
57
XMLmind Word To XML Manual
This step always generates UTF-8 encoded, “.html” files, no matter the parameters specifying other
values.
58
XMLmind Word To XML Manual
Same parameters as the Split step, plus the following Web Help specific parameters (for clarity, the
“webhelp.” parameter name prefix is omitted here):
59
XMLmind Word To XML Manual
About thread-safety
It’s strongly recommend not to reuse an instance of Processor. That is, please create one
instance of Processor per conversion.
The reference manual (generated using javadoc) of the Java API of w2x is found in XMLmind Word To XML
Java™ API.
int l = processor.configure(args);
10
Apache Ant is a command-line utility for automating software build processes. By default, ant uses an XML file,
called build.xml to describe the build process and its dependencies. In the case of the two above code samples,
this file is w2x_install_dir/doc/manual/embed/build.xml.
60
XMLmind Word To XML Manual
processor.parameterMap.put("edit.xed-url-or-file",
"w2x:xed/main-styled.xed");
processor.parameterMap.put("save.indent", "yes");
com.xmlmind.w2x.docx.image.ImageConverterFactoryImpl
Image converter factory used to convert TIFF images to PNG or JPEG.
com.xmlmind.w2x_ext.wmf_converter.WMFConverterFactory
Image converter factory used to convert WMF graphics to SVG.
61
XMLmind Word To XML Manual
com.xmlmind.w2x_ext.emf2png.EMF2PNG
This image converter factory is available only on Windows. It leverages Windows own GDI+ to
convert EMF (in fact, Windows metafiles of any kind, including WMF) to PNG.
This is not that great because, unlike above WMFConverterFactory which converts WMF (Windows
vector graphics format) to SVG (standard vector graphics format), EMF2PNG converts a vector graphics format
to a raster image format. However, having EMF2PNG is better than nothing at all.
EMF2PNG has one parameter called resolution. Its value is a real number expressed in Dot Per Inch
(DPI). The default value of parameter resolution is 0.0 (see below).
The resolution parameter specifies the resolution of the output PNG file. 0 means: same
resolution as the one found input EMF/WMF file; a positive number means: use this value to
override the resolution found in the input EMF/WMF file; a negative number means: use specified
absolute value but only if this absolute value is greater than the resolution found in the input
EMF/WMF file.
com.xmlmind.w2x.docx.image.ExternalImageConverter
This image converter factory executes an external program to perform the conversion. See 9.1.2.1
below.
If you want w2x to support more image formats, you’ll have to create your own
ImageConverterFactory and register it with w2x using method ImageConverterFactories.register.
About thread-safety
The command executed by an external image converter may contain the following variables:
62
XMLmind Word To XML Manual
Variable Definition
%I Absolute path of the input image file.
%O Absolute path of the output image file.
%i Same as %I but quoted, that is, equivalent to “%I”.
%o Same as %O but quoted, that is, equivalent to “%O”.
%S File separator: “\” on Windows, “/” on Mac/Linux.
The following modifiers may be applied to the %I, %O, %i, %o variables:
Modifier Definition
~p Absolute path of the parent directory of the file. For example, if %I is
“C:\temp\doc_files\logo.wmf”, then %~pI is “C:\temp\doc_files”.
~n Basename of the file. For example, if %I is “C:\temp\doc_files\logo.wmf”,
then %~nI is “logo.wmf”.
~r Basename of the file without any extension. For example, if %I is
“C:\temp\doc_files\logo.wmf”, then %~rI is “logo”.
~e Extension of the file. For example, if %I is “C:\temp\doc_files\logo.wmf”,
then %~eI is “wmf”.
Also note that “%%” may be used to escape character “%”. More generally, just like in an URL, an %HH UTF-
8 sequence may be used to escape any character. Example: “%3B” is “;” (semi colon), “%C3%A9” is “é”
(“e” with acute accent).
9.1.2.2 Controlling how image files found in the input DOCX file are converted to
standard formats
Conversion of images found in the DOCX file (TIFF, WMF, EMF, etc) to standard formats (SVG, PNG,
JPEG) may be controlled using environment variable (or Java™ property) W2X_IMAGE_CONVERSIONS.
.wmf.svg java:com.xmlmind.w2x_ext.wmf_converter.WMFConverterFactory;
.tiff.png java:com.xmlmind.w2x.docx.image.ImageConverterFactoryImpl
.wmf.svg java:com.xmlmind.w2x_ext.wmf_converter.WMFConverterFactory;
.emf.png.wmf.png java:com.xmlmind.w2x_ext.emf2png.EMF2PNG resolution 0;
.tiff.png java:com.xmlmind.w2x.docx.image.ImageConverterFactoryImpl
63
XMLmind Word To XML Manual
.wmf.svg java:com.xmlmind.w2x_ext.wmf_converter.WMFConverterFactory;
.emf.png.wmf.png java:com.xmlmind.w2x_ext.emf2png.EMF2PNG resolution 0;
.tiff.png java:com.xmlmind.w2x.docx.image.ImageConverterFactoryImpl
Note that the image conversion specifications are considered in the order of their declarations
in variable W2X_IMAGE_CONVERSIONS. In the case of the above example, it’s custom “magick
convert %i %o” which is used to convert EMF to PNG and not stock
“java:com.xmlmind.w2x_ext.emf2png.EMF2PNG resolution 0”.
64
XMLmind Word To XML Manual
By “does not support”, we mean that w2x will not generate something useful corresponding to such
features. We don’t mean that using such features in a DOCX file would cause w2x to fail or to generate
invalid XML documents.
The Convert step generates XHTML+CSS documents having the following specificities:
Tab stops are converted to <span class=”role-tab> </span>. See About tab stops.
MS-Word document properties having no standard meta equivalent are given names starting
with “ms-”. Example:
MS-Word “styles” having no CSS equivalent are a given a “-ms-” prefix. Example:
.p-Heading3 {
-ms-outlineLvl: 2;
color: #4F81BD;
font-family: Cambria;
...
65
XMLmind Word To XML Manual
Page breaks are translated to <?break-page?>. Column breaks are translated to <?break-
column?>. End of sections are signaled by <?end-of-section?>.
WMF pictures are converted to SVG.
−𝑏±√𝑏2 −4𝑎𝑐
OpenXML math, for example 𝑥 = 2𝑎
, is converted to MathML.
Conversion from OpenXML math to MathML is implemented by an XSLT 1.0 stylesheet called
omml2mml.xsl coming from open source project XSL stylesheets for TEI XML. If you think you
have access to a better XSLT stylesheet than open source omml2mml.xsl, then you may use it by
specifying environment variable (or Java™ system property) W2X_MATH_CONVERTER_XSLT. Example:
All simple and most complex fields are converted to a <?field code?> having a <span
class="role-field"> parent. Example:
<span class="role-field">
<?field DATE \@ "MMMM d, yyyy" \* MERGEFORMAT ?>
August 27, 2014
</span>
Smart tags are enclosed between <?begin-smartTag tag?> and <?end-smartTag tag?>.
Example:
<?begin-smartTag {urn:schemas-microsoft-com:office:smarttags}PersonName#0?>
<?begin-smartTag {urn:schemas:contacts}GivenName#1?>
Bill
<?end-smartTag {urn:schemas:contacts}GivenName#1?>
<?begin-smartTag {urn:schemas:contacts}Sn#2?>
Gates
<?end-smartTag {urn:schemas:contacts}Sn#2?>
<?end-smartTag {urn:schemas-microsoft-com:office:smarttags}PersonName#0?>
<?begin-sdt comboBox#6?>
<?end-sdt comboBox#6?>
66
XMLmind Word To XML Manual
The language of DOCX files written in an East Asian language is not correctly detected.
Unfortunately, this will always be the case because w2x never examines the characters actually
contained in a text span having <w:lang w:eastAsia="ja-JP" w:val="en-US"/> to determine
whether this text span is written in ja-JP or is written in en-US or is written is a mix of both
languages.
However, a partial workaround for this limitation is to specify for example –p convert.set-
lang ja-JP or –p convert.default-lang ja-JP. When parameter convert.set-lang or
parameter convert.default-lang is set to a language code starting with ja, zh or ko, then it is
attribute w:lang/@w:eastAsia which is used to determine the language of a text span and not
attribute w:lang/@w:val.
Note that –p convert.default-lang ja-JP is just used as a hint to favor attribute
w:lang/@w:eastAsia over attribute wlang/@w:val. Given the way MS-Word sets these two
attributes, using parameter –p convert.default-lang ja-JP will not cause a vastly incorrect
detection of the language when converting a German DOCX file for example.
w2x can generate DITA indexterm elements having index-sort-as children and DocBook
indexterm/primary, secondary, tertiary elements having sortas attributes. For this to
happen, the input DOCX file must contain XE (index entry) fields having \y "yomi" (first phonetic
character for sorting indexes) field arguments.
Unlike MS-Word which considers \y "yomi" only for East Asian languages, w2x uses this XE field
argument to sort the index entries whatever the language of the document. English examples:
{XE "<span>" \y "span"}, {XE "Operation:+" \y ":Addition"}.
When generating styled HTML (that is, XHTML+CSS), some JavaScript™ code
(w2x_install_dir/xed/expand-tabs.js) is added to the output file. This code computes and gives
a width to all <span class=”role-tab> </span>. This allows to decently emulate tab stops in any
modern Web browser.
If you don't want this code to be added to the output file, pass option -p edit.do.expand-tabs ""
to w2x.
When generating semantic XHTML and all the other semantic XML formats (DocBook, DITA, etc), it's
possible to convert consecutive paragraphs containing text runs aligned on tab stops to a borderless
table.
However because, in the general case, it's not possible to emulate tab stops using tables, this XED
script is disabled by default. If you really want to emulate tab stops using tables, pass option -
p edit.convert-tabs.to-table yes to w2x.
67
XMLmind Word To XML Manual
Index
E L
-e, option ........................................................ 20, 33, 35, 37 -l, option ........................................................................... 34
-e2, option ........................................................................35 -liststeps, option ......................................................... 20, 35
Edit, step ...........................................................................41 Load, step ......................................................................... 51
encoding, parameter ........................................................52 lower-case-resource-names, parameter .......................... 40
68
XMLmind Word To XML Manual
P U
-p, option .................................................................... 34, 37 us-id-as-filename, parameter ........................................... 54
-p, parameter .............................................................. 19, 20
pre-element-name, parameter .........................................56
V
prune.preserve, parameter ..............................................49
-pu, option ........................................................................34 -v, option .......................................................................... 35
-pu, parameter ..................................................................20 -version, option ................................................................ 35
version, parameter ........................................................... 41
R -vv, option .................................................................. 19, 35
-vvv, option ...................................................................... 35
remove-pis.except, parameter .........................................45
remove-styles.preserved-classes, parameter ...................49
W
resource-directory, parameter .........................................40
resource-prefix, parameter...............................................40 w2x-app ...................................................................... 6, 7, 9
root-topic-id, parameter ...................................................56 Web Help, output format ................................16, 17, 54, 58
webhelp.add-index, parameter ........................................ 59
S
X
-s, option ..................................................................... 35, 37
Save, step ..........................................................................52 xed-url-or-file, parameter ................................................ 42
section-depth, parameter .................................................58 XHTML 1.0 Strict, output format ...................................... 17
sections.max-level, parameter .........................................49 XHTML 1.0 Transitional, output format............................ 17
servlet ...............................................................................10 XHTML 1.1, output format ............................................... 17
curl ...............................................................................13 XHTML 5.0, output format ............................................... 17
multipart/form-data ....................................................13 XHTML, output format ............................................... 15, 17
POST .............................................................................13 xhtml-file, parameter ....................................................... 41
set-column-number, parameter .......................................40 XMLmind Web Help Compiler .................................... 58, 59
set-lang, parameter .................................................... 40, 67 XMLmind XML Editor add-on ............................................. 9
shortdesc-class-name, parameter ....................................56 xslt-url-or-file, parameter ................................................. 55
69