Re: TEI/TEI lite support

On Tue, 2004-02-03 at 11:00, Roberto Rosselli Del Turco wrote:
> Il lun, 2004-02-02 alle 16:30, Dave Malcolm ha scritto:
> 
> > As I said, it doesn't usually matter if your dispspec contains more
> > elements than are in the DTD. You can have a dispspec that contains
> > simply the union of all possible elements.  The trouble is that at the
> > moment, each dispspec is only expected to associate with a single DTD. 
> > There isn't a mechanism yet for dealing with this kind of "family of
> > DTDs" approach.  We could use entities to reuse fragments of xds file
> > and have a big family of xds files, perhaps.
> 
> I was thinking about something like that, but of course you're the one
> knowing what's possible.
> 
> > Need to think this through, and consider what to do with similar
> > approaches.  For example, this feels similar to the problem of when
> > someone wants to edit instances of a customised version of the DocBook
> > DTD.
> > 
> > Perhaps we should focus on TEI Lite for the moment?
> 
> Yes, my (implicit) conclusion too.

OK.   So we'll probably have a single file called "teixlite.xds" in
Conglomerate's examples subfolder (to match the dtd filename)?

[snip]

> > 
> > Looks like Conglomerate didn't do a great job of generating the xds
> > file, but it's a start.  Some issues to look at:
> > - sort out the external-document-model element so that it knows about
> > the DTD
> 
> Hmm, can you elaborate on this? I'm not sure I understand what you mean.

The public-id and system-id attributes should be set to give the
information normally supplied in a DOCTYPE declaration.  By way of
reference, the equivalent tag in the docbook xds file looks like this:
<external-document-model type="dtd" public-id="-//OASIS//DTD DocBook XML
V4.1.2//EN"
system-id="http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"/>

This can be used by Conglomerate to spot when a particular DTD is in
use; also if you go to File->Properties there's a GUI for adding DOCTYPE
declarations to a document which uses this part of the dispspec.

It's best to supply both a public ID that's the formal public ID, and a
system ID that's a URI, rather than a reference to a locally installed
file.  Hopefully the user should have the file in their catalog so that
libxml can find the local copy...

> 
> > - fix the name and description in the metadata
> 
> OK.
> 
> > - possibly remove the xml:lang attributes from the <name> elements
> 
> xml:lang="C" looks pretty useless to me.

Yes, it probably should be removed (simple search & replace)

> 
> > - possibly remove all the <name> elements, or fix them so they make
> > sense.
> 
> I have prepared a similar list for the gedit tag list plugin: I usually
> expanded where possible (e.g. Paragraph for the <p> element) and left
> unmodified those that make sense on their own  (e.g. Imprint).

Excellent.

> 
> > - use plugins where appropriate
> 
> Hmm, what plugins are available? what do they do? where can I read about
> those?

No documentation at the moment, so I'll write some here, once I've sent
this email I'm going to put this into the FAQ:

Custom Rendering of an XML element:
-----------------------------------
Most of the element types are either "structural" or "span".   It's
possible to supply a custom type using the plugin system.  This will
affect how elements of that type are displayed in Conglomerate's main
editor widget.

Currently existing IDs:
-----------------------
"paragraph":  This is used by the DocBook <para> 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.

"admonition": This is used by DocBook's admonition elements: <note>,
<tip>, <caution> 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.

"listitem":  This is used by DocBook's <listitem> 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
<orderedlist> or an <itemizedlist>, 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.

Setting this up inside the 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
"plugin-id" (I hope to rename this to "service-id" before the 0.8.0
release), 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.

Customising the Property dialog for an XML element:
---------------------------------------------------
Another thing you can do to improve support for a DTD is to create a
plugin node property dialog.  To do this, add a <property-dialog> 
element inside the main <element>, with a "plugin-id" attribute giving
the registered ID of the code providing the GtkWidget for elements of
that type (again, this will probably become "service-id" before the
0.8.0 release).  

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.

> > - add icons
> 
> OK.
> 
> > Let the list know when you've got a new xds file; I'm keen to add it.
> 
> OK!

Don't feel like you have to sort out all of the above before submitting
something.  As soon as you've got something that works on some test
documents it's probably worth posting it so we can add to CVS (and to
the tarballs).  Refinements can happen at a later stage.

> 
> > Thanks!
> 
> You're welcome :)
> 
> Ciao