Push Content

Shaun McCance <shaunm at gnome.org>
Wed Apr 14 14:09:56 EDT 2010

Hi folks,

I was just reading about the conref push feature in DITA 1.2.
This was suggested to me as something that might accomplish
something similar to Mallard's reverse guide-linking.

http://dita.xml.org/resource/dita-12-feature-article-conref-push

Conrefs are a content transclusion mechanism, i.e. a way to
pull content from another XML file into a document. Excepting
the new push features, I don't understand what advantages it
has over XInclude with XPointer.

The new push feature, however, allows you to replace or add to
existing content by putting push conrefs into separate resource
files.

It's not clear to me if there are restrictions on where you can
use this feature. It could somewhat mimic guide links by adding
topicrefs to a map. For a single upstream document augmented by
a single downstream distributor, it would probably work. But I
think it would break down with massively cooperative guides,
where multiple packages put their own links in. (Think plugins
for an application.) We refined the link grouping and ordering
in Mallard a few times, and you wouldn't get that here.

That said, this feature is actually much more general. You can
insert or replace content just about anywhere. So, for example,
if Ubuntu needed to change a paragraph in a Gnome document,
they could provide a resource that does that without patching
the original file.

We have nothing like this in Mallard, though there have been
vague what-ifs over the years. Here's a this-if:

Define some sort of info files for additional resources for
a Mallard document. This would be useful for other features,
like the dynamic glossaries we've talked about.

In these info files, you can put actions that will be applied
to pages. We could have actions for replace, insert after,
insert before, append to, and prepend to. Or whatever we find
useful. Actions would declare a page and an XPointer, and then
provide content to use.

foo.page:
  <page id="foo">
  <title>A Page</title>
  <p xml:id="replace-me">This paragraph might change.</p>
  </page>

distro.info:
  <info>
  <replace xref="foo" xpointer="xpointer(id('replace-me'))">
  <p>This is new content.</p>
  </replace>
  </info>

After processing:
  <page id="foo">
  <title>A Page</title>
  <p>This is new content.</p>
  </page>

(Omitted namespaces for brevity.)

I don't immediately see a way to do this fast in XSLT. But
it could be done quite fast as a pre-processing step to the
XML document in an application like Yelp.

Is this a feature people are interested in pursuing? There
is no reason this would have to live in the core spec. We
could have an extension for Mallard actions.

--
Shaun