User's manual for

Writer2LaTeX, Writer2BibTeX, Writer2xhtml and Calc2xhtml

version 1.2

© 2002–2012 Henrik Just

1 Introduction

1.1 What is Writer2LaTeX?

Writer2LaTeX is a utility to convert OpenDocument text and spreadsheet documents1 – in particular documents containing formulas – into other formats.

Actually it is a collection of four converters:

• Writer2LaTeX converts OpenDocument text documents to LaTeX 2e, and works together with...

• Writer2BibTeX which extracts bibliographic data from an OpenDocument text document and converts it to BibTeX format.

• Writer2xhtml converts OpenDocument text documents to XHTML 1.0 strict, XHTML 1.1, XHTML 1.1 + MathML 2.0 or EPUB using CSS2 to convert style information.

• Calc2xhtml converts OpenDocument spreadsheet documents to XHTML 1.0 strict or XHTML 1.1, using CSS2 to convert style information.

Although Writer2LaTeX is a general OpenDocument converter, it is primarily designed for use with OpenOffice.org and it's derivatives (e.g. StarOffice or NeoOffice). You can use Writer2LaTeX

• ...as an export filter for OpenOffice.org 3.0 or later2, or equivalent versions of StarOffice or NeoOffice3.

• ...as a command line utility, independent of OpenOffice.org.

• ...as a Java library providing conversions from OpenDocument for other Java programs.

Writer2LaTeX is a Java application, and thus should work on any platform that supports Java. You need Sun's Java 2 Virtual Machine (Runtime Environment), version 5 or later. You can download this from http://java.sun.com/getjava/download.html. Writer2LaTeX has not been tested with other java implementations.

This user's manual will explain how to install and use Writer2LaTeX.

Note: In this manual OOo is used as an abbreviation of OpenOffice.org.

1.2 More about Writer2LaTeX and Writer2BibTeX

Writer2LaTeX is quite flexible: It can take advantage of several LaTeX packages, such as hyperref, pifont, ulem. It can create customized LaTeX code based on the styles and text in the document. Also it supports more than 25 different languages, latin, greek and cyrillic scripts and 8 input-encodings.

The flexibility makes it possible to use Writer2LaTeX from several philosophies:

• You can use LaTeX as a typesetting engine for your OOo documents: Writer2LaTeX can be configured to create a LaTeX document with as much formatting as possible preserved. Note that the resulting LaTeX source will be readable, but not very clean.

  Be aware that even though Writer2LaTeX tries hard to cope with any document, you will only get good results for well structured documents, ie. documents that are formatted using styles. For other documents you will find that Writer2LaTeX uses the principle garbage in – garbage out!

• If you need to continue the work on your document in LaTeX your primary interest may be the content rather than the formatting. Writer2LaTeX can instructed to produce a LaTeX document which strips most of the formatting and hence produces a clean LaTeX source from any source document.

• Traditionally, LaTeX documents are written by hand using a text editor. Using a graphical frontend like LyX provides a more user friendly alternative. A companion extension named  Writer4LaTeX is in available and provides the tools to make you use OOo as a graphical frontend for LaTeX.

1.3 More about Writer2xhtml and Calc2xhtml

The primary goal for Writer2xhtml and Calc2xhtml is to provide standards compliant XHTML documents which can be customized to your specific needs.

• Standards compliance is necessary to ensure consistent results when the document is viewed in different browsers. It is also vital to ensure that the created document can be processed further by other tools.

• Customization means that you can control important aspects about the conversion. In particular you can control the style of the document:

  • You can let Writer2xhtml convert the style information in the source document and thus get an XHTML document that has the same general appearance as the original, but is adapted to an online environment.

  • You can create a document that adapts the style of the document to your own CSS style sheet.

2 Using the export filters

2.1 Installing of the filters

Writer2LaTeX can work as an export filter for OOo Writer. This requires OpenOffice.org 3.0 or later, or equivalent versions of StarOffice or NeoOffice.

Two OOo extensions are provided:

• writer2latex.oxt installs the LaTeX and BibTeX export filters in Writer

• writer2xhtml.oxt installs the XHTML and EPUB export filters in Writer and Calc

The two extensions are independent, you can install one or both depending on your needs.

Note: From OOo 2.0.4 until 3.0, Writer2LaTeX version 0.4 is installed by default (LaTeX and BibTeX export only). If you install version 1.2, the built-in version will be hidden (to avoid confusion). If you uninstall version 1.2, the original version will reappear.

Also note: Before you install the Writer2LaTeX extensions, you need to set up OOo to use Java. You can configure this in OOo under Tools – Options. Of course this requires that you have installed a Java runtime environment on your system.

Important: If you have installed Writer2LaTeX 0.5, you must uninstall this version first. (This is not necessary if you have installed Writer2LaTeX 0.5.0.2.)

The extensions are installed and uninstalled using the Extension Manager in OOo. If you need instructions about using the Extension Manager, see

http://extensions.services.openoffice.org/resources/user/howto_install

In case of installation troubles, please see the FAQ on Writer2LaTeXs web page:

http://writer2latex.sourceforge.net.

2.2 Using the filters

The filters provided by Writer2LaTeX are all export filters. This means that the filters are to be found in the File – Export menu in Writer or Calc.

Note: As Writer2LaTeX does not provide corresponding import filters, you should always save in OpenDocument format as well!

2.3 Using Writer2LaTeX and Writer2BibTeX

To export a Writer document to LaTeX, choose LaTeX 2e in the export dialog.

