Re: Entities in Mallard

[Shaun McCance <shaunm gnome org>]

On Mon, 2009-06-29 at 11:17 -0500, Jim Campbell wrote:
> Hi All,
> 
> For us Ubuntu folks, we use entities to store software version numbers
> ("This release includes Python {version number}"), release names
> (e.g., Karmic Koala), & click-paths to various applications, but I'm
> not sure how other distros' doc teams may or may not use entities.
> I've found using them to be particularly helpful when sharing
> documents across flavors of Ubuntu... even though Ubuntu and Xubuntu
> may share an application as part of the default install, the
> click-path location will be different between Ubuntu and Xubuntu.
> 
> Because Mallard uses a Relax NG schema, I started checking into Relax
> NG schemas a bit, and see that they do not allow for the use of
> entities in the same way that is available through a DTD.  I haven't
> done a lot of checking yet, but there may be some workarounds . . . To
> be honest, though, I really just don't know at this point.
> 
> I only bring this up because, since we use entities & a Relax NG
> schema doesn't natively accommodate them, then we will need to find a
> way around this.  That, or we'll just need to be prepared to have
> scripts in place that can help automate some of the text conversion
> that entities allow.
> 
> If anyone has any thoughts or suggestions on this for now, please
> share.  Is this something that could be worked around?  If so, what
> could we do?

So in order to use entities, you'll need to have a DOCTYPE
declaration, even if you're not using it for validation.
Put this at the top of your XML file:

<!DOCTYPE page [
<!ENTITY foo "bar">
]>

Of course, if you're using the same entities in a bunch of
pages, you probably don't want to define them all over and
over again.  You can define them all at once in one file.
Let's go with foo.ent:

<!ENTITY fe "fi">
<!ENTITY fo "fum">

Then in your XML files, you do this:

<!DOCTYPE page [
<!ENTITY % foo SYSTEM "foo.ent">
%foo;
]>

(If you're using gnome-doc-utils to build and install your
documentation, add foo.ent to DOC_ENTITIES.  I'm almost
certain that will work without any problems.  Let me know
if I'm wrong.)

If you want character entities, you should probably just
reuse the W3C character entities:

http://www.w3.org/TR/xml-entity-names/

To use these, put this at the top of your XML files:

<!DOCTYPE page [
<!ENTITY % w3centities PUBLIC
  "-//W3C//ENTITIES Combined Set//EN//XML"
  "http://www.w3.org/2003/entities/2007/w3centities-f.ent";
>
%w3centities;
]>

Now here's the tricky part.  We certainly do not want to
be hitting the network every time we load up a document.
In fact, Yelp refuses to do so, so on my machine these
entities won't work.

But there's this nice feature called XML catalogs that
allow you to locally install files and map public and
system identifiers to the local files.  This is used,
by the way, to resolve the DocBook DTDs we all use.

For the W3C entities to be a viable solution, somebody
is going to have to get them installed on the system
and registered in the XML catalog.  Two options:

1) Ubuntu decides it really wants to use the character
entities, so Ubuntu makes a package and makes sure it's
installed by default.

2) We decide upstream it's a nice feature, so we have
gnome-doc-utils install a copy of the character entities
and register it with the catalog.

My concern with (2) is that we risk conflicts in the
catalog if somebody else is doing the same thing.

Oh, and a caveat: DOCTYPE declarations are completely
ignorant of XML namespaces, so if you prefer to write
your Mallard docs like this:

<mal:page xmlns:mal="...">
  <mal:info>...</mal:info>
  <mal:title>...</mal:title>
  ...
</mal:page>

Then your DOCTYPE needs to look like this:

<!DOCTYPE mal:page [...]>


--
Shaun