• View
• Edit
• Upload
• History
• Print

ExportingOpenDocumentLibreofficeOpenofficeAndOfficeOpenXMLMSWordWithPandoc

<< | Page list | >>

Export to OpenDocument (.odt) and Open Office XML (.docx) file formats with Pandoc

LyX can be set up to export to OpenDocument (.odt, Libreoffice, Openoffice) and Open Office XML (.docx, Microsoft Word) file formats. This page explains how to do so using one of the main third-party converters, Pandoc. Pandoc is a free, open-source, multi-platform tool and, as of 2016, actively developed.

Not all features of LyX documents are properly exported to OpenDocument and Open Office XML. Some limitations of Pandoc are listed below. These are subject to change as Pandoc is further developed. If your export using Pandoc is unsatisfactory you should try exporting to RTF format using latex2rtf to see if the output is better. RTF file formats can be opened by MS Word, Libreoffice and other word processors.

LyX (version 2.2 and later) uses conversions tools such as Pandoc and Latex2rtf out of the box. As of 2016 however, some setup is required for Pandoc to take account bibliography (BibTeX) files. That is detailed below.

1.  Features and limitations of Pandoc exports

The lists are not exhaustive.

1.1  Features

• Export directly from LyX.
• Main structural elements: title, headings, footnotes, description, quote, author ... .
  • *Note* In the OpenDocument format title and author are preserved but not typeset.
• Main typography elements: bold, italic, ... .
• Equations: with MS Open Office XML, equations are exported in MathML mode, which preserves and renders fairly well.
• References: BibTeX bibliographies are converted, by default with the Chicago author-year style, but also with most journal styles using CSL files. See below for details.
• Metadata: title, author.
• tikz graphs: not converted in the default set-up, but should be possible using Pandoc's tikz filter.

1.2  Limitations

• Cross-references: not converted. Instead Pandoc reproduces their labels.
• Headings: not converted.
• Page formatting: not converted.
• Custom LaTeX code, additional LaTeX packages: typically not converted.

2.  Default configuration

This section explains how to set up LyX to use Pandoc for exporting to OpenDocument and Office Open XML format. Additional configuration to process bibliographies is explained in the next section.

§2.1  Install Pandoc