After you have typed in a file name, an options dialog will open. To get help, select an item and press F1 or press the help button. Alternatively you can enable extended tips with Shift-F1.

Click Export to initiate the export or Cancel to close the dialog without exporting the document.

Normally you would export the bibliographic data to BibTeX as part of the export to LaTeX, but you may also export the bibliographic data alone. To do this, choose BibTeX in the export dialog. All bibliographic data in the document will be extracted and stored in a BibTeX file which can later be used by e.g. LaTeX documents.

2.4 Using Writer2xhtml

To export a Writer document to XHTML, choose one of the following formats in the export dialog:

• XHTML 1.0 strict will create an XHTML file which is compatible with the older HTML 4 standard. You can thus expect that the result will be viewable with any (modern) browser, but note that mathematical formulas are not supported.

• XHTML 1.1 will create an XHTML file using the XHTML 1.1 standard, but without support for mathematical formulas.

• XHTML 1.1 + MathML 2.0 will create an XHTML file which follows the standard for combining XHTML with mathematical formulas, using MathML for the formulas. Unfortunately, not all browsers support this.

• XHTML 1.1 + MathML 2.0 (xsl) will create a similar XHTML file, but using some XSL-transformations provided by the World Wide Web Consortium (W3C), the result will be viewable by a wider range of browsers, such as Internet Explorer with the MathPlayer plugin. See http://www.w3.org/Math/XSL/ for details.

  This is how W3C's Math Working Group recommends to put ”math on the web”.

• EPUB will create an electronic e-book suitable for viewing on variety of devices.

In all cases, Writer2xhtml uses CSS to format the document, either by converting the original formatting to CSS or by using a CSS style sheet selected by the user.

Note that the default file extension and the recommended MIME types varies with the output format:

After you have typed in a file name, an options dialog will open. To get help, select an item and press F1 or press the help button. Alternatively you can enable extended tips with Shift-F1.

Click Export to initiate the export or Cancel to close the dialog without exporting the document.

2.5 Using Calc2xhtml

To export a Calc document to XHTML, choose XHTML 1.0 strict or XHTML 1.1 in the export dialog.

After you have typed in a file name, an options dialog will open. To get help, select an item and press F1 or press the help button. Alternatively you can enable extended tips with Shift-F1.

Click Export to initiate the export or Cancel to close the dialog without exporting the document.

2.6 Custom configuration

Each of the exports provides the possibility to use a custom format/style. To edit this, choose Tools – Options – Writer2LaTeX resp. Writer2xhtml.

All three exporters uses a configuration file in the user installation folder for OOo.

• On unix-like systems this folder will usually be something like

  home directory/.OpenOffice.org2/user

  or

  home directory/.OpenOffice.org/3/user

• On Windows it will usually be something like

  C:\Documents and Settings\username\OpenOffice.org2\user

  or

  C:\Documents and Settings\username\OpenOffice.org\3\user

  (Note that this directory may be hidden.)

Writer2LaTeX uses a file named writer2latex.xml, and Writer2xhtml and Calc2xhtml shares a file named writer2xhtml.xml. These files are created automatically the first time you use the custom configuration.

See section 4 for the structure of the configuration file.

2.7 Configuration packages

Advanced users may add further formats/styles to the lists in the export dialog. This is done using configuration packages, which are custom extensions to OOo containing further configurations for Writer2LaTeX or Writer2xhtml.

A configuration package can contain:

• A configuration file for Writer2LaTeX or Writer2xhtml, see section 4.

• An XHTML template (Writer2xhtml only).

• An OOo template.

• An OOo registry file to glue the parts together.

The Writer2LaTeX distribution contains a sample configuration package xhtml-config-sample.oxt that demonstrates this.

As a demonstration of the principles of configuration packages, you can install this into OOo using the Extension Manager:

• If you export to XHTML, the dialog will show an additional entry Sample custom style in the Style list.

• If you open Templates and Documents in OOo you will find a new folder xhtml-sample-config. This folder contains a Writer template. If you create a document based on this template, Sample custom style will be preselected when you export to XHTML.

You can create your own configuration package based on this sample. Use a zip utility to unpack the extension. The following explains the individual parts of the sample configuration package.

The file description.xml

This files identifies the extension in OOo. For your own configuration package you should choose a unique name for the identifier and a version number, eg.

<?xml version="1.0" encoding="UTF-8"?>

<description

  xmlns="http://openoffice.org/extensions/description/2006"

  xmlns:d="http://openoffice.org/extensions/description/2006">

  <identifier value="MyConfigPackage" />

  <version value="1.0" />

</description>

The files META-INF/manifest.xml and Paths.xcu

These files should be left unchanged.

The folder template

Put your OOo Writer template in this folder (it is recommended to use a subfolder with a descriptive name). You may add more that one templates, and if you don't want to include a Writer template you may leave it empty (do not delete the folder).

The folder config

Put your Writer2LaTeX/Writer2xhtml configuration in this folder. If you are using Writer2xhtml, you should also put your XHTML template here.

The file Options.xcu

This is the central configuration file that glues together the content of the configuration package. See the following example for an explanation of the structure.

<?xml version='1.0' encoding='UTF-8'?>

<oor:component-data oor:name="Options"

For LaTeX, Writer2xhtml should be replaced by Writer2LaTeX here:

  oor:package="org.openoffice.da.Writer2xhtml"

  xml:lang="en-US"

  xmlns:oor="http://openoffice.org/2001/registry"

  xmlns:xs="http://www.w3.org/2001/XMLSchema">

