FAQ

This is a list of frequently asked questions for the Conglomerate XML editor.

General questions

Q: Why not just use XXX xml editor?

Conglomerate is usable for editing all XML documents but it is not always the ideal editor. Conglomerate really comes into its own when dealing with documents which are content based rather than attribute based. Therefore it is much better for editing documents types traditionally handled in word processors rather than configuration files which require a more traditional tree structure.

Document questions

Q: Can Conglomerate edit an XML document of type XXX?

Yes, conglomerate will allow you to edit any "well-formed" XML document. Although having a "Display Specification" for the document will make it better.

Q: What specific XML document types does Conglomerate support?

In theory, Conglomerate can load and save any well-formed XML document, but it is much happier if it can find a Display Specification for the document type. The following document types are currently supported:

The following document types are partially supported:

The following document types are unsupported, though we hope to add support in the future (patches welcome!):

Q: Can Conglomerate edit non-XML documents?

Yes and no. You can edit non XML documents but only if the appropriate document plugin is present. The internals of conglomerate are designed to work with XML documents so to allow a non XML document to be handled it requires a plugin to convert the document to XML and back again.

Q: What is a "Display Specification"?

A display specification is an XML document used by Conglomerate to hold information about how Conglomerate should display a document and how elements are to be edited.

It is designed to work alongside DTDs or XSchema files to provide information which is more specific to Conglomerate. For example, it can suggest icons that should be used for a particular XML tag.

The Conglomerate website has a list of display specifications. This list is generated from a recent version of the data in CVS.

Q: How do I add support for a new type of document to Conglomerate?

You will need to create a display specification to tell how to display the various elements of that type.

The easiest way to do this is to let Conglomerate create the display specification itself. Load an example document of the type you wish to support, ideally one with a Document Type Declaration referencing a PUBLIC ID with a SYSTEM ID referencing the document type definition via http .

Conglomerate will complain that it doesn't recognise the document type, and ask if you wish to load it anyway. Click on the Force button, and Conglomerate will generate a display specification as it loads the file. You can then go to the Tools menu and select Dump Display Spec. You should save the file into the examples subdirectory, giving it a ".xds" extension. You should then edit examples/Makefile.am and add the filename of the new display specification to dispspec_DATA. You should then re-run make, then (possibly as root) make install, and restart conglomerate. Try loading your document; Conglomerate should now handle it without complaining. Please email the conglomerate-devel mailing list with a patch that adds the document type, so that we can add it to CVS, and into the next release.

Once you have a working xds file for a document type, you can fine-tune it in some of these ways:

The best thing to do is to look through the examples/docbook.xds file, which has examples of how to do these things, and to ask on the conglomerate-devel mailing list.

Q: What custom element renderers already exist?

Q: How do I set up a custom element renderer inside an xds file?

The xds file should use the value "plugin" for the element's "type" attribute. The element will need to have an additional attribute "service-id", which should have a value corresponding to the string ID that the service is registered with inside the plugin.

This affects how elements of that type are rendered in the main editor widget. For other purposes (such as XML Source cleanup, handling the Overview sidebar, etc), such elements are, in general, treated like structural elements (as opposed to span ones).

Some plugin element types need additional information in the xds file; this is done by having a <key-value-list> element below the <element> element; the <key-value-list> should contain <key-value-pair> elements. Each <key-value-pair> element should contain a "key" and "value" attribute. See DocBook's <caution> element for an example.

Q: How do I customise the Property dialog for an element within my DTD?

You can improve support for a DTD by creating a plugin node property dialog. To do this, edit the xds file for the document type, and add a <property-dialog> element inside the main <element>, with a "service-id" attribute giving the registered ID of the code providing the GtkWidget for elements of that type.

FIXME: write information on how to actually create the plugin

For example for the DocBook <orderedlist> element; the xds file gives an ID of "docbook-orderedlist-properties". This is hooked up in the source code in src/plugin-docbook.c to a routine (the C function "docbook_orderedlist_properties_factory_method") which loads a GUI from a Glade file, and uses a set of utility functions that bind the widgets in the glade file to attributes of the XML element. For example, the radio buttons are linked to the various valid values of the "numeration" attribute.

Gnome questions

Q: I use the KDE desktop. Do I have to install Gnome instead, to be able to run Conglomerate?

No. Conglomerate will run perfectly well under KDE, provided you have installed all Gnome 2 shared libraries neccessary for Conglomerate to run.

Building Conglomerate

Q: How do I build Conglomerate from CVS?

The latest version of Conglomerate is stored on GNOME's CVS server as module conglomerate. Detailed instructions for doing this can be found here.

You'll need Gnome 2.0 installed (or a more recent version) to build on top of. You will also need the gnome-commonmodule from GNOME CVS.

Bear in mind that you will be playing with the raw code that the developers use, and it might be temporarily broken. Also, there can be a delay of anything up to 24 hours between the time changes happen on the main CVS server and the time they appear on the anonymous CVS server.

The CVS tree can be browsed here.