= unoconv(1)
Dag Wieers <dag@wieers.com>
v0.4, 20 october 2010


== NAME
unoconv - convert any document from and to any LibreOffice supported format


== SYNOPSIS
'unoconv' [options] file [file2 ..]

'unoconv' --listener [--server SRV] [--port PRT] [--connection CON]


== DESCRIPTION
unoconv is a command line utility that can convert any file format that
LibreOffice can import, to any file format that LibreOffice is capable of
exporting.

unoconv uses the LibreOffice's UNO bindings for non-interactive conversion
of documents and therefore needs an LibreOffice instance to communicate with.
Therefore if it cannot find one, it will start its own instance for temporary
usage. If desired, one can start a ``listener'' instance to use for subsequent
connections or even for remote connections.


== OPTIONS
-c, --connection::
    UNO connection string to be used by the client to connect to an
    LibreOffice instance, or used by the listener to make LibreOffice
    listen.
+
    Default connection string is "socket,host=localhost,port=2002;urp;StarOffice.ComponentContext"

-d, --doctype::
    Specify the LibreOffice document type of the backend format. Possible
    document types are: 'document', 'graphics', 'presentation',
    'spreadsheet'.
+
    Default document type is 'document'.

-e, --export::
    Set specific export filter options (related to the used LibreOffice filter).
+
    eg. for the PDF output filter one can specify: -e PageRange=1-2
+
    See the *EXPORT FILTERS* section.

-f, --format::
    Specify the output format for the document. You can get a list of
    possible output formats per document type by using the +--show+ option.
+
    Default document type is 'pdf'.

-F, --field::
    Replace user-defined text field with value
+
    eg. -F Client_Name="Oracle"

-i, --import::
    Set specific import filters options (related to the used LibreOffice
    import filter based on the input filename).
+
    See the *IMPORT FILTERS* section.

-l, --listener::
    Start unoconv as listener for unoconv clients to connect to.

-n, --no-launch::
    By default if no listener is running, unoconv will launch its own
    (temporary) listener to make sure the conversion works. This option
    will abort the conversion if no listener is found, rather than starting
    our own listener.

-o, --output::
    If the argument is a directory, put the converted documents in this
    directory. If multiple input files are provided, use it as a 
    basename (and add output extension). Otherwise use it as the
    output filename.

--password::
    Provide a password to decrypt the document

--pipe::
    Use a pipe as an alternative connection mechanism to talk to LibreOffice.

-p, --port::
    Port to listen on (as listener) or to connect to (as client).
+
    Default port is '2002'.

--preserve::
    Keep timestamp and permissions of the original document

-s, --server::
    Server (address) to listen on (as listener) or to connect to (as client).
+
    Default server is 'localhost'.

--show::
    List the possible output formats to be used with +-f+.

--stdin::
    Read input file from stdin (filenames are ignored if provided)

--stdout::
    Print converted output file to stdout.

-t, --template::
    Specify the template to use for importing styles from. This can be very
    useful if you have a corporate identity you have to apply to every
    document you distribute.

-T, --timeout::
    When unoconv starts its own listener, try to connect to it for an amount
    of seconds before giving up. Increasing this may help when you receive
    random errors caused by the listener not being ready to accept conversion
    jobs.

-v, --verbose::
    Be more and more and more verbose.


== ARGUMENTS
You can provide one or more *files* as arguments to convert each of them to
the specified *output format*.


== IMPORT FILTERS
Depending on the used input file, a different LibreOffice import filter is
automatically used by unoconv. This import filter can be influenced by the
+-i+ option that, depending on the filter used, accepts different arguments.

It is not always clear what import filter options you can provide, the import
dialog in LibreOffice for the filter you ar using might give a good indication
as to what you can expect as import filter options.

The reference is LibreOffice's documentation, for spreadsheets it is described at:
http://wiki.services.openoffice.org/wiki/Documentation/DevGuide/Spreadsheets/Filter_Options
but we will look into some examples.


