Re: Cross-references (was [PATCHES] PQescapeBytea documentation

Joe Conway writes:

> I did find a reference to a docbook tag which *might* be useful, if we
> can figure out how to use it. See:
>
> http://www.oasis-open.org/docbook/documentation/reference/html/olink.html
>
> The TargetDocEnt parameter seems to be defined in filelist.sgml, but it
> isn't clear to me what the other parameters should be.

In theory, <olink> would be the right solution, but it requires you to
declare all the possible links explicitly beforehand, and at a place which
is not near your actual link.  I think this would be much too complicated
to set up and maintain.

It's currently possible to do cross-document links like this:

| For more information, see <![%set-of-books;[<xref
| linkend="whereever">]]><![%single-book;[the <citetitle>Administrator's
| Guide</citetitle>]]>.

(Think of this as equivalent to #ifdef's.)

However, this is pretty ugly, and I think we don't want to expand too much
on this mechanism because it doesn't work in XML.

I imagine we could work out a solution which works like this:  <xref
linkend="somewhere" role="if-missing:<citetitle>Administrator's
Guide</citetitle>"> (the role attribute is available for arbitrary
customization, which we'd need to write), but the trick is that ID
checking is done during the SGML parsing stage, which is before stylesheet
processing, so that you'd still get warnings (errors?) about undefined
ids.  Possibly, we could convince the olink element to fit this idea, but
then we'd need to write the entire olink processing anew.

So, a short-term solution isn't in sight.

--
Peter Eisentraut   peter_e@gmx.net