lloconv
=======

This is a document converter 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
or /usr/lib64/libreoffice/program (which is where the Debian and Fedora
packages install to) and if it's not there, looks for /opt/libreoffice*/program
(which is where the .debs from libreoffice.org install to), using the highest
version if multiple are found.  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

Server
------

The time to initialise LibreOfficeKit can be significant if you have a lot of
files to process, so lloconv supports a "server" mode where a background
process provides a way to reuse a single LibreOfficeKit instance to convert
multiple documents.

This works via a Unix domain socket.  Bear in mind that if another user on
the same machine can write to the domain socket you use then they can probably
read your documents by using lloconv, so it's a good idea to create the socket
in its own directory which only you can read (`chmod 700 DIRECTORY`).

If you specify `-s SOCKETPATH` and a document path and a server isn't running
for SOCKETPATH then one will be started in the background.  You can also start
a server explicitly by using `lloconv -l -s SOCKETPATH` first without
specifying a document.

Currently you can't use `-u` and `-s SOCKETPATH` together, which means when
using a server you can convert files from paths, but not files from arbitrary
URLs.

inject-meta
-----------

This program converts a textual document to `.odt` format, adjusts the metadata
fields in the `.odt` file as specified by the command line options, then
converts back to the requested output format.  This allows you to add or modify
metadata fields in a document automatically, but the double conversion may
result in additional unwanted changes to the document.

It's more of a worked example than a usable tool, and isn't built by default.
Run configure with option `--enable-extra-programs` to enable it.

If you're packaging lloconv you probably don't want to install `inject-meta` via
the package (at least not in `/usr/bin` or equivalent).

Building
--------

To build a release you need a C++ compiler, make, and the LOK headers,
then the standard autotools build commands should work:

./configure
make
sudo make install

If you want to build from a git checkout, you'll also need autoconf and
automake installed, and to first run:

autoreconf -fiv

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

./configure 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
----

Known Bugs
~~~~~~~~~~

LibreOffice seems to be unable to handle a file whose filename isn't valid
in the current locale's encoding (for example, a filename which isn't
valid UTF-8 on a typical modern Linux machine).

Other Issues
~~~~~~~~~~~~

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.

Related Software
----------------

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