== DEFAULT IMPORT FILTER OPTIONS
The default import filter for many imports (eg. Lotus, dBase or DIF) accepts
as the only argument the input encoding-type, so if you require utf-8 (76)
you can do:

    -i FilterOptions=76

For a list of possible encoding types, you can use the above link to find the
possible options.

  - FilterOptions


== TEXT IMPORT FILTER OPTIONS
The Text import filter accepts a FilterOptions setting holding the input
encoding.

  - FilterOptions


== CSV IMPORT FILTER OPTIONS
The CSV import filter accepts a FilterOptions setting, the order is:
'separator(s),text-delimiter,encoding,first-row,column-format'

For example you might want to use this for a 'real' comma-separated document:

    -i FilterOptions=44,34,76,2,1/5/2/1/3/1/4/1

which will use a comma (44) as the field separator, a double quote (34) as the
text delimiter, UTF-8 (76) for the input encoding, start from the second row
and use the specified formats for each column (1 means standard, 5 means
YY/MM/DD date)

If you like to use more than one separator (say a space or a tab) and use the
system's encoding (9), but with no text-delimiter, you can do:

    -i FilterOptions=9/32,,9,2

For a list of possible encoding types, you can use the above link to find the
possible options.

  - FilterOptions


== EXPORT FILTERS
In contrast to import filters, export filters can have multiple named options,
although it is not always clear what options are available. It all depends on
the version of LibreOffice. The export dialog you get in LibreOffice might give
you a clue about what is possible, each of those widgets represents an option.


== TEXT EXPORT FILTER OPTIONS
The Text export filter accepts a FilterOptions setting holding the output
encoding.

  - FilterOptions

The order of the arguments is:
'encoding,field-seperator,text-delimiter,quote-all-text-cells,save-cell-content-as-shown'



== CSV EXPORT FILTER OPTIONS
The CSV export filter accepts various arguments, the order is:
'field-seperator(s),text-delimiter,encoding'

For example you might want to use this for a 'real' comma-separated document:

    -e FilterOptions=44,34,76

which will use a comma (44) as the field separator, a double quote (34) as the
text delimiter, UTF-8 (76) for the export encoding, start from the second row and
use the specified formats for each column (1 means standard, 5 means YY/MM/DD
date)

If you like to use more than one separator (say a space or a tab) and use the
system's encoding (9), but with no text-delimiter, you can do:

    -e FilterOptions=9/32,,9

For a list of possible encoding types, you can use the above link to find the
possible options.

  - FilterOptions


== PDF EXPORT FILTER OPTIONS
The PDF export filter is likely the most advanced export filter in its kind
with a myriad of options one can use. The export filter options are described
in a separate document, or on LibreOffice's wiki at:

http://wiki.services.openoffice.org/wiki/API/Tutorials/PDF_export

For example one can specify: +-e PageRange=1-2+

Here is a list of all options, however for more details please look in
'filters.txt':

 - AllowDuplicateFieldNames
 - CenterWindow
 - Changes
 - ConvertOOoTargetToPDFTarget
 - DisplayPDFDocumentTitle
 - DocumentOpenPassword
 - EmbedStandardFonts
 - EnableCopyingOfContent
 - EnableTextAccessForAccessibilityTools
 - EncryptFile
 - ExportBookmarks
 - ExportBookmarksToPDFDestination
 - ExportFormFields
 - ExportLinksRelativeFsys
 - ExportNotes
 - ExportNotesPages
 - FirstPageOnLeft
 - FormsType
 - HideViewerMenubar
 - HideViewerToolbar
 - HideViewerWindowControls
 - InitialPage
 - InitialView
 - IsAddStream
 - IsSkipEmptyPages
 - Magnification
 - MaxImageResolution
 - OpenBookmarkLevels
 - OpenInFullScreenMode
 - PageLayout
 - PageRange
 - PDFViewSelection
 - PermissionPassword
 - Printing
 - Quality
 - ReduceImageResolution
 - ResizeWindowToInitialPage
 - RestrictPermissionPassword
 - Selection
 - SelectPdfVersion
 - UseLosslessCompression
 - UseTaggedPDF
 - UseTransitionEffects
 - Watermark
 - Zoom