XhtmlOptions may be replaced by XhtmlOptionsCalc or LaTeXOptions:

    <node oor:name="XhtmlOptions">

        <node oor:name="Configurations">

The configuration needs a unique name (you may define several configurations in the same package):

            <node oor:name="myconfig1" oor:op="replace">

You can define options which are normally set in the filter dialog. In that case you can lock (disable) the corresponding parts of the dialogs. To do so, add a comma separated list of options as value here. See below for the options that can be locked for each of the three filters.

                <prop oor:name="LockedOptions" oor:type="xs:string">

                    <value></value>

                </prop>

The DisplayName is the name displayed in the style/format list in the filter dialog.

                <prop oor:name="DisplayName" oor:type="xs:string" oor:localized="true">

                    <value>My Config Package</value>

                </prop>

This path points to the configuration within the extension, you want to use:

                <prop oor:name="ConfigURL" oor:type="xs:string">

                    <value>%origin%/config/myconfig.xml</value>

                </prop>

This property (XHTML only) points to the XHTML template within the extension, you want to use:

                <prop oor:name="TargetTemplateURL" oor:type="xs:string">

                    <value>%origin%/config/mytemplate.xhtml</value>

                </prop>

This property (XHTML only) points to style sheet within the extension, you want to include (for EPUB export):

                <prop oor:name="StyleSheetURL" oor:type="xs:string">

                    <value>%origin%/config/mytemplate.xhtml</value>

                </prop>

            </node>

        </node>

The next section defines the OOo template you wish to connect with your configuration:

        <node oor:name="Templates">

The entry needs a unique name:

            <node oor:name="mytemplate1" oor:op="replace">

                <prop oor:name="TemplateName" oor:type="xs:string">

The name of the OOo template is defined here (leave out .odt).

                    <value>MyWriterTemplate</value>

                </prop>

                <prop oor:name="ConfigName" oor:type="xs:string">

The configuration to link to is defined here.

                    <value>myconfig1</value>

                </prop>

            </node>

        </node>

    </node>

</oor:component-data>

About locked options

The options you can specify for the LockedOptions property depends on the filter. The following list details which options are available to lock for each filter (see section 4).,

Writer2LaTeX

backend, inputencoding, multilingual, greek_math, additional_symbols4, use_bibtex, bibtex_style, wrap_lines_after, split_linked_sections, split_toplevel_sections, save_images_in_subdir, notes, metadata, original_image_size, simple_table_limit, float_tables, float_figures, float_options, ignore_hard_page_breaks, ignore_hard_line_breaks, ignore_empty_paragraphs, ignore_double_spaces

Writer2xhtml (XHTML export)

scaling, column_scaling, convert_to_px, image_size, notes, use_dublin_core, ignore_hard_line_breaks, ignore_empty_paragraphs, ignore_double_spaces, split_level, repeat_levels, save_images_in_subdir, xslt_path

Writer2xhtml (EPUB export)

scaling, column_scaling, relative_font_size, font_scaling, use_default_font, default_font_name, convert_to_px, image_size, ignore_hard_line_breaks, ignore_empty_paragraphs, ignore_double_spaces, display_hidden_text, notes, split_level, page_break_split, split_after, image_split, cover_image, external_toc_depth, include_toc

Calc2xhtml

scaling, column_scaling, convert_to_px, image_size, notes, use_dublin_core, display_hidden_sheets, display_hidden_rows_cols, display_filtered_rows_cols, apply_print_ranges, use_title_as_heading, use_sheetnames_as_headings, calc_split, save_images_in_subdir

3 Using the command line utility

3.1 How to install Writer2LaTeX for command line usage

Writer2LaTeX can work as a standalone command line utility (an installation of OOo is not required).

Limitation: The export filters support conversion of embedded objects and graphics to a suitable format. The command line utility can only handle graphics in the original format.

Installation for Microsoft Windows

To install Writer2LaTeX under Microsoft Windows follow these instructions:

1. Unzip writer2latex12.zip into some directory. This will create a subdirectory writer2latex12.

2. Add this directory to your PATH environment variable (optional but re­com­men­ded).

In some cases you may have to edit w2l.bat slightly: The batch file assumes that the java executable is in your path. To verify this, open a command prompt and type java -version.  If this test fails (or if you have several Java versions installed and want to use a specific version): Open the file w2l.bat with a text editor and edit the approriate line to contain the full path to the Java executable, eg.

set JAVAEXE="C:\j2sdk1.5.0_01\bin\java”

Installation for Unix and friends

1. Unzip writer2latex12.zip into some directory. This will create a subdirectory writer2latex12.

2. Add this directory to your PATH environment variable (optional but recommended).

3. Add execute permissions to w2l as follows:

   chmod +x w2l

In some cases you may have to edit the script slightly:

If you place w2l and writer2latex.jar in different directories, or if you choose to create a symbolic link to the script: Open the file w2l with a text editor and replace the path at the top of the file with the full path to Writer2LaTeX, eg.

W2LPATH="/home/username/writer2latex12"

Also, the script assumes that the java executable is in your path, or that the JAVA_HOME variable points to the locations. To verify the former, open a command shell and type java -version. To verify the latter, type env. If neither is the case or you have several Java versions installed you should edit this line to contain the full path to the Java executable, ie.

set MYJAVAEXE="/path/to/java/executable/”

3.2 Using the command line utility

