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