Look at the [[http://www.pandoc.org/installing.html(approve sites)|installation page] on pandoc's website for instructions specific to your system.

Note for Mac OS X users. There are two ways to install pandoc: an installer package and using "Homebrew". The first is quick but requires you to download and install the package again to get pandoc updates. The second is best because it allows for easy updates and it is needed anyway to install further tools, notably Latex2rtf, the other word processor converter for LyX. Here are the steps for the latter option (note that, as of 2016, the last step is missing on pandoc's installation webpage):

1. Install Homebrew. To do so:
   1. Open the Terminal app. You'll find it in Applications > Utilities, or with Spotlight by hitting ⌘Space and typing "Terminal". This allows you to enter "commands" into your Mac, by typing or pasting some text and hitting the "↩︎" key. In this tutorial and elsewhere on the LyX Wiki, when you see "enter" or "enter the command" followed by some code, this normally means that you should enter the code in question in the Terminal (one line at a time).
   2. Browse to Homebrew's page. This gives you a command code that you should copy and paste in the Terminal. Double-click the code (should be something like /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install(approve sites))", hit ⌘C (or do Edit > Copy), go to the Terminal app, hit ⌘V (or do Edit > Paste), hit ↩︎. This will ask for confirmation before downloading install the Homebrew package manager. You may need to enter your user password to allow for the installation.
2. Install Pandoc. To do so:
   1. Still in the Terminal app, enter the command brew install pandoc. This will ask for confirmation before downloading and installing Pandoc.
3. Done. You may close to the terminal.
4. Optional. Now that you have Homebrew installed, it's straightforward to install Latex2rtf as well. That converter allows LyX to export to the RTF format, which can also be opened and modified by MS Word, Libreoffice and other word processors. To install it enter brew install latex2rtf in the Terminal.
5. Optional. Maintenance with Homebrew. If later on you want or need to update things you have installed with Homebrew, open the Terminal and enter brew update (this updates Homebrew itself) and then @@brew upgrade** (this updates everything you have installed with Homebrew).

2.2  Configure LyX

That is easier with current versions of LyX (2.2 or later). To check your version, open LyX and go to Help > About (Windows, Linux) or LyX > About (OS X). To upgrade to the current version go to LyX's webpage.

Lyx 2.2 or later

Open Lyx and go to Tools > Reconfigure. That takes a few moments during which LyX scans your system and finds what tools and formats it can use. If all goes well it will detect Pandoc (and Latex2rtf if you installed it) and configure itself for using it (and Latex2rtf).

When the process is over, LyX displays a message that says that you must restart it to use the new configuration. To restart go to File > Quit (Linux, Windows) or LyX > Quit (Mac OS X) and start LyX again.

If you want to use non-TeX-fonts see section troubleshooting.

Lyx 2.1 or earlier

1. Open the LyX Preferences box. Open Lyx and go to Edit > Preferences (Linux and Windows) or LyX > Preferences (Mac OS X). The box opens. Go to the section File Handling > Converter.
2. Create a converter command from LaTex (plain) to MS Word Office XML. To do that:
   1. Under "From format" select "LaTeX (plain)"
   2. Under "To format" select "MS Word Office XML" or, if not available, "MS Word".
   3. (Optional.) At that point one of the two top-right buttons "Add" or "Modify" will be active. If "Add" you can proceed. If "Modify" then you already have a converter set up for these from/to options, and the steps below will replace it with Pandoc. If you want to be able to undo the switch to Pandoc simply copy and paste somewhere the content of the "Converter" and "Extra flag" fields.
   4. In the "Converter" field enter pandoc -s -f latex -o $$o -t docx $$i
   5. Click "Add" or "Modify" - whichever is active. (If none are active, you already had the Pandoc converter configured as above.)
3. Create a converter command from LaTex (plain) to OpenDocument. Do as in the previous step, except that:
   1. Under "To format" select "OpenDocument (Pandoc)" or, if not available, "OpenDocument".
   2. In the "Converter" field enter pandoc -s -f latex -o $$o -t odt $$i
4. Click "Save" to save the preferences and close the preferences box.

§2.3  Try exporting a LyX document

Open or create a LyX document. It's best to test with a simple one first (not many pages, no modules, customised LaTeX code or preamble etc). Go to File > Export > MS Word Office XML, or alternatively File > Export > OpenDocument (Pandoc). A processing wheel and processing messages should appear at the bottom of your LyX window.

If all goes well, the last message displayed at the bottom of the window should be something like "Export successful". Go the folder where you LyX file is (using File Explorer in Windows or the Finder in Mac or your favourite way of browsing files in Linux). You should see a file with the same name but a .odt or .docx extension next to it. Try an open it with a word processor to see if the conversion worked.

If not all goes well, you will see a warning box with a message like "Error while running pandoc -s -f latex -o $$o -t docx $$i". That's most likely because LyX is not sending Pandoc a file with the proper encoding. For a quick fix try: Document > Settings, go to the Language section, and under "Encoding" select "Other: Unicode (utf8)". Try exporting again. If that works now, then encoding was the problem. See the Troubleshooting section for a way to ensure that all your new LyX documents have the proper encoding setting. If you still get the warning message, see Troubleshooting below.

3.  Configuration for bibliographies

The default configuration above does not handle separate bibliography files (.bib files). However Pandoc does support them and it is possible to setup LyX to include the bibliography in the conversion. By default the bibliography will be formatted in the Chicago manual of style author-year style. Some further setup is needed if you want to generate bibliographies in other formats. The first section below gives some background on bibliography files, you can skip it if you know what a BibTeX bibliography is.

3.1  Background on bibliography (.bib) files

If your LyX documents typically include a bibliography you are or should be using a BibTeX bibliography file (.bib). For more information on using BibTeX for bibliographies in LyX see LyX's User Guide, the section More Tools > Bilbliography > Bibliography databases (bibtex). To read the guide open LyX and go to Help > User Guide; you can go to the relevant section by using the Navigate menu.

Note that a BibTeX bibliography database can be used to insert references in Word or Libreoffice documents too by using a bibliography manager like [[http://www.zotero.org/|Zotero] (free, open-source, multi-platform).

In its default setup for the pandoc converter, LyX exports to MS Word Office XML and OpenDocument do not include bibliographies. Perhaps that's a good thing, as bibliography files with the wrong encoding can cause an error that the average user will have a hard time to uncover (see below, utf8 encoding issue). Below are the steps to allow exports with bibliography.

3.2  If not done already, install Pandoc

See step "Install Pandoc" above.

3.3  Configure LyX

1. Open the LyX Preferences box. Open Lyx and go to Edit > Preferences (Linux and Windows) or LyX > Preferences (Mac OS X). The box opens. Go to the section File Handling > Converter.
2. Update the converter command from LaTex (plain) to MS Word Office XML. To do that:
   1. Under "From format" select "LaTeX (plain)"
   2. Under "To format" select "MS Word Office XML" or, if not available, "MS Word".
   3. In the "Converters" field, enter pandoc -s --citeproc -f latex -o $$o -t docx $$i
   4. Clear the "Extra flag" field if it contains anything.
   5. Click "Modify" (or "Add" if "Modify" is greyed out).
3. Update the converter command from LaTex (plain) to OpenDocument. Same as in the previous step except that:
   1. Under "To format" select "OpenDocument (Pandoc)" or, if not available, "OpenDocument".
   2. In the "Converters" field, enter pandoc -s --citeproc -f latex -o $$o -t odt $$i
4. Click "Save" to save the preferences and close the preferences box.

3.4  Try exporting a LyX document

See step "Try exporting" above. Of course you should try a LyX document that uses a separate bibliography file. It's good to try with a simple (e.g. new, one-entry) bibliography file. The bibliography file must be in the so-called "utf8" encoding, otherwise you will get an error message ("Error while processing pandoc ..."). To make sure your bibliography file is in the proper encoding see the Troubleshooting section.

3.5  Selecting a bibliography style

As of 2016 the configuration above will export your bibliography, but it will ignore your choice of bibliography style. That is, the converted document will use Pandoc's default style for bibliographies, namely the Chicago Manual of Style author-year model. However, there are fairly easy ways to get Pandoc to generate a document with pretty much any bibliography style. Two options are detailed below. The first uses LyX only, the second uses the command line. The first step is common to both.

• Note*. It would be great if (a script for) LyX could look at the bibliography style you've chosen, find the corresponding file online and pass it on to Pandoc. However as of 2016 that's not yet in place.

Get a CSL file for the bibliography format you want.

Go to Zotero's style repository and search for the bibliography format you want. You can search by style name (Chicago manual of style), journal name (IEEE, Cell), professional association (APA), academic field (Law, Humanities, History), style features (numeric).

Click on the name of the style you choose to download a .csl file. The file is a description of the format in the "Citation Style Language" that can be used by Pandoc. Below we use the file mybibformatfile.csl as an example, replace that name by the actual name of your file (such as apa.cls or @ieee.cls@).

Save or copy the .csl file *in the same folder as the LyX file you want to convert*. That is not necessary (see below for putting having .cls files in a separate folder) but it's wise to try it that way first.

Method 1, Lyx-only: adjust the Converter command

This method is good if you want to export a LyX file several times, or export several LyX files and use the same bibliography format for all. Its downside is that each time you want to change bibliography format, you have to change the LyX converter command.

1. Update the converter from LaTex (plain) to MS Word Office XML. To do that:
   1. Under "From format" select "LaTeX (plain)"
   2. Under "To format" select "MS Word Office XML" or, if not available, "MS Word".
   3. In the "Converters" field, enter pandoc -s --citeproc --csl mybibformatfile.csl -f latex -o $$o -t docx $$i
   4. Clear the "Extra flag" field if it contains anything.
   5. Click "Modify" (or "Add" if "Modify" is greyed out).
2. Update the converter from LaTex (plain) to OpenDocument. Same as in the previous step except that:
   1. Under "To format" select "OpenDocument (Pandoc)" or, if not available, "OpenDocument".
   2. In the "Converters" field, enter pandoc -s --citeproc --csl mybibformatfile.csl -f latex -o $$o -t odt $$i
3. Click "Save" to save the preferences and close the preferences box.

To be clear, even with this LyX-only method the format of your bibliography in LyX and in the OpenDocument / Office XML conversion remain distinct entities. The first is selected by clicking on the bibliography within LyX and is used to generate LaTeX outputs such as PDF documents. The second is selected by the commands above (--csl mybibformatfile.csl) and used only by Pandoc for OpenDocument / Office XML exports. Thus if you put the name of a different CSL file above, it will only affect your OpenDocument / Office XML exports, not your PDFs; and conversely, if you change the bibliography format within LyX, that will not change the format used in your OpenDocument / Office XML.

Note that this method sets the bibliography format for exporting *all* LyX files to OpenDocument / Office XML. So if you open another LyX file and export it to OpenDocument / Office XML, the converted .odt or .docs file will also have the mybibformatfile.cls. Do not worry however, that doesn't modify the bibliography format style chosen in the LyX file themselves, because as just explained, these are distinct from the export to OpenDocument / Office XML settings.

Method 1 bis, with the online repository

Sometimes, LyX does not find the csl file, even with absolute address, a workaround is the following pandoc -s --citeproc --csl https://raw.githubusercontent.com/citation-style-language/styles/master/mybibformat.csl(approve sites) -f latex -o $$o -t docx $$i where you just replace mybibformat by one of the styles featured in the repository. I rechecked before editing the page with the French style annales.csl and it works flawlessly. If you have a flag in the code next to the address, remove it, it is not part of the command (or better, replace by your own choice of address, in my experience, it works with the "raw" folder on Github)

Method 2, command line:

This method is good if you want to try several bibliographic formats quickly on the same file and if you're comfortable with the command line. (For more information of the command line do an online search with "command line" and the name of your system.) Its downside is that each time you edit your text you need to export it again and switch from LyX to the terminal.

1. In LyX, choose Export > LaTeX (plain). This generates a file with a .tex extension in the same folder as your LyX document. Here we assume its name is mydocument.tex, replace that with the actual name of your file in the command below.
2. Open a terminal and navigate towards the folder of your LyX document.
3. For OpenDocument conversion enter pandoc -s --citeproc --csl mybibformatfile.csl -f latex -o mydocument.odt -t odt mydocument.tex
4. For Office Open XML conversion enter pandoc -s --citeproc --csl mybibformatfile.csl -f latex -o mydocument.odt -t odt mydocument.tex

3.6  Optional: Store your .csl files in a separate folder

The methods above assume that your mybibformatfile.csl is in the same folder as the LyX document you're converted. That's inconvenient if you're converting several documents scattered over several folders. Ideally, you'd want to have all your .csl files in the same folder. For instance, a folder that also contains your .bib file. This can be done in one of the two ways below.

Method 1: absolute path

This method is good if you're using LyX on one computer only and your .csl files are in a folder that you don't move around.

First, find the "full path" of mybibformatfile.csl. This can be done by right-clicking the file in File Explorer (Windows), Finder (Mac OS X) or your favourite tool (Linux) and looking at the Properties (or "Get Info" on OS X). You should see the "path" or "location" there:

• In Linux it should be something like /home/amelie/writing/biblio/mybibformatfile.csl
• In Mac OS X it should be something like /Users/amelie/biblio/mybibformatfile.csl
• In Windows it should be something like C:\Users\amelie\My Documents\writing\biblio\mybibformatfile.csl

Copy the whole path. Let's suppose that it is C:\Users\amelie\My Documents\writing\biblio\mybibformatfile.csl. Choose one of the method of the step 3.5 again, but wherever there is a pandoc command, replace:

--csl mybibformatfile.csl

with:

--csl "C:\Users\amelie\My Documents\writing\biblio\mybibformatfile.csl"@@

Note that double quotes (") have been added around the full path. These are necessary if the full path contains spaces. If the path doesn't contain spaces, as in the Linux and OS X examples above, you don't need them.

Method 2 relative path

If you adopt the command-line method to use bibliography formats, this method can save you some typing.

If you adopt the Lyx-only method to use bibliography formats, this method is useful in two settings:

• if your LyX files are in a folder synchronized between several computers (through some cloud application like Dropbox, OneDrive, iCloud, etc.) and you want to be able to use LyX and export to OpenDocument or Office Open XML from these different computers. In that kind of setting the full path of your .csl files may differ across computers and the previous method break down.
• if you want to be able to move around the folder that contains both your Lyx documents folder(s) and the folder for .csl files.

Note if you're using the LyX-only method. To be able to export several (all) your LyX files with the same converter setting, these files should all have the same "relative position" relative to your .csl files. If they aren't you need to change the converter command whenever you switch to a LyX file with a different relative position relative to your .csl. In most cases, this means that all the LyX files in question should be at the same "depth" in your directories. For instance, each LyX file should be in some subfolder or other of a Writing/ folder. By contrast, if one LyX file is in a subfolder of Writing/ and one is in a subfolder of a subfolder of Writing/, then you cannot use the same convert command with a relative-path bibliography style for both files. If you're using the command-line method for exporting, that's less of a problem, as you have to enter a command for each export anyway.

To illustrate, suppose you have the following directory structure:

• Work/
  • References/
    • mybibliography.bib
    • mybibformatstyle.csl
  • Drafts/
    • TheHappyOtter/
      • otter1.lyx
      • otter2.lyx
    • TheSadWombat/
      • wombat1.lyx

That is, you have a top folder Work/ (itself located in some document folder, possibly one synchronized across several devices). It has two subfolders, References/ and Drafts/. The first contains your bibliography file, mybibliography.bib and your csl bibliography format file mybibformatstyle.cls. The second contains subfolders with your drafts: TheHappyOtter/ contains drafts otter1.lyx and @otter2.lyx and @TheSadWombat/ contains wombat1.lyx.

Identify the relative path from your LyX file to your .csl. In the example above the relative path is:

../../References/mybibformatstyle.csl

Here's how we find it. Start with the desired LyX document, say, wombat1.lyx. We look at the steps needed to move from there, folder by folder, to reach mybibformatstyle.csl. Namely, we would need to:

1. Move one directory up. That is, from TheSadWombat/ to Drafts/.
2. Move one directory up. That is, from Drafts/ to Work/.
3. Move down into the directory References/. That is, from Work/ to References/.
4. Pick the file mybibformatstyle.csl.

Moving up one directory is marked ../. Moving down a directory is marked by the directory name followed by /. Picking up a file is marked by the file name. So we need:

1. ../
2. ../
3. References/
4. mybibformatstyle.csl

Put these together you get ../../References/mybibformatstyle.csl. That is the "relative path" from wombat1.lyx to mybibformatstyle.csl.

Note that you would do the very same steps to go from otter1.lyx to mybibformatstyle.csl. So that is also the relative path from otter1.lyx to mybibformatstyle.csl.

To use that relative path, we choose one of the method of the step 3.5 again, but wherever there is a pandoc command we replace:

--csl mybibformatfile.csl

with:

--csl "../../References/mybibformatstyle.csl"

The double quotes are only necessary if your relative path contains spaces.

§4.  Troubleshooting

4.1  Using non-TeX-fonts

By default pandoc converters are not present when using non-TeX-fonts. In order to use non-TeX-fonts, you have to configure converters using xetex and / or luatex. This is easiest done I think in the configuration files themselves rather than in LyX. Find your user directory and open the file lyxrc.defaults. In there, you will find a line like:

\converter latex odt3 "pandoc -s -f latex -o $$o -t odt $$i" ""

Copy it and open the file preferences. Paste four times but change it to:

\converter xetex odt3 "pandoc -s -f latex -o $$o -t odt $$i" ""

\converter luatex odt3 "pandoc -s -f latex -o $$o -t odt $$i" ""

\converter xetex word2 "pandoc -s -f latex -o $$o -t docx $$i" ""

\converter luatex word2 "pandoc -s -f latex -o $$o -t docx $$i" ""

Save that file and open LyX.

While exporting with Pandoc you may get an error message like Error while running pandoc -s --filter pandoc-citeproc -f latex -o $$o -t docx $$i. That is most likely the result of encoding issues. Fortunately they are easy to fix: see 4.2 below. But you would also get that error if anything goes wrong in the attempt to export, including:

4.2  Pandoc is not installed

Check that you have pandoc installed and running. To test whether it so, open a terminal (run cmd on Windows, Terminal app on Mac OS X, and you know how with Linux) and enter:

pandoc -v

If you get a "command not found" message, pandoc is not installed or the system doesn't know how to reach it. Try to reinstall, and if still unsuccessful, get help from Pandoc forums.

4.3  LyX is sending files with the wrong encoding

Background. This is the most likely cause of error message. Text files use various "encodings" to encode characters. Until recently LaTeX files (what LyX works with in the background) and BibTeX files (bibliography files for LyX and LaTeX) were typically encoded in "ISO-8859 Latin text". More recently the encoding "UTF-8" has become standard, as it handles pretty much any characters, including e.g. Chinese. Pandoc requires UTF-8 encoding, but LyX may need some set-up to send files in the proper encoding. If LyX sends a file with the wrong encoding, and the file contains complex characters such as é î ø etc., pandoc will not convert the file.

Fix. You need to make sure that LyX sends Pandoc a "UTF-8"-encoded file. If you use a bibliography file, you also have to make sure that that file is in the "UTF-8" encoding. Here are steps to do so.

Make sure that LyX sends a file with the proper encoding

In LyX, open the document you want to convert to MS Word or Libreoffice format. Go to Document > Settings, select the section "Language". Under “Encoding”, select “Other: Unicode (utf8)”. Click Ok to save the settings.

Exporting should now work. If you still get an error message, then either you use a bibliography file and it is in the wrong encoding (see below), or you have further problems (see below).

(Optional) Make sure that all your new LyX documents have the proper encoding

In LyX, create a new document. Go to Document > Settings, and in the section "Language", under "Encoding" choose "Other: Unicode (utf8)". Click "Save as Document Defaults". Click Ok to save these settings. Close and discard the new document.

This ensures that all your new documents have the UTF-8 encoding. That ensures that you can straightforwardly export them to Libreoffice or MS Word formats.

Make sure your bibliography file has the proper encoding

Note for Zotero users. If you created a bibliography file with Zotero from scratch, it's already in UTF-8 and you can skip to step 19. If, however, you've imported a non-UTF .bib file in Zotero, then Zotero has not converted it and your bibliography may contain non-UTF-8 characters. (You can spot them in Zotero: the little lozenges with a question mark inside). If so, you should export a .bib file from Zotero and then apply one of the conversion below. But in the longer term, you'll need to remove clean up your bibliography of non-UTF-8 characters.

For all users. Warning. It's recommended to make a backup of your bibliography (.bib) file before attempting to correct your file encoding using one of the methods.

Method 1. Use the http://www/jabref.org(approve sites) bibliography manager. Open your .bib file in JabRef, go to File > Database properties. At the top, entry "Encoding", select "UTF-8". Click Ok to exit the database properties, and then File > Save database. Your .bib is converted.

Note for running JabRef on Mac OS X. There may be a couple of hurdles when installing JabRef in OS X 10.10 or 10.11. Check JabRef's FAQ(approve sites), Mac OS X tab, to solve them.

Method 2. The .bib file is an ordinary text file. If you're advanced enough to search online how to check the encoding of a text file and convert it, that's an option. You'll typically find methods using the command line or some advanced text editor like EditPadLite on Windows.

4.4  None of the above

If you still get an error message despite the steps above, you should find out what error messages Pandoc is sending. To do so:

1. Go to View > Message Pane. This opens a box at the bottom of the window, the "message pane".
2. Try Exporting again.

The message pane will display Pandoc's error messages. Copy them somewhere and use them to find information relevant to your issue on the web and to ask for help on forums. Note that at that stage you're almost certainly encountering a Pandoc error, not a LyX error. So you should address your questions to Pandoc forums rather than LyX ones.

5.  Categories

Category: Export Category: Tips Category: Bibliography Category: BibTeX Category: Pandoc Category: OpenDocument Category: Office Open XML

Export Tips Bibliography Pandoc OpenDocument Office Open XML