[postgis-devel] Documentation and comments in tarball

[Sandro Santilli]

On Tue, Jan 10, 2012 at 08:30:38PM -0500, Greg Troxel wrote:

> So I modified (locally) pkgsrc/database/postgresql-postgis to build the
> documents, to find out what it took.  It turns out I had to add only
> libxslt (2.5 MB), docbook-xsl (13 MB), and ImageMagick (37 MB), which
> aren't all that huge (relatively, because one already needs postgresql
> itself, at 33MB for 8.4).
> 
> I'm guessing most people who build postgis from the tarball don't really
> want to regenerate the docs, so I lean to including them, because the
> build tools are somewhat large compared to what would have been needed
> anyway.

Note that building docs is not mandatory, they aren't built by default.
If all you need is _reading_ the manual you have convenient separate
downloads here: http://www.postgis.org/documentation/

>From a packaging point of view I think docs should be in a separate
package as well (postgis-doc).

> When I tried to build the documents (from the 1.5.3 tarball), I had the
> following problems.  I have patches for the first three - should I send
> them here, or file trac tickets and attach, or ?

Note that the documentation discussion is about 2.0, not 1.5.
Anyway, let's see each issue in turn.

>  - doc/Makefile.in uses bare 'make' for submakes, it should be $(MAKE)
>    so it uses the right command for where GNU make happens to be (gmake
>    on BSD, because make is BSD make)

Fixed for 1.5 branch with r8761, 2.0 with r8763.

>  - generator fails to clear the malloced 'filename' variable, and copies
>    one too few bytes of "../images/", not getting the trailing null,
>    resulting in garbage filenames.  (Does malloc on Linux clear the
>    returned bytes (posix says the contents are unspecified)?  I don't
>    see how this could have worked.)

Known bug: http://trac.osgeo.org/postgis/ticket/1146
Fixed in 2.0 around 3 weeks ago, now also backported in 1.5 (with r8764).

>  - doc/Makefile.in installs to $(PGSQL_MANDIR) etc. without prefixing
>    $(DESTDIR), so a DESTDIR install (as used by pkgsrc to create
>    packages unprived before installation) fails.  (The rest of postgis
>    correctly uses DESTDIR.)

Also fixed in 2.0 (ticket #1184). Now backported (r8765).

>  - the docs install step uses cp instead of $(INSTALL_DATA) (as
>    postgis/Makefile.pgxs does) (minor)

Please file a ticket for this, with a patch if possible.

>  - gmake install in docs/ doesn't install the images, and doesn't
>    install style.css, but the generated html seems to refer to it.  How
>    is this supposed to get installed?

Another ticket for this (but I wouldn't target 1.5).

>  - there seems not to be a single top-level build/install target to
>    invoke if one wants code/doc/comments all at once.

This is by design, as the documentation aren't build by default.

> (Currently, the published pkgsrc entry doesn't try to build documents,
> and has a hand-constructed makefile target to copy the built docs to
> DESTDIR.)
> 
> I can also report that (with geos 3.3.2 and postgresql 8.4), postgis
> 1.5.3 on NetBSD/i386 5_STABLE passes 'gmake check' 100% (as does geos).

Great to hear that, thanks for testing !

--strk;

  ()   Free GIS & Flash consultant/developer
  /\   http://strk.keybit.net/services.html