Re: [HACKERS] Uppercase SGML entity declarations

On Tue, Apr 5, 2011 at 2:18 PM, Peter Eisentraut <peter_e(at)gmx(dot)net> wrote:
> On mån, 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.  In 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.  If that doesn't apply to the OS you are working, then either
>
> 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.

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