To invoke the command line utility, use the command line

w2l <options> <source document/path> [<target document/path>]

The available options are

Some of the options are explained in more detail in the examples below.

Examples converting to LaTeX

The command line

w2l mydocument.odt mypath/myoutputdocument.tex

will convert the document mydocument.odt in the current directory, and save the result in the subdirectory mypath in the document myoutputdocument.tex.

The command line

w2l -config myconfig.xml mydocument.odt

will convert the document using the configuration file myconfig.xml (You can read more about configuration in section 4). As no output file is specified, Writer2LaTeX will use the same name as the original document, but change the extension to .tex.

You can also specify any simple option described in section 4 directly on the command line. Eg. to produce a file suitable for processing with pdfLaTeX:

w2l -backend pdftex mydocument.odt

Instead of giving your own configuration file, you can use one of the standard configurations. For example to produce a clean LaTeX file (ie. ignoring most of the formatting from the source document):

w2l -clean mydocument.odt

Examples converting to BibTeX from the command line

Writer2BibTeX extracts bibliography data to a BibTeX file. For example

w2l -bibtex mydocument.odt

will extract all bibliographic references from the document and store them in a file named mydocument.bib. You can also extract the data as part of the conversion to LaTeX, see section 4.

Examples converting to XHTML from the command line

The command line

w2l -xhtml+mathml mydocument.odt

will convert the document to XHTML+MathML, using the filename mydocument.xhtml.

Likewise the commandline

w2l -xhtml -config myconfig.xml mydocument.odt myresult.html

will convert into XHTML using the specified configuration and file name.

To produce a clean xhtml file (see section 4.3), for example:

w2l -cleanxhtml mydocument.odt mypath/myoutputdoc.html

Examples converting to EPUB from the command line

The command line

w2l -epub -split_level 2 mydocument.odt

will convert to EPUB, divding the document at sections of level 2

Likewise the command line

w2l -epub -stylesheet mystyles.css -cleanxhtml -split_level 2

will create an EPUB file using the custom style sheet mystyles.css for formatting.

4 Configuration

4.1 Writer2LaTeX configuration

LaTeX export can be configured with a configuration file. The location of the configuration depends on how you use Writer2LaTeX: Please see the sections on the export filter and the command line application.

The configuration is a file in xml format. Here is a sample configuration file for producing a document of class book, converting only basic formatting and optimizing for pdfTeX.

<?xml version="1.0" encoding="UTF-8" ?>

<config>

  <option name="backend" value="pdftex" />

  <option name="documentclass" value="book" />

  <option name="inputencoding" value="latin1" />

  <option name="use_pifont" value="false" />

  <option name="use_bibtex" value="false" />

  <option name="bibtex_style" value="plain" />

  <option name="formatting" value="convert_basic" />

  <option name="page_formatting" value="convert_all" />

  <heading-map max-level="4">

    <heading-level-map writer-level="1" name="chapter" level="0" />

    <heading-level-map writer-level="2" name="section" level="1" />

    <heading-level-map writer-level="3" name="subsection"

      level="2" />

    <heading-level-map writer-level="4" name="subsubsection"

      level="3" />

  </heading-map>

  <custom-preamble />

  <style-map name="Quotations" family="paragraph"

    before="\begin{quote}" after=\end{quote} />

  <string-replace input="LaTeX" latex-code="{\LaTeX}" />

</config>

Writer2LaTeX comes with five standard configuration files:

• ultraclean.xml to produce a clean LaTeX file, ie. almost all the formatting is ignored.

• clean.xml is a less radical version; preserves hyperlinks, color and some character formatting.

• pdfscreen.xml to produce a LaTeX file which is optimized for screen viewing using the package pdfscreen.sty.

• pdfprint.xml to produce a LaTeX file which is optimized for printing with pdfTeX.

In addition, you can find a sample configuration file suitable for documents originating from Google Docs in the directry samples/config.

The following subsections explains the available options. The options written in italics can be set using the dialog if you use Writer2LaTeX as an export filter.

General options

These options are used to control general aspects of the generated LaTeX document.

Options for bibliography (BibTeX)

These options controls the handling of the bibliography.

File options

These options controls the creation of files associated with the main LaTeX document.

Options for special content

Figure and table options

The first options are used to control the handling og floating or non-floating figures and tables.

These options controls the export of tables:

These options controls the export of figures:

AutoCorrect options

Formatting options

In Writer, formatting is controlled by styles. You can control how much formatting is exported using the following options. Note that these options has a major impact on the structure of the LaTeX document created.

Options for including or excluding content

The following options can be used to control which content to export.

Headings

The heading_map section specifies how headings in OOo should map to LaTeX. Eg. the first line in the sample above specifies that the toplevel heading (Heading 1) should map to \chapter, which is of level 0 in LaTeX. Up to 10 levels are supported (the same number as in OOo).

Style maps

In addition you can specify maps from styles in Writer to your own LaTeX styles in the configuration. Currently this is possible for text styles, paragraph styles and list styles. In addition a few direct formatting attributes can be mapped to LaTeX code. The following examples are from the standard configuration file article.xml.

This is a simple rule, that maps text formatted with the text style Emphasis to the LaTeX code \emph{...}:

<style-map name="Emphasis" family="text" before="\emph{" after="}" />

This is another simple rule, that maps paragraphs formatted with the paragraph style part to the LaTeX code \part{...}. The attribute line-break ensures that no line breaks are inserted between the code and the text.

