pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedCross-references (was [PATCHES] PQescapeBytea documentation patch)
3+ messages / 3 participants
[nested] [flat]
* Cross-references (was [PATCHES] PQescapeBytea documentation patch)
@ 2001-11-20 21:09 Tom Lane <tgl@sss.pgh.pa.us>
0 siblings, 1 reply; 3+ messages in thread
From: Tom Lane @ 2001-11-20 21:09 UTC (permalink / raw)
To: Joe Conway <joseph.conway@home.com>; +Cc: pgsql-docs
[ 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
^ permalink raw reply [nested|flat] 3+ messages in thread
* Re: Cross-references (was [PATCHES] PQescapeBytea documentation patch)
@ 2001-11-20 23:02 Joe Conway <joseph.conway@home.com>
parent: Tom Lane <tgl@sss.pgh.pa.us>
0 siblings, 1 reply; 3+ messages in thread
From: Joe Conway @ 2001-11-20 23:02 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: pgsql-docs
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
^ permalink raw reply [nested|flat] 3+ messages in thread
* Re: Cross-references (was [PATCHES] PQescapeBytea documentation
@ 2001-11-21 22:12 Peter Eisentraut <peter_e@gmx.net>
parent: Joe Conway <joseph.conway@home.com>
0 siblings, 0 replies; 3+ messages in thread
From: Peter Eisentraut @ 2001-11-21 22:12 UTC (permalink / raw)
To: Joe Conway <joseph.conway@home.com>; +Cc: Tom Lane <tgl@sss.pgh.pa.us>; pgsql-docs
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
^ permalink raw reply [nested|flat] 3+ messages in thread
end of thread, other threads:[~2001-11-21 22:12 UTC | newest]
Thread overview: 3+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2001-11-20 21:09 Cross-references (was [PATCHES] PQescapeBytea documentation patch) Tom Lane <tgl@sss.pgh.pa.us>
2001-11-20 23:02 ` Joe Conway <joseph.conway@home.com>
2001-11-21 22:12 ` Re: Cross-references (was [PATCHES] PQescapeBytea documentation Peter Eisentraut <peter_e@gmx.net>
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox