Thread: Cross-references (was [PATCHES] PQescapeBytea documentation patch)

[ redirected from patches to pgsql-docs ]

Joe Conway <joseph.conway@home.com> writes:
> I was trying (but gave up) to cross-reference back to the input escape
> table in the User's Guide, but could not get the documentation to
> compile with a cross-book xref (missing IDREF error). Can a cross-book
> xref be done?

AFAIK, not.  If you look around you'll notice a bunch of vague cross-
references like

    See the <citetitle>Administrator's Guide</> for details.

This pretty much sucks but as long as we maintain the notion that the
books should be separately buildable, I'm not sure there's a way to do
better.

As far as readers go, I don't see that there's any need for anything
but the integrated document --- and we could do better cross-references
in that setting than we are doing.  The one good thing about the
separate books is that you can build just one (to check the markup of
a section you're working on) in a reasonable amount of time.  Building
the integrated doc seems to take forever :-(

Anyone see a way out of this dilemma?

            regards, tom lane

Tom Lane wrote:

> AFAIK, not.  If you look around you'll notice a bunch of vague cross-
> references like
>
>     See the <citetitle>Administrator's Guide</> for details.
>
> This pretty much sucks but as long as we maintain the notion that the
> books should be separately buildable, I'm not sure there's a way to do
> better.


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.



Joe

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