<style-map name="part" family="paragraph" before="\part{" after="}" line-break="false" />

This is a rule, that maps paragraphs formatted with style Preformatted Text to the LaTeX environment verbatim. The attribute verbatim ensures that the content of the paragraph is exported verbatim (this implies that characters not available in the inputenc are converted to question marks and that other content is discarded, eg. footnotes). The paragraph-block entry specifies code to go before and after an entire block of paragraphs. The name attribute specifies the style of the first paragraph; the next attribute specifies the style(s) of subsequent paragraphs in the block.

  <style-map name="Preformatted Text" family="paragraph-block" next="Preformatted Text" before="\begin{verbatim}" after="\end{verbatim}" />

<style-map name="Preformatted Text" family="paragraph" before="" after="" verbatim="true" />

This is a more elaborate set of rules, that maps paragraphs formatted with styles Title, author and date (in any order) to \maketitle in LaTeX.

<style-map name="Title" family="paragraph" before="\title{" after="}" line-break="false" />
 <style-map name="author" family="paragraph" before="\author{" after="}" line-break="false" />
 <style-map name="date" family="paragraph" before="\date{" after="}" line-break="false" />
 <style-map name="Title" family="paragraph-block" next="author;date" before="" after="\maketitle" />
 <style-map name="author" family="paragraph-block" next="Title;date" before="" after="\maketitle" />
 <style-map name="date" family="paragraph-block" next="Title;author" before="" after="\maketitle" />

This will produce code like this:

\title{Configuration}

\author{Henrik Just}

\date{2006}

\maketitle

The next example maps a paragraph formatted with the theorem list style to a LaTeX environment named theorem. Note that there are two entries for a list style: The first one to specify the LaTeX code to put before and after the entire list. The second one to specify the LaTeX code to put before and after each list item.

<style-map name="theorem" family="paragraph" before="" after="" />
<style-map name="theorem" family="list" before="" after="" />
<style-map name="theorem" family="listitem" before="\begin{theorem}" after="\end{theorem}" />

When you override a style, all formatting specified in the original document will be igored.

Finally an example using direct formatting attributes:

<style-map name="italic" family="text-attribute" before="\emph{" after="}" />

Currently the only supported names are italic, bold, small-caps, superscript and subscript.

String replace

Often LaTeX requires special care to typeset certain constructions. For example according to German typographical rules, an abbreviation like z.B. should be typeset with a small space before the B. You can specify this in the configuration:

<string-replace input="z.B." latex-code="z.\,B." />

The input is the text in the OOo document, the latex-code is the LaTeX code to export for this text.

Another example is French quotations marks (« Je parle français ») which should be converted to the LaTeX macros \fg and \og. This can be achieved using this rule:

<string-replace input="&#xAB;&#xA0;" latex-code="\fg " />

<string-replace input="&#xA0;&#xBB;" latex-code="\og " />

The final example ensures that the LaTeX logo is typeset correctly

<string-replace input="LaTeX" latex-code="{\LaTeX}" />

Math symbols

In OOo Math you can add user-defined symbols. Writer2LaTeX already understands the predefined symbols such as %alpha. If you define your own symbols, you can add an entry in the configuration that specifies LaTeX code to use. The math-symbol-map element is used for this:

<math-symbol-map name=”ddarrow” latex=”\Downarrow” />

This example will map the symbol %ddarrow to the LaTeX code \Downarrow.

Custom preamble

The text you specify in the element custom-preamble will be copied verbatim into the LaTeX preamble. For example:

<custom-preamble>\usepackage{palatino}</custom-preamble>

to typeset your document using the postscript font palatino.

4.2 Writer2xhtml and Calc2xhtml configuration

Also the XHTML export can be configured with a configuration file in xml format. This is a sample configuration file:

<?xml version="1.0" encoding="UTF-8"?>

<config>

  <option name="custom_stylesheet" value="/mystyle.css" />

  <option name="ignore_styles" value="false" />

  <option name="use_dublin_core" value="true" />

  <option name="convert_to_px" value="true" />

  <option name="split_level" value="1" />

  <xhtml-style-map name="mystyle" family="paragraph" element="p" css="mycssclass" />

</config>

The following subsections explains the available options. The options written in italics can be set using the dialog if you use Writer2xhtml as an export filter.

Style options

You can control some general aspects of the generated XHTML documents using these technical options.

The following options are used to control the conversion of the formatting in the source document. If you use an external CSS style sheet, this is important to define.

In addition, a number of options defines how dimensions in the source document should be handled.

Options for special content

AutoCorrect options

File options

Options specific for spreadsheet documents

Options for batch conversion

Style maps

In addition to the options, you can specify that certain styles in Writer should be mapped to specific XHTML elements and CSS style classes. Here are some examples showing how to use some of the built-in Writer styles to create XHTML elements:

<?xml version="1.0" encoding="UTF-8"?>

<config>

  <!-- map OOo paragraph styles to xhtml elements -->

  <xhtml-style-map name="Text body" family="paragraph"   

           element="p" css="(none)" />  

  <xhtml-style-map name="Sender" family="paragraph"

           element="address" css="(none)" />

  <xhtml-style-map name="Quotations" family="paragraph"

           block-element="blockquote" block-css="(none)"

           element="p" css="(none)" />

  <!-- map OOo text styles to xhtml elements -->

  <xhtml-style-map name="Citation" family="text"

           element="cite" css="(none)" />

  <xhtml-style-map name="Emphasis" family="text"

           element="em" css="(none)" />

  <!-- map hard formatting attributes to xhtml elements -->

  <xhtml-style-map name="bold" family="attribute"

           element="b" css="(none)" />

  <xhtml-style-map name="italics" family="attribute"

           element="i" css="(none)" />

