paul@20 | 1 | Introduction
|
paul@20 | 2 | ------------
|
paul@20 | 3 |
|
paul@20 | 4 | ConfluenceConverter is a distribution of software that converts exported data
|
paul@20 | 5 | from Confluence Wiki instances, provided in the form of an XML file, to a
|
paul@20 | 6 | collection of Wiki pages and resources that can be imported into a MoinMoin
|
paul@20 | 7 | instance as a page package.
|
paul@20 | 8 |
|
paul@20 | 9 | Prerequisites
|
paul@20 | 10 | -------------
|
paul@20 | 11 |
|
paul@20 | 12 | ConfluenceConverter requires a library called xmlread that can be found at the
|
paul@20 | 13 | following location:
|
paul@20 | 14 |
|
paul@20 | 15 | http://hgweb.boddie.org.uk/xmlread
|
paul@20 | 16 |
|
paul@20 | 17 | The xmlread.py file from the xmlread distribution can be copied into the
|
paul@20 | 18 | ConfluenceConverter directory.
|
paul@20 | 19 |
|
paul@20 | 20 | The moinsetup program is highly recommended for the installation of page
|
paul@20 | 21 | packages and the management of MoinMoin Wiki instances:
|
paul@20 | 22 |
|
paul@20 | 23 | http://moinmo.in/ScriptMarket/moinsetup
|
paul@20 | 24 |
|
paul@20 | 25 | If moinsetup is not being used, the page package installer documentation
|
paul@20 | 26 | should be consulted:
|
paul@20 | 27 |
|
paul@20 | 28 | http://moinmo.in/HelpOnPackageInstaller
|
paul@20 | 29 |
|
paul@20 | 30 | Quick Start
|
paul@20 | 31 | -----------
|
paul@20 | 32 |
|
paul@20 | 33 | Given an XML file for a Confluence Wiki instance (in the example below, the
|
paul@20 | 34 | file is called com_entities.xml), the following command can be used to prepare
|
paul@20 | 35 | a page package for MoinMoin:
|
paul@20 | 36 |
|
paul@20 | 37 | python convert.py com_entities.xml COM
|
paul@20 | 38 |
|
paul@20 | 39 | In addition to the filename, a workspace name is required. Confluence appears
|
paul@20 | 40 | to require a workspace as a container for collections of pages, but this also
|
paul@20 | 41 | permits us to selectively import parts of a Wiki into MoinMoin.
|
paul@20 | 42 |
|
paul@20 | 43 | The result of the above command will be a directory having the same name as
|
paul@20 | 44 | the chosen workspace, together with a zip archive for that directory's
|
paul@20 | 45 | contents. Thus, the above command would produce a directory called COM and an
|
paul@20 | 46 | archive called COM.zip.
|
paul@20 | 47 |
|
paul@20 | 48 | To import the result, use moinsetup as follows:
|
paul@20 | 49 |
|
paul@20 | 50 | python moinsetup.py -m install_page_package COM.zip
|
paul@20 | 51 |
|
paul@20 | 52 | This requires a suitable moinsetup.cfg file in the working directory.
|
paul@20 | 53 |
|
paul@30 | 54 | Output Structure
|
paul@30 | 55 | ----------------
|
paul@30 | 56 |
|
paul@30 | 57 | The structure of a converted workspace is a directory hierarchy containing the
|
paul@30 | 58 | following directories:
|
paul@30 | 59 |
|
paul@30 | 60 | * pages (a collection of directories defining each page or content item,
|
paul@30 | 61 | corresponding to Page, Comment and BlogPost elements in the XML
|
paul@30 | 62 | exported from Confluence)
|
paul@30 | 63 |
|
paul@30 | 64 | * versions (a collection of files, each defining a revision or version of
|
paul@30 | 65 | some content, corresponding to BodyContent elements in the XML
|
paul@30 | 66 | exported from Confluence)
|
paul@30 | 67 |
|
paul@30 | 68 | Each page directory contains the following things:
|
paul@30 | 69 |
|
paul@30 | 70 | * manifest (a list of version entries in a format similar to the MoinMoin
|
paul@30 | 71 | page package manifest format)
|
paul@30 | 72 |
|
paul@30 | 73 | * pagetitle (an optional page title imposed on the page by another content
|
paul@30 | 74 | item)
|
paul@30 | 75 |
|
paul@30 | 76 | * children (a list of child page names defined for the page)
|
paul@30 | 77 |
|
paul@30 | 78 | In the output structure, content items such as comments are represented as
|
paul@30 | 79 | pages and each reference a content version. Since comments will ultimately be
|
paul@30 | 80 | represented as subpages of some parent page, they will have a pagetitle file
|
paul@30 | 81 | in their directory with an appropriate subpage name written according to the
|
paul@30 | 82 | parent page's name and comment details.
|
paul@30 | 83 |
|
paul@20 | 84 | Troubleshooting
|
paul@20 | 85 | ---------------
|
paul@20 | 86 |
|
paul@20 | 87 | The page package import activity in particular can be a source of problems.
|
paul@20 | 88 | Generally, any error occurring when attempting to import a package is likely
|
paul@20 | 89 | to be due to insufficient privileges when writing to the pages directory of a
|
paul@20 | 90 | Wiki or to its edit-log file.
|
paul@20 | 91 |
|
paul@20 | 92 | The moinsetup software can generate scripts that set the ownership of Wiki
|
paul@20 | 93 | files or apply ACLs (access control lists) to those files in order to make
|
paul@20 | 94 | access to Wiki data more convenient. Where the ownership of the files must be
|
paul@20 | 95 | set (to www-data or nobody), the import step can be run as that user given
|
paul@20 | 96 | sufficient privileges. However, the easiest solution is to apply ACLs, thus
|
paul@20 | 97 | allowing the user who created the Wiki to retain write access to it.
|
paul@20 | 98 |
|
paul@20 | 99 | Contact, Copyright and Licence Information
|
paul@20 | 100 | ------------------------------------------
|
paul@20 | 101 |
|
paul@20 | 102 | The current Web page for ConfluenceConverter at the time of release is:
|
paul@20 | 103 |
|
paul@20 | 104 | http://hgweb.boddie.org.uk/ConfluenceConverter
|
paul@20 | 105 |
|
paul@20 | 106 | Copyright and licence information can be found in the docs directory - see
|
paul@20 | 107 | docs/COPYING.txt and docs/LICENCE.txt for more information.
|