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