=== GRAPHICS EXPORT FILTER OPTIONS
 - Height
 - Resolution
 - Width

==== BMP EXPORT FILTER OPTIONS
 - Compression
 - RLEEncoding

==== JPEG EXPORT FILTER OPTIONS
 - ColorDepth
 - Quality

==== PBM/PGM/PPM EXPORT FILTER OPTIONS
 - Encoding

==== PNG EXPORT FILTER OPTIONS
 - Compression
 - InterlacedMode

==== GIF EXPORT FILTER OPTIONS
 - InterlacedMode
 - Transparency

==== EPS EXPORT FILTER OPTIONS
 - ColorFormat
 - Compression
 - Preview
 - Version

== EXAMPLES
You can use unoconv in standalone mode, this means that in absence of an
LibreOffice listener, it will starts its own:

    unoconv -f pdf some-document.odt


One can use unoconv as a listener (by default localhost:2002) to let other
unoconv instances connect to it:

    unoconv --listener &
    unoconv -f pdf some-document.odt
    unoconv -f doc other-document.odt
    unoconv -f jpg some-image.png
    unoconv -f xsl some-spreadsheet.csv
    kill -15 %-


This also works on a remote host:

    unoconv --listener --server 1.2.3.4 --port 4567


and then connect another system to convert documents:

    unoconv --server 1.2.3.4 --port 4567


== ENVIRONMENT VARIABLES
UNO_PATH::
    specifies what LibreOffice pyuno installation unoconv needs to use
    eg. _/opt/libreoffice3.4/basis-link/program_


== EXIT STATUS
Normally, the exit status is 0 if the conversion ran successful. If an error
has occured, the return code is most likely an error returned by LibreOffice
(or its interface, called UNO) however, the error never translates to something
meaningful. In case you like to decipher the LibreOffice errCode, look at:

    http://cgit.freedesktop.org/libreoffice/core/tree/tools/inc/tools/errcode.hxx
    http://cgit.freedesktop.org/libreoffice/core/tree/svtools/inc/svtools/sfxecode.hxx
    http://cgit.freedesktop.org/libreoffice/core/tree/svtools/inc/svtools/soerr.hxx

Using the above lists, the error code 2074 means:

    Class: 1 (ERRCODE_CLASS_ABORT)
    Code: 26 (ERRCODE_IO_INVALIDPARAMETER or SVSTREAM_INVALID_PARAMETER)

And the error code 3088 means:

    Class: 3 (ERRCODE_CLASS_NOTEXISTS)
    Code: 16 (ERRCODE_IO_CANTWRITE)


== SEE ALSO
    convert(1), file(1), odt2txt


== BUGS
unoconv uses the UNO bindings to connect to LibreOffice, in absence of a usable
socket, it will start its own LibreOffice instance with the correct parameters.

[NOTE]
Please see the TODO file for known bugs and future plans.


== REFERENCES
unoconv is very useful together with the following tools:

Asciidoc::
    http://www.methods.co.nz/asciidoc/

asciidoc-odf::
    http://github.com/dagwieers/asciidoc-odf

docbook2odf::
    http://open.comsultia.com/docbook2odf/

A list of possible import and export formats is available from:

OpenOffice 2.1::
    http://wiki.services.openoffice.org/wiki/Framework/Article/Filter/FilterList_OOo_2_1

OpenOffice 3.0::
    http://wiki.services.openoffice.org/wiki/Framework/Article/Filter/FilterList_OOo_3_0


== AUTHOR
Written by Dag Wieers, <mailto:dag@wieers.com[]>


== RESOURCES
Main web site: http://dag.wieers.com/home-made/unoconv/[]


== COPYING
Copyright \(C) 2007 Dag Wieers. Free use of this software is granted under the
terms of the GNU General Public License (GPL).

// vim: set syntax=asciidoc