Received: from maia.hub.org (maia-5.hub.org [200.46.204.29])
	by mail.postgresql.org (Postfix) with ESMTP id 560181337BD0;
	Tue,  5 Apr 2011 15:55:14 -0300 (ADT)
Received: from mail.postgresql.org ([200.46.204.86])
	by maia.hub.org (mx1.hub.org [200.46.204.29]) (amavisd-maia, port 10024)
	with ESMTP id 70187-05; Tue,  5 Apr 2011 18:55:04 +0000 (UTC)
X-Greylist: domain auto-whitelisted by SQLgrey-1.7.6
X-Greylist: domain auto-whitelisted by SQLgrey-1.7.6
Received: from mail-ww0-f50.google.com (mail-ww0-f50.google.com
 [74.125.82.50])
	by mail.postgresql.org (Postfix) with ESMTP id 0F8171337BCF;
	Tue,  5 Apr 2011 15:55:02 -0300 (ADT)
Received: by wwc33 with SMTP id 33so802293wwc.19
	for <multiple recipients>; Tue, 05 Apr 2011 11:55:02 -0700 (PDT)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=gamma;
	h=domainkey-signature:mime-version:in-reply-to:references:date
	:message-id:subject:from:to:cc:content-type
	:content-transfer-encoding;
	bh=SXGEySSIuky+D0jdnyBh2V9wZfSfSYMoxxk1J30AvWw=;
	b=vlWYAU+FFIA8bYHGscfAolNm+hCOekYvpiWUg9xhx+vrkb4dcjxMLt/coc/OjrIoHe
	d/JGSTzlB/LfLMu8Zk13JyV9ObS7gNQvuUPCdlrrxhbeKkR0Rajs/kTEnbnM5dBfocNw
	sln+iGHSmrZDcfv/P4fSWQ/iL01Vfwxb82qLw=
DomainKey-Signature: a=rsa-sha1; c=nofws; d=gmail.com; s=gamma;
	h=mime-version:in-reply-to:references:date:message-id:subject:from:to
	:cc:content-type:content-transfer-encoding;
	b=TWuwmcmUlewJLSlBQZREyKAWYLg8W8GEvxhNORz8bDB/XLkhwML4xcMXtOjgapDxGk
	W9ReJ0Rir8zU9kHzkMfdLr4VQmtXXCaNe+qG9ZKcIe+7eHxM2On6f9novGzNes2WTMci
	np1ai7r3vN2Hse3ZLMMTnKXz8uv0JnAUvFzxM=
MIME-Version: 1.0
Received: by 10.216.69.203 with SMTP id n53mr5432381wed.88.1302029701536; Tue,
	05 Apr 2011 11:55:01 -0700 (PDT)
Received: by 10.216.120.135 with HTTP; Tue, 5 Apr 2011 11:55:00 -0700 (PDT)
In-Reply-To: <1302027484.27487.13.camel@vanquo.pezone.net>
References: <4D998B49.8050000@2ndQuadrant.it>
	<BANLkTikwxtb9MU-Bn7XqCJSCEdEuJPL+Lg@mail.gmail.com>
	<4D99F09D.3000606@2ndQuadrant.it> <1503.1301935044@sss.pgh.pa.us>
	<4D99FF55.9070301@2ndQuadrant.com>
	<BANLkTinSEBwkFNb7+Ow6+PgR8pKPOj+WGQ@mail.gmail.com>
	<BANLkTi=Ux689MQP0UYLwP6b8fL3m1Do6LA@mail.gmail.com>
	<1302027484.27487.13.camel@vanquo.pezone.net>
Date: Tue, 5 Apr 2011 14:55:00 -0400
Message-ID: <BANLkTikPd3T0OK27aOohuxRqNWMYmPserQ@mail.gmail.com>
Subject: Re: [HACKERS] Uppercase SGML entity declarations
From: Robert Haas <robertmhaas@gmail.com>
To: Peter Eisentraut <peter_e@gmx.net>
Cc: Christopher Browne <cbbrowne@gmail.com>,
	Susanne Ebrecht <susanne@2ndquadrant.com>, Tom Lane <tgl@sss.pgh.pa.us>,
	Gabriele Bartolini <gabriele.bartolini@2ndquadrant.it>,
	pgsql-docs@postgresql.org,
	PostgreSQL-development <pgsql-hackers@postgresql.org>
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: quoted-printable
X-Virus-Scanned: Maia Mailguard 1.0.1
X-Spam-Status: No, hits=-1.899 tagged_above=-5 required=5 tests=BAYES_00=-1.9,
	FREEMAIL_FROM=0.001
X-Spam-Level: 
X-Archive-Number: 201104/47
X-Sequence-Number: 6618

On Tue, Apr 5, 2011 at 2:18 PM, Peter Eisentraut <peter_e@gmx.net> wrote:
> On m=E5n, 2011-04-04 at 15:02 -0400, Robert Haas wrote:
>> AFAICT, the biggest problem with our existing toolchain is that it's
>> hard for some people to get it working. =A0In theory, we have
>> documentation that explains this:
>>
>> http://www.postgresql.org/docs/current/static/docguide-toolsets.html
>>
>> However, in contrast to the vast majority of our documentation, it
>> stinks.
>
> Umm, if you look under "Debian Packages", there is a one-line command to
> execute, which, as far as I can tell, is pretty much guaranteed to get
> you going. =A0If that doesn't apply to the OS you are working, then eithe=
r
>
> a) You haven't contributed better installation documentation, or
>
> b) The makers of your OS haven't bothered to package it properly.
>
> No other toolchain will make that principle easier.

I don't know whether some other toolchain would be easier or not.  I
believe that the directions for RPM installation aren't completely
up-to-date; I think you need docbook-style-dsssl at least on newer
Fedoras, and there isn't any stylesheet package on such systems.
There are also no directions for MacOS X at all.  My biggest gripe is
that when things fail, it's often not obvious what the problem is.
I've had failures due to missing packages (but the package that's
missing is far from obvious) and I've also had failures, I believe,
from not being connected to the Internet, which is surprising because
it's not at all obvious that building the docs should require an
Internet connection.  At least if you are missing something like zlib
it says "checking for zlib... not found".  And while it may be that
you have zlib and are missing zlib-devel, it at least gets you pointed
in the right direction, whereas the docbook stuff tends to spew out 50
pages of error messages that I at least don't find terribly intuitive.

--=20
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company