</config>

An extended version of this is distributed with Writer2LaTeX, please see the file cleanxhtml.xml.

The attributes of the xhtml-style-map element are used as follows:

• name specifies the name of the Writer style.

• family9 specifies the style family in Writer; this can either be text, paragraph, heading, frame, list or attribute. The last value does not specify a real style, but refers to hard formatting attributes. The possible names in this case are bold, italics, fixed (for fixed pitch fonts), superscript, subscript, underline and overstrike.

• element specifies the XHTML element to use when converting this style. This is not used for frame and list styles.

• css specifies the CSS style class to use when converting this style. If it is not specified or the value is “(none)”, no CSS class will be used.

• block-element only has effect for paragraph and heading styles. For paragraphs it is used to specify a block XHTML element, that should surround several exported paragraphs with this style. For headings it is used to specify the element containing the entire heading (the element is used for the text content only, excluding the label).

• block-css specifies the CSS style class to be used for this block element. If it is not specified or the value is “(none)”, no CSS class will be used.

For example the rules above produces code like this:

<p>This paragraph is Text body</p>

<address>This paragraph is Sender</address>

<blockquote>

  <p>This paragraph is Quotations</p>

  <p>This paragraph is also Quotations</p>

</blockquote>

<p>This paragraph is also Text body and has some <em>text with emphasis style</em> and uses some <b>hard formatting</b>.</p>

You can use your own Writer styles together with your own CSS style sheet to create further style mappings, for example:

<xhtml-style-map name="Some OOo style" family="paragraph"

           block-element="div" block-css="block_style"

           element="p" css="par_style" />

to produce output like this:

<div class=”block_style”>

  <p class=”par_style”>Paragraph with Some OOo style</p>

  <p class=”par_style”>Yet another</p>

</div>

Note that the rules for hard formatting are only used when formatting is set to ignore_hard or ignore_all. It is not recommended to rely on these rules, using real text styles is preferable. They are included because the use of hard character formatting is very common even in otherwise well-structured documents.

XHTML templates

You can use your own XHTML document as a template for the generated XHTML documents. This should be an ordinary XHTML file (do not include DOCTYPE declaration) with some special elements:

• A div-element with the id content is used to fill the text content. If no such element exists, the <body> element is used. If there is no <body> element in the template, the root element is used.

• div-elements with the id header or footer (optional) will be filled with a simple navigation panel using a first/previous/next/last scheme (for spreadsheet documents, sheet names are used for navigation).

• A div-element with the id panel (optional) will be filled with a simple navigation panel using a table of contens-like scheme.

You can change the names of the id attributes using the template_ids option.

A simple template including a header might look like this:

<html>

  <head>

    <title/>

  </head>

  <body>

    <div id='header' />

    <div id='content' />

  </body>

</html>

As the template does not include footer and panel nodes, these elements will not be included.

The absolute mininal template is this:

<div/>

The div-element will be used as the content container. The generated document will not be a complete XHTML document (no <html>, <head> and <body> nodes). It will however still be a well-formed XML file that can be handled with standard tools. The use case for this is that you can produce XHTML fragments suitable for inclusion in e.g. a CMS.

Note: Make sure to set the option no_doctype to true in this case!

4.3 Using OpenOffice.org to create XHTML documents

The configuration file cleanxhtml.xml that is distributed with Writer2LaTeX, can be used to create semantically rich XHTML content, which can be formatted with your own stylesheet (you should edit the file to add the URL to the stylesheet you want to use).

A subset of the built-in styles in Writer are mapped to XHTML elements (note that the style names are localized, so this is for the english version of OpenOffice.org):

So by using these styles only, you will create well-structured XHTML documents. See the document sample-xhtml.sxw for an example of how to use this.

Links

OOo does not support all kind of XHTML link attributes, for example you cannot set title or rel. Writer2xhtml provides a solution for thus using the name attribute: You can define values for all attributes by providing a semicolon separated list of names and values, eg.

title=My title;rel=next

will create an XHTML link like

<a href="..." title="My title" rel="next">

If the name attributes does not contain such a list, the value is used for the name and title attribute:

My name

will create an XHTML link like

<a href="..." name="My name" title="My name">

5 Special features for the EPUB export

5.1 Meta data

Writer2xhtml always exports the title of the document, and also the subject, keywords and description if they are non-empty.

The EPUB standard specifies a number of meta data elements not supported by ODF. Writer2xhtml supports these elements using user-defined meta data. To add user-defined meta data choose File-Properties, User-defined properties. (The export filter includes a custom editor for these.) The following properties are supported:

• Identifier: Each EPUB document must have a unique ID. Normally Writer2xhtml generates a Universal Unique ID (UUID) for this purpose, but you may override this with your own ID.

  To do this add a new property, enter Identifier (case is not important) as name and the ID as value.

  An identifier may follow a specific identification scheme, e.g. ISBN. To specify an identification scheme, append this to the name separated by a period, e.g. Identifier.ISBN.

  It is possible to have several identifiers, in this case append a number to the name, e.g. Identifier1.ISBN and Identifier2. The first identifier is used as the unique ID.

