README

lloconv
=======

This is a document convertor which uses LibreOfficeKit for all the heavy
lifting.  LibreOfficeKit was formerly known as liblibreoffice, hence the name
"lloconv".

LibreOffice 4.4 and later are fully supported.  LibreOffice 4.3 works
provided you avoid filenames which contain characters which need
escaping in a URL.

To use it, just run it with the input and output filenames - the format to
convert to is determined by the extension of the output filename.  E.g.:

$ ./lloconv essay.odt essay.html

You can also fetch a document from a URL to convert:

$ ./lloconv -u https://example.org/sample.doc sample.html

Use this feature with caution - it's probably safe on https URLs you control
the content of, but fetching arbitrary documents is equivalent to automatically
opening email attachments.

The code checks for LibreOffice installed in /usr/lib/libreoffice/program
(which is where the Debian packages install to) and if it's not there, tries
/opt/libreoffice<major>.<minor>/program for known <major>.<minor> versions
(which is where the .debs from libreoffice.org install to).  You can override
this by setting environmental variable LO_PATH, either to handle an install in
another location, or to force a particular install to be used if you have more
than one copy installed, e.g.:

$ LO_PATH=/opt/libreoffice5.0/program
$ export LO_PATH

Building
--------

You need a C++ compiler, GNU make, and the LOK headers.

In most cases, you can just run `make`.

If you want to build against LOK headers outside /usr/include, you can specify
LO_INCLUDE_PATH like so:

make LO_INCLUDE_PATH="$HOME/git/libreoffice/master/include"

This allows building on a system where $HOME/git/libreoffice/master is a
git checkout and /usr/include has no LOK headers.

Bugs
----

Failure to convert a particular file is much more likely an issue with
LibreOffice or the file itself rather than a lloconv bug.  If you find a file
which lloconv can't convert, before reporting a bug against lloconv please
first check if you can convert it by opening it using the LibreOffice UI and
selecting File->Export.  If this also fails, it's either a bad file or a
LibreOffice bug.

If you find a file which LibreOffice can convert but lloconv can't, please
report that at https://gitlab.com/ojwb/lloconv, ideally with an example file
which reproduces the problem.

If you're looked for a Python API to LibreOfficeKit, take a look at pylokit:
https://github.com/xrmx/pylokit