To: Josh Berkus <josh@agliodbs.com>
Cc: Peter Eisentraut <peter_e@gmx.net>, pgsql-docs@postgresql.org
Subject: Re: Need help with SGML again 
In-reply-to: <200310150946.01052.josh@agliodbs.com> 
References: <Pine.LNX.4.44.0310150914440.20107-100000@peter.localdomain>
	<200310150946.01052.josh@agliodbs.com>
Comments: In-reply-to Josh Berkus <josh@agliodbs.com>
	message dated "Wed, 15 Oct 2003 09:46:01 -0700"
Date: Wed, 15 Oct 2003 13:22:13 -0400
Message-ID: <16736.1066238533@sss.pgh.pa.us>
From: Tom Lane <tgl@sss.pgh.pa.us>

Josh Berkus <josh@agliodbs.com> writes:
> Peter,
>> 1. Linking to anything that is not a formal object (having a title and a
>> number) does not render well in print.  ("for more information, see
>> paragraph 3 on page 15"?)

> I see what you mean.   Given that I do 95% of my doc browsing in HTML, this 
> seems very redundant to me, though; I think it would be interesting to see 
> how many users refer to a paper version of the docs.  We may find it's a tiny
> minority.

That was my reaction as well.  While I don't want to make the paper
version unusable, I think that the HTML version is considerably more
important.

The compromise I would propose is to do the cross-linking as Josh
wanted, and to have the links in the HTML version go directly to the
paragraphs describing the variables, but in the paper version have the
links just refer to the containing numbered subsections.  (Dunno how
practical this is to implement, though.)

I don't much care for any of the three alternatives Josh mentions,
although if pressed I would opt for duplicating the info.  That might
be the best answer anyway, since the descriptions appropriate in the
main listing might be too terse for novices; that is, I'm not sure the
duplication would or should be exact.

			regards, tom lane