• Creator: A primary creator or author of the publication.

  Enter Creator as name and the creator's name as value.

  A creator may have a special role, you can specify this with a three letter code after the word creator, e.g. creator.aut for the author or creator.ill for the illustrator. For the complete list of three letter codes see the EPUB specification (http://www.idpf.org/2007/opf/OPF_2.0_final_spec.html).

  You can define several creators, in this case add a number to the word creator, e.g. creator1.aut and creator2. The creators will be sorted according to the numbers. Note that some readers may only present the first creator.

  If no creator is defined, Writer2xhtml will export the default creator given in the document (this is usually taken from OOo's user settings).

• Contributor: A party whose contribution to the publication is secondary to those named in creator elements. Otherwise it is handled like Creator, and the same rules apply.

• Date: Date of publication. The date must be in the format YYYY-MM-DD (year-month-date) or more generally in the format specified in http://www.w3.org/TR/NOTE-datetime.

  A date may be associated with a special event such as creation, publication or modification. To define this, add the event after the word date, e.g. date.publication.

  You can give several dates, in this case add a number to the word date, e.g. date1.creation, date2.modification.

  If you don't define any dates, Writer2xhtml will include the date the document was last modified.

You can only have one instance of the remaining properties, hence they cannot be numbered. Also no additional data can be appended to the name.

• Publisher: The publisher of the document.

• Type: Terms describing general categories, functions, genres, or aggregation levels for content.

• Format: The media type or dimensions of the resource.

• Source: Information regarding a prior resource from which the publication was derived.

• Relation: An identifier of an auxiliary resource and its relationship to the publication.

• Coverage: The extent or scope of the publication’s content.

• Rights: A statement about rights, or a reference to one.

5.2 Hidden hedings

If the entire text of a heading is striked out (using any strike-out style), this heading will be hidden in the text. It will however still be visible in the EPUB table of contents.

6 The LaTeX package ooomath.sty

OOo Math has a few features that are not available in standard LaTeX packages. Hence Writer2LaTeX uses an optional package ooomath.sty10 which implements these constructions. This packages is only needed for documents containing formulas. If it is not available, Writer2LaTeX will insert the necessary definitions in the LaTeX preamble.

It is sufficient to place ooomath.sty in the same directory as the converted LaTeX document. It will however be more convenient if you install it in your TeX distribution. The proper place will usually be the “local texmf tree”, please see the documentation of your TeX distribution. Below are specific instructions for teTeX and MikTeX:

Instructions for teTeX and TeX Live (Linux)

If you use teTeX or TeX Live on Linux you can install ooomath.sty as follows:

Open a shell and type

texconfig conf

This will list the configuration details for TeX. Under the heading “Kpathsea” you will see a list of directories searched by TeX. You can put ooomath.sty in the subdirectory tex of any of these directories. Usually the directory

/home/<user name>/texmf/tex

can be used (you can create it if it doesn't exist).

Next you should type

texconfig rehash

to make TeX refresh it's filename database.

Instructions for MikTeX (Windows)

If you use MikTeX you can install ooomath.sty as follows:

Copy ooomath.sty to the tex subdirectory in the local texmf tree. With a standard installation this will be the directory

c:\localtexmf\tex

If this directory does not exist you should start “MikTeX Options” (you can find this in the Start Menu). On the tab page Roots you can see the location of the local texmf tree.

If the subdirectory tex does not exist, you can create it.

Next you should start “MikTeX Options”. On the tab page General, click the button Refresh Now to make MikTeX refresh it's filename database.

7 Using Writer2LaTeX from another application

7.1 Using Writer2LaTeX from a Java application

Writer2LaTeX features a simple API to convert documents from another Java application. Please see the javadoc for writer2latex.jar (the package writer2latex.api) for details.

The API offers a stream based as well as a file based interface for conversions.

Here's a simple example showing how to convert a file to LaTeX using a custom configuration (excluding exception handling) using the file based methods of the API.

import java.io.File;

import writer2latex.api.*;

// Create a LaTeX converter

Converter converter =

    ConverterFactory.createConverter("application/x-latex");

// Configure the converter

Config config = converter.getConfig();

config.read(new File("myconfig.xml"));

config.setOption("inputencoding","latin1");

// Convert the document

ConverterResult result =

    converter.convert(new File("mydocument.odt"),

        "mydocument.tex");

// Write the files

result.write(new File("mydirectory"));

Using the stream based methods the conversion may look like this (assuming the option save_images_in_subdir is set to false):

import java.io.FileInputStream;

import java.io.FileOutputStream;

// Convert the document

ConverterResult result =

    converter.convert(new FileInputStream("mydocument.odt"),   

    "mydocument.tex");

// Write the files

Iterator<OutputFile> docs = result.iterator();

while (docs.hasNext()) {

    OutputFile docOut = (OutputFile) docs.next();

    FileOutputStream fos =

        new FileOutputStream("mydirectory/"+docOut.getFileName());

    docOut.write(fos);

    fos.flush();

    fos.close();

}

Writer2LaTeX also offers an interface for batch conversion of a directory into XHTML. For at simple example, see the source of Application.java.

7.2 Using Writer2LaTeX from a Basic macro

You can also access Writer2LaTeX through OOo's api. Here's an example using a Basic macro, but the principle is the same for any other language with a UNO binding.

Writer2LaTeX is used as any other filter in OOo. Using the parameter FilterData, you can provide specific options for Writer2LaTeX: You can give an URL for a configuration file to use and/or you can provide values for simple options (the order does not matter, the configuration file is always read first). In addition (XHTML export only), you can define a target template and an included style sheet.

This example exports a document to LaTeX using a specific configuration, but overriding the value of the option use_colortbl.

Dim sUrl As String

sUrl = <url to document>

Dim sConfigUrl As String

sConfigUrl = <url to config>

Dim oFilterData(1) As New com.sun.star.beans.PropertyValue

oFilterData(0).Name  = "ConfigURL"

oFilterData(0).Value = sConfigUrl

oFilterData(1).Name  = "use_colortbl"

oFilterData(1).Value = "true"

Dim oProps(2) As New com.sun.star.beans.PropertyValue

oProps(0).Name  = "FilterName"

oProps(0).Value = "org.openoffice.da.writer2latex"

oProps(1).Name  = "Overwrite"

oProps(1).Value = true

oProps(2).Name  = "FilterData"

oProps(2).Value = oFilterData

ThisComponent.StoreToURL(sUrl, oProps())

The table lists the names of the filters provided by Writer2LaTeX:

This table lists the special properties available for the filter data (all are optional):

The URLs can contain variables such as $(user) for the user installation of OOo. Thus for example “$(user)/myconfig.xml” can be used to point to a configuration within the user installation. See

http://api.openoffice.org/docs/common/ref/com/sun/star/util/PathSubstitution.html

for a list of available variables.

As a special feature, you can require one of Writer2LaTeX's standard configurations. To do this, the URL should start with an asterisk, for example “*ultraclean.xml”.

7.3 Batch conversion with UNO

Writer2LaTeX also offers a uno service

org.openoffice.da.writer2xhtml.BatchConverter

providing batch conversion of a complete directory into another format (usually XHTML) with index pages. This service implements the interface org.openoffice.da.writer2xhtml.XBatchConverter, which provides a single method

// method

// org::openoffice::da::writer2xhtml::XBatchConverter::convert

void convert ( [in] string sSourceURL,

  [in] string sTargetURL,

  [in] sequence<com::sun::star::beans::PropertyValue> lArguments,

  [in] XBatchHandler handler );

• The sSourceURL specifies the URL of the source directory

• The sTargetURL specifies the URL of the target directory

• The handler is an implementation of the call back interface org.openoffice.da.writer2xhtml.XBatchHandler, which is used to provide user interaction during the conversion process. See the IDL definition for documentation. If you use the batch conversion from a Basic macro, the interface must be implemented using CreateUnoListener.

The available arguments (for the parameter lArguments) are specified in this table

7.4 Converting from StarMath with a Basic macro

In addition to converting a complete document, you can also convert a single formula from StarMath to LaTeX. To do this, the uno service

org.openoffice.da.writer2latex.W2LStarMathConverter

is provided. This service supports two methods

string convertFormula ( [in] string sStarMathFormula );

string getPreamble ( );

• The method convertFormula converts a StarMath string to a LaTeX string

• The method getPreamble returns a LaTeX preamble suitable for processing the converted formulas.

This small example is a Basic macro that converts a few formulas and displays the result. Note that the last conversion triggers a definition of the LaTeX macro \defeq in getPreamble().

Dim smc As Object

smc = CreateUnoService( _

    "org.openoffice.da.writer2latex.W2LStarMathConverter")

MsgBox smc.convertFormula("1 over 2")

MsgBox smc.convertFormula("int from 1 to infty f(x)dx")

MsgBox smc.convertFormula("sqrt 3")

MsgBox smc.convertFormula("f(x) def x^2-1")

MsgBox smc.getPreamble()

8 Troubleshooting

If you have to convert a large document, you could get the following error message :

Exception in thread "main" java.lang.OutOfMemoryError: Java heap space

In that case, you need to manually increase the memory available to the java virtual machine, for example using the following command to convert your document:

java -Xmx128M -jar writer2latex.jar bigFile.sxw out.tex

In the example, the heap size is set to 128 Megabyte of RAM. If you still get the “heap space” error,  try setting the available memory to 256 or 512 Megabyte (assuming that your computer has enough physical RAM).

If you are using Writer2LaTeX as an export filter in OOo, this problem will result in a generic error message saying that that document could not be written. To increase the heap size in this case, choose Tools – Options – OpenOffice.org – Java. Click Parameters, and add the parameter -Xmx128M (or higher).

A few memory optimizations are planned for the next version (1.4), which should make it possible to convert a wider range of documents without increasing the heap size in java.

1 In addition, Writer2LaTeX supports the old file formats for OpenOffice.org 1.x Writer and Calc.

2 For OpenOffice.org 2.2-2.4, you can use Writer2LaTeX 1.0.1, for OpenOffice.org 2.0.4–2.1, you can use Writer2LaTeX 0.5.0.2.

3 Unfortunately these variants does not use the same version numbers. For StarOffice you should use StarOffice 8, Product Update 6 or later. For NeoOffice I don't know how the version numbering relates to that of OpenOffice.org.

4 This is a pseudo-option which locks all the options use_pifont, use_ifsym, use_wasysym, use_eurosym and use_tipa.

5 In previous versions, this option was called keep_image_size, but has been renamed to avoid confusion (the old name is still supported).

6 This and the following options replaces the former option ignore_styles.

7 In previous versions, this option was called list_hack, but was renamed to support the new value hard_labels. (The old name is still supported.)

8 This option replaces old options keep_image_size and original_image_size (the old names are still supported).

9 Previously this attribute was called class.

10 This pakcage replaces writer.sty used by older versions of Writer2LaTeX.