README 4.54 KB
Newer Older
1
2
3
lloconv
=======

Olly Betts's avatar
Olly Betts committed
4
This is a document converter which uses LibreOfficeKit for all the heavy
Olly Betts's avatar
Olly Betts committed
5
6
lifting.  LibreOfficeKit was formerly known as liblibreoffice, hence the name
"lloconv".
7

Olly Betts's avatar
Olly Betts committed
8
9
10
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.
11
12
13
14
15
16

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

17
18
19
20
21
22
23
24
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.

Olly Betts's avatar
Olly Betts committed
25
The code checks for LibreOffice installed in /usr/lib/libreoffice/program
26
or /usr/lib64/libreoffice/program (which is where the Debian and Fedora
27
28
29
30
31
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.:
Olly Betts's avatar
Olly Betts committed
32

Olly Betts's avatar
Olly Betts committed
33
$ LO_PATH=/opt/libreoffice5.0/program
Olly Betts's avatar
Olly Betts committed
34
35
$ export LO_PATH

36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
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.

Olly Betts's avatar
Olly Betts committed
54
55
56
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.
57

Olly Betts's avatar
Olly Betts committed
58
59
60
inject-meta
-----------

Olly Betts's avatar
Olly Betts committed
61
62
63
64
65
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.
Olly Betts's avatar
Olly Betts committed
66

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

Olly Betts's avatar
Olly Betts committed
70
If you're packaging lloconv you probably don't want to install `inject-meta` via
Olly Betts's avatar
Olly Betts committed
71
72
the package (at least not in `/usr/bin` or equivalent).

73
74
75
Building
--------

Olly Betts's avatar
Olly Betts committed
76
77
To build a release you need a C++ compiler, make, and the LOK headers,
then the standard autotools build commands should work:
78

Olly Betts's avatar
Olly Betts committed
79
80
81
./configure
make
sudo make install
82

Olly Betts's avatar
Olly Betts committed
83
84
If you want to build from a git checkout, you'll also need autoconf and
automake installed, and to first run:
85

Olly Betts's avatar
Olly Betts committed
86
87
88
89
90
91
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"
92

Olly Betts's avatar
Olly Betts committed
93
94
This allows building on a system where `$HOME/git/libreoffice/master` is a
git checkout and `/usr/include` has no LOK headers.
95
96
97
98

Bugs
----

99
100
101
102
103
104
105
106
107
108
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
~~~~~~~~~~~~

Olly Betts's avatar
Olly Betts committed
109
110
111
112
113
114
115
116
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
117
118
report that at https://gitlab.com/ojwb/lloconv, ideally with an example file
which reproduces the problem.
Olly Betts's avatar
Olly Betts committed
119

120
121
122
Related Software
----------------

Olly Betts's avatar
Olly Betts committed
123
124
If you're looked for a Python API to LibreOfficeKit, take a look at pylokit:
https://github.com/xrmx/pylokit