Cytoscape WikiTwo options for DocBook editing with GUI editor:
- XMLmind is an XML specific editor that supports Docbook:
OpenOffice can work with Docbook:
OpenOffice 2.0 has support for importing/exporting docbook directly:
An advantage of using OpenOffice is that it can open the current manual in MS-Word format (see the picture above). As many of Cytoscape developers are Mac users, OpenOffice is also not a problem as it runs on MacOSX too. It is also ported to Linux, FreeBSD, Solaris and Windows, so portability is not too much a problem here 
. The source code is also available, so it can be ported to other platforms too. For the PDF generation, one can use the native PDF exporter of OpenOffice (no need for extra tools).
OpenOffice 1.x is relatively difficult to get working with DocBook. Using version 1.1.2 on RedHat EL4 I am not able to save or export a file as DocBook XML. This appears to be a known bug that is fixed in version 2.0 of OpenOffice.
I have also had no luck getting the conversion tool ooo2dbk to work. Problem number one is that I can't download the latest version from the indesko website. I was able to find an older version (1.3), but was still not able to get it to run. Getting it to run at all involved making edits to the XSLT, but even once those were fixed the program still didn't caputure any of the actual text in the OO document. Given these difficulties, this does not appear to be robust solution, although that might change in the future.
XMLmind seems to be a high quality tool for editing XML documents. XMLmind is not, however, a customary word processor. It requires an understanding of what DocBook is to successfully edit a document. This shouldn't be much of a hurdle for programmers, but could be problematic for non-technical users. XMLmind is not free (as in speech) software, but a basic version can be used for free (as in beer). XMLmind is written in Java and therefore runs on all of our development platforms.
OpenOffice 2.0
OpenOffice v2.0 was just released and its integration with DocBook and XML have been greatly improved. It is now straightforward to export a normal OO document as DocBook. Simply select File - Save As and then select DocBook as the output type of the file. The quality of the export is highly dependent on how well the OO document was styled. For example, the entirety of the Cytoscape manual has a style of "Default". This means that when exported as DocBook, everything is simply turned into paragraphs, which is clearly not ideal. This problem could be overcome fairly easily by simply styling the document (i.e. setting title lines to "Heading 1" and so forth).
However, there are still problems with import. Problem number one is that OpenOffice only respects the 4.1.2 DTD while other more modern versions exist. The result of this is that a document specified with the 4.2 DTD is read in as plain text. This problem can be overcome in most cases by simply changing the DTD version number. The real problem is that the XSLT transform used by OpenOffice to transform DocBook to OpenDocument does not appear to map standard DocBook tags to anything meaningful in OpenDocument - everything gets a "Default" style. This means that if I write and style a document, export it as DocBook, and then import it to edit again, all of the styling is lost. This almost entirely defeats the purpose of importing a DocBook document, so it is possible that I'm doing something wrong. On the other hand, it may simply be a case of an immature transform.
If anyone has had a different (more positive) experience with OpenOffice 2.0 I'd be very interested in hearing about it.