
======
README
======

*$Id: README.txt 30124 2005-11-30 14:23:58Z rspivak $*


OOo2DBK is an OpenOffice.org document to DocBook XML converter. It can produce
both DocBook article and DocBook book documents.

The online reference presenting all the available DocBook elements can is
http://docbook.org/tdg/en/html/

OOo2DBK can at the moment only process files generated by the OpenOffice.org
1.1.x series. Future versions of OOo2DBK will process files generated by the
OpenOffice.org 2.x series.


Prerequisites
=============

To run ooo2dbk on your system you need on your system:

  * Python 2.3 (because of the dependence to the optparse module)

  * any supported XSLT processor (check in config.xml)
    ooo2dbk defaults to using the faster xsltproc program
    http://xmlsoft.org/XSLT/xsltproc2.html But you can use any other XSLT
    processor, such as Saxon.


Examples
========

1. To produce a DocBook XML article out of an OpenOffice.org document:
$ ooo2dbk --article --zipfile=document.zip document.sxw

2. To produce a DocBook XML book out of an OpenOffice.org document:
$ ooo2dbk --book --zipfile=document.zip document.sxw


Styles
======

The following styles can be used in OpenOffice.org and map to the corresponding
DocBook tags:

Abstract		abstract
Acronym			acronym
Attribution		attribution
Author			author
Authorblurb		authorblurb
Bibliocoverage		bibliocoverage
Bibliomisc		bibliomisc
Bibliorelation		bibliorelation
Bibliosource		bibliosource
Blockquote		blockquote
Citation		citation
Command			command
Computeroutput		computeroutput
Copyright		copyright
Corpauthor		corpauthor
Definition		element used for variablelist
Editor			editor
Email			email
Emphasis		emphasis
Epigraph		epigraph
Example			literal
Filename		filename
Firstname		firstname
Frame			element used for figure
Graphics		element used for figure
Guillemets		element used to mark quotes we don't want to treat
Heading			title
Holder			holder
Honorific		honorific
Jobtitle		jobtitle
Keyword			keyword
Keywordset		keywordset
Legalnotice		legalnotice
Lineage			lineage
Lineannotation		lineannotation
Literal			literal
Literallayout		literallayout
Note			note
Option			option
Orgname			orgname
Othercredit		othercredit
Othername		othername
Preformatted Text	programlisting
ProgramListing		programlisting
Pubdate			pubdate
Pubsnumber		pubsnumber
Quotations		blockquote
Remark			remark
Replaceable		replaceable
Source Text		literal
Strong Emphasis		emphasis role="strong"
Subtitle		subtitle
Surname			surname
Teletype		literal
Term			term
Title			title
Userentry		userinput
User Entry		userinput
Year			year


Problems and debugging
======================

In case of problems run ooo2dbk with the "--verbose" option.


Is it possible to run ooo2dbk on Microsoft Windows ?
====================================================

If you get the following problem:

C:\WINDOWS\Bureau\ooo2dbk-1.0.2-1>c:\python23\python ooo2dbk --book --zipfile=document.zip document.sxw

Commande ou nom de fichier incorrect
Traceback (most recent call last):
  File "ooo2dbk", line 587, in ?
    exec_args()
  File "ooo2dbk", line 131, in exec_args
    deltemp=options.flatxml, xslParams=xslParams)
  File "ooo2dbk", line 560, in convert
    make_zip()
  File "ooo2dbk", line 508, in make_zip
    zarchive.write(sDocbookXML, pjoin(archive_top_dir, docbook_fname))
  File "C:\PYTHON23\lib\zipfile.py", line 391, in write
    st = os.stat(filename)
OSError: [Errno 2] No such file or directory: 'C:\\WINDOWS\\Bureau\\ooo2dbk-1.0.
2-1\\document.docb.xml'

The problem is that there is no 'xsltproc' executable installed.
To solve the problem you need to install it.

1) Download:
  - ftp://ftp.zlatkovic.com/pub/libxml/libxml2-2.6.15.win32.zip
  - ftp://ftp.zlatkovic.com/pub/libxml/libxslt-1.1.12.win32.zip
  - ftp://ftp.zlatkovic.com/pub/libxml/zlib-1.2.1.win32.zip
  - ftp://ftp.zlatkovic.com/pub/libxml/iconv-1.9.1.win32.zip

2) Create directory somewhere on filesystem, for example, c:\libxml

3) Put c:\libxml into system PATH on windows
(On WinXP you can achieve this with following: Start -> Control Panel -> System,
then choose tab "Advanced" and press "Environment variables".  You will see
"System variables", find there "Path" and append "c:\libxml" at the end)

4) From first 3 above downloaded zip files copy _all_ contents of "bin"
directory into "c:\libxml". As for iconv-1.9.1.win32.zip - copy iconv.dll from
"lib" and "iconv.exe" from "util" into "c:\libxml".

5) Restart shell from which you ran ooo2dbk (this will take into account
modified PATH) and try again.

This has been tested with both Microsoft Windows XP (SP2) and Windows 2000.

Creating standalone executable on Microsoft Windows
===================================================

You can build standalone console application with the help of 'py2exe' -
http://py2exe.sourceforge.net

It's a version 0.6.3 at the moment of the writing.

After installing py2exe execute in ooo2dbk source directory:

python setup.py py2exe -b 1

As a result you'll get 'dist' directory containing:
library.zip, ooo2dbk.exe, w9xpopen.exe that should be distributed together
to run oo2dbk.exe

Don't forget that you'll also need at least two additional files from source
distribution: ooo2dbk.xml and ooo2dbk.xsl for proper use of ooo2dbk.exe

To make ooo2dbk.exe available system wide, put path to directory containing
that executable into system PATH variable.
Good luck!

ooo2dbk along with a OpenOffice.org instance
============================================

If you want to use the OLE objects to image conversion feature you need to
launch the ooo2dbk script with the python shipped with OpenOffice.org.
Since OpenOffice.org 1.1.x series ship with Python 2.2 you need to take extra
steps to make this combination possible.

The solution is to copy the Python 2.3 specific modules that are needed by
ooo2dbk to the OpenOffice.org shipped Python module location:
/usr/local/openoffice-1.1.4/program/python-core/lib$ cp /usr/lib/python2.3/optparse.py .
/usr/local/openoffice-1.1.4/program/python-core/lib$ cp /usr/lib/python2.3/textwrap.py .

