Re: faq.xml.qna
Sean Wheller <[email protected]> Sun, 8 May 2005 16:28:50 +0200
| Newsgroups | gmane.editors.conglomerate.devel |
|---|---|
| Organization | In Words |
| Message-ID | <[email protected]> |
I transformed faq.xml to HTML. I attach it here. The structure is not perfect but it will illustrate what I mean about packaging the document as HTML in conglomerate. At least this way we can overcome the limitation that yelp does not support qanda. To view in yelp save the file to disk and do yelp faq.xml.html What we need to do in the conglomerate build is use xsltproc to transform the xml to html. There is no point in commiting the html since we will only update the faq. Hope this helps -- Sean Wheller Technical Author [email protected] 084-854-9408 http://www.inwords.co.za Registered Linux User #375355 _______________________________________________ Conglomerate-devel mailing list [email protected] http://lists.copyleft.no/mailman/listinfo/conglomerate-devel
faq.xml.html
(text/html, 17 KB)
<html><head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Conglomerate FAQ</title><meta name="generator" content="DocBook XSL Stylesheets V1.67.2"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="article" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="d0e2"></a>Conglomerate FAQ</h2></div></div><hr></div><p>This is a list of frequently asked questions for the Conglomerate XML editor.</p><div class="qandaset"><dl><dt>1. <a href="#generalfaq">General questions</a></dt><dd><dl><dt>1.1. <a href="#d0e11">Why not just use XXX xml editor?</a></dt></dl></dd><dt>2. <a href="#docfaq">Document questions</a></dt><dd><dl><dt>2.1. <a href="#d0e21">Can Conglomerate edit an XML document of type XXX?</a></dt><dt>2.2. <a href="#d0e28">What specific XML document types does Conglomerate support?</a></dt><dt>2.3. <a href="#d0e69">Can Conglomerate edit non-XML documents?</a></dt><dt>2.4. <a href="#d0e76">What is a "Display Specification"?</a></dt><dt>2.5. <a href="#d0e90">How do I add support for a new type of document to Conglomerate?</a></dt><dt>2.6. <a href="#d0e151">What custom element renderers already exist?</a></dt><dt>2.7. <a href="#d0e199">How do I set up a custom element renderer inside an xds file?</a></dt><dt>2.8. <a href="#d0e243">How do I customise the Property dialog for an element within my DTD?</a></dt></dl></dd><dt>3. <a href="#gnomefaq">Gnome questions</a></dt><dd><dl><dt>3.1. <a href="#d0e281">I use the KDE desktop. Do I have to install Gnome instead, to be able to run Conglomerate?</a></dt></dl></dd><dt>4. <a href="#building">Building Conglomerate</a></dt><dd><dl><dt>4.1. <a href="#d0e291">How do I build Conglomerate from CVS?</a></dt></dl></dd></dl><table border="0" summary="Q and A Set"><col align="left" width="1%"><tbody><tr class="qandadiv"><td align="left" valign="top" colspan="2"><a name="generalfaq"></a><h3 class="title"><a name="generalfaq"></a>1. General questions</h3></td></tr><tr class="toc" colspan="2"><td align="left" valign="top" colspan="2"><dl><dt>1.1. <a href="#d0e11">Why not just use XXX xml editor?</a></dt></dl></td></tr><tr class="question"><td align="left" valign="top"><a name="d0e11"></a><a name="d0e12"></a><b>1.1.</b></td><td align="left" valign="top"><p>Why not just use XXX xml editor?</p></td></tr><tr class="answer"><td align="left" valign="top"><b></b></td><td align="left" valign="top"><p>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. </p></td></tr><tr class="qandadiv"><td align="left" valign="top" colspan="2"><a name="docfaq"></a><h3 class="title"><a name="docfaq"></a>2. Document questions</h3></td></tr><tr class="toc" colspan="2"><td align="left" valign="top" colspan="2"><dl><dt>2.1. <a href="#d0e21">Can Conglomerate edit an XML document of type XXX?</a></dt><dt>2.2. <a href="#d0e28">What specific XML document types does Conglomerate support?</a></dt><dt>2.3. <a href="#d0e69">Can Conglomerate edit non-XML documents?</a></dt><dt>2.4. <a href="#d0e76">What is a "Display Specification"?</a></dt><dt>2.5. <a href="#d0e90">How do I add support for a new type of document to Conglomerate?</a></dt><dt>2.6. <a href="#d0e151">What custom element renderers already exist?</a></dt><dt>2.7. <a href="#d0e199">How do I set up a custom element renderer inside an xds file?</a></dt><dt>2.8. <a href="#d0e243">How do I customise the Property dialog for an element within my DTD?</a></dt></dl></td></tr><tr class="question"><td align="left" valign="top"><a name="d0e21"></a><a name="d0e22"></a><b>2.1.</b></td><td align="left" valign="top"><p>Can Conglomerate edit an XML document of type XXX?</p></td></tr><tr class="answer"><td align="left" valign="top"><b></b></td><td align="left" valign="top"><p>Yes, conglomerate will allow you to edit any "well-formed" XML document. Although having a "Display Specification" for the document will make it better. </p></td></tr><tr class="question"><td align="left" valign="top"><a name="d0e28"></a><a name="d0e29"></a><b>2.2.</b></td><td align="left" valign="top"><p>What specific XML document types does Conglomerate support?</p></td></tr><tr class="answer"><td align="left" valign="top"><b></b></td><td align="left" valign="top"><p>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:</p><div class="itemizedlist"><ul type="disc"><li><p>DocBook 4.1.2</p></li><li><p>XHTML (strict)</p></li><li><p>"Kernel Traffic" newsetter format</p></li></ul></div><p>The following document types are partially supported:</p><div class="itemizedlist"><ul type="disc"><li><p>RELAX NG schema files</p></li><li><p>XSL-FO files</p></li></ul></div><p>The following document types are unsupported, though we hope to add support in the future (patches welcome!):</p><div class="itemizedlist"><ul type="disc"><li><p>CSS</p></li><li><p>OpenOffice.org file format</p></li><li><p>Open eBook format</p></li><li><p>TEI format</p></li></ul></div></td></tr><tr class="question"><td align="left" valign="top"><a name="d0e69"></a><a name="d0e70"></a><b>2.3.</b></td><td align="left" valign="top"><p>Can Conglomerate edit non-XML documents?</p></td></tr><tr class="answer"><td align="left" valign="top"><b></b></td><td align="left" valign="top"><p>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. </p></td></tr><tr class="question"><td align="left" valign="top"><a name="d0e76"></a><a name="d0e77"></a><b>2.4.</b></td><td align="left" valign="top"><p>What is a "Display Specification"?</p></td></tr><tr class="answer"><td align="left" valign="top"><b></b></td><td align="left" valign="top"><p>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. </p><p>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. </p><p>The Conglomerate website has a <a href="http://www.conglomerate.org/xds/index.html" target="_top">list of display specifications</a>. This list is generated from a recent version of the data in CVS.</p></td></tr><tr class="question"><td align="left" valign="top"><a name="d0e90"></a><a name="d0e91"></a><b>2.5.</b></td><td align="left" valign="top"><p>How do I add support for a new type of document to Conglomerate?</p></td></tr><tr class="answer"><td align="left" valign="top"><b></b></td><td align="left" valign="top"><p>You will need to create a display specification to tell how to display the various elements of that type. </p><p>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 .</p><p>Conglomerate will complain that it doesn't recognise the document type, and ask if you wish to load it anyway. Click on the <span class="guibutton">Force</span> button, and Conglomerate will generate a display specification as it loads the file. You can then go to the <span class="guimenu">Tools</span> menu and select <span class="guimenuitem">Dump Display Spec</span>. You should save the file into the <code class="filename">examples</code> subdirectory, giving it a ".xds" extension. You should then edit <code class="filename">examples/Makefile.am</code> and add the filename of the new display specification to <span class="symbol">dispspec_DATA</span>. You should then re-run <strong class="userinput"><code>make</code></strong>, then (possibly as root) <strong class="userinput"><code>make install</code></strong>, and restart <span class="application">conglomerate</span>. 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.</p><p>Once you have a working xds file for a document type, you can fine-tune it in some of these ways:</p><div class="itemizedlist"><ul type="disc"><li><p>Change whether elements are "structural" or "span" elements. The display specification generation routine tries to guess this based upon the example document and on the DTD, but it sometimes makes mistakes.</p></li><li><p>Set up human-readable names for elements, together with descriptions of what they do. Currently this is in English only, though we plan to allow localisable versions of these strings (patches welcome!)</p></li><li><p>Set up icons for elements, for use in the menus and in the main widget.</p></li><li><p>Write custom XPath rules for generating the title string to be used for an element.</p></li><li><p>Use plugins to better represent an element. For example, there are already plugins aimed at rendering paragraphs, and items within lists. You can even create custom property dialogs for an element type, those this requires writing some code.</p></li></ul></div><p>The best thing to do is to look through the <code class="filename">examples/docbook.xds</code> file, which has examples of how to do these things, and to ask on the conglomerate-devel mailing list.</p></td></tr><tr class="question"><td align="left" valign="top"><a name="d0e151"></a><a name="d0e152"></a><b>2.6.</b></td><td align="left" valign="top"><p>What custom element renderers already exist?</p></td></tr><tr class="answer"><td align="left" valign="top"><b></b></td><td align="left" valign="top"><div class="itemizedlist"><ul type="disc"><li><p><b><code class="literal">paragraph</code>. </b>This is used by the DocBook <code class="sgmltag-element">para</code> element and should be used by any other document type to represent a typical paragraph-level element. Currently it renders itself as a dashed rectangle surrounding the element's content. We might add a "pilcrow" symbol (a little q) as an extra refinement at some point.</p></li><li><p><b><code class="literal">admonition</code>. </b>This is used by DocBook's admonition elements: <code class="sgmltag-element">note</code>, <code class="sgmltag-element">tip</code>, <code class="sgmltag-element">caution</code> etc. It renders itself as an icon on the left, with the element's content presented in an indented form to the right. It could be used by any other element that would be well-presented as a icon labelling the content. The key-value pair "icon" should be used to specify which icon to use for each particular element.</p></li><li><p><b><code class="literal">listitem</code>. </b>This is used by DocBook's <code class="sgmltag-element">listitem</code> element. It renders itself as a textual label, with the content indented on the right-hand side. Currently the code has hardcoded logic that generates the label according to DocBook's semantics; it looks to see if its inside an <code class="sgmltag-element">orderedlist</code> or an <code class="sgmltag-element">itemizedlist</code>, and what position it occupies in that list etc to generate either a bullet or a numbering. This could be generalised if people want to reuse the code for other DTDs.</p></li></ul></div></td></tr><tr class="question"><td align="left" valign="top"><a name="d0e199"></a><a name="d0e200"></a><b>2.7.</b></td><td align="left" valign="top"><p>How do I set up a custom element renderer inside an xds file?</p></td></tr><tr class="answer"><td align="left" valign="top"><b></b></td><td align="left" valign="top"><p>The xds file should use the value "<code class="literal">plugin</code>" for the element's "<code class="literal">type</code>" attribute. The element will need to have an additional attribute "<code class="literal">service-id</code>", which should have a value corresponding to the string ID that the service is registered with inside the plugin. </p><p>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).</p><p>Some plugin element types need additional information in the xds file; this is done by having a <code class="sgmltag-element">key-value-list</code> element below the <code class="sgmltag-element">element</code> element; the <code class="sgmltag-element">key-value-list</code> should contain <code class="sgmltag-element">key-value-pair</code> elements. Each <code class="sgmltag-element">key-value-pair</code> element should contain a "<code class="literal">key</code>" and "<code class="literal">value</code>" attribute. See DocBook's <code class="sgmltag-element">caution</code> element for an example.</p></td></tr><tr class="question"><td align="left" valign="top"><a name="d0e243"></a><a name="d0e244"></a><b>2.8.</b></td><td align="left" valign="top"><p>How do I customise the Property dialog for an element within my DTD?</p></td></tr><tr class="answer"><td align="left" valign="top"><b></b></td><td align="left" valign="top"><p>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 <code class="sgmltag-element">property-dialog</code> element inside the main <code class="sgmltag-element">element</code>, with a "<code class="literal">service-id</code>" attribute giving the registered ID of the code providing the GtkWidget for elements of that type.</p><p>FIXME: write information on how to actually create the plugin</p><p>For example for the DocBook <code class="sgmltag-element">orderedlist</code> element; the xds file gives an ID of "<code class="literal">docbook-orderedlist-properties</code>". This is hooked up in the source code in <code class="filename">src/plugin-docbook.c</code> to a routine (the C function "<code class="function">docbook_orderedlist_properties_factory_method</code>") 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 "<code class="literal">numeration</code>" attribute.</p></td></tr><tr class="qandadiv"><td align="left" valign="top" colspan="2"><a name="gnomefaq"></a><h3 class="title"><a name="gnomefaq"></a>3. Gnome questions</h3></td></tr><tr class="toc" colspan="2"><td align="left" valign="top" colspan="2"><dl><dt>3.1. <a href="#d0e281">I use the KDE desktop. Do I have to install Gnome instead, to be able to run Conglomerate?</a></dt></dl></td></tr><tr class="question"><td align="left" valign="top"><a name="d0e281"></a><a name="d0e282"></a><b>3.1.</b></td><td align="left" valign="top"><p>I use the KDE desktop. Do I have to install Gnome instead, to be able to run Conglomerate?</p></td></tr><tr class="answer"><td align="left" valign="top"><b></b></td><td align="left" valign="top"><p>No. Conglomerate will run perfectly well under KDE, provided you have installed all Gnome 2 shared libraries neccessary for Conglomerate to run.</p></td></tr><tr class="qandadiv"><td align="left" valign="top" colspan="2"><a name="building"></a><h3 class="title"><a name="building"></a>4. Building Conglomerate</h3></td></tr><tr class="toc" colspan="2"><td align="left" valign="top" colspan="2"><dl><dt>4.1. <a href="#d0e291">How do I build Conglomerate from CVS?</a></dt></dl></td></tr><tr class="question"><td align="left" valign="top"><a name="d0e291"></a><a name="d0e292"></a><b>4.1.</b></td><td align="left" valign="top"><p>How do I build Conglomerate from CVS?</p></td></tr><tr class="answer"><td align="left" valign="top"><b></b></td><td align="left" valign="top"><p>The latest version of Conglomerate is stored on GNOME's CVS server as module <code class="filename">conglomerate</code>. Detailed instructions for doing this can be found <a href="http://developer.gnome.org/tools/cvs.html" target="_top">here</a>. </p><p>You'll need Gnome 2.0 installed (or a more recent version) to build on top of. You will also need the <code class="filename">gnome-common</code>module from GNOME CVS. </p><p>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.</p><p>The CVS tree can be browsed <a href="http://cvs.gnome.org/bonsai/rview.cgi?dir=conglomerate&amp;cvsroot=/cvs/gnome&amp;module=default" target="_top">here</a>.</p></td></tr></tbody></table></div></div></body></html>
signature.asc
(application/pgp-signature, 189 B)
-----BEGIN PGP SIGNATURE----- Version: GnuPG v1.2.5 (GNU/Linux) iD8DBQBCfiIi9PtDMvDDTqYRAgrKAJ9molfA0TyHEWFJaAe7uPCEWrK5fgCfVDnM W1qZzKM87yMXoSTzCrPLd/0= =I5Yg -----END PGP SIGNATURE-----