[postgis-devel] Documentation and comments in tarball

[Greg Troxel]

Sandro Santilli <strk at keybit.net> writes:

>> The thing is: if you just want to _read_ the documentation, get a binary 
>> package for them.

I don't follow -- I'm talking about the process that produces the binary
package that includes the compiled code and the formatted documentation,
and by 'as a packager' I meant 'writing the control files that allow a
user to create a binary package on multiple os/version/cpu combinations
without having to understand any of this'.

>> If you want to contribute then you'll need the additional
>> dependencies anyway.

Understood, and that's of course fine.

So, I think the question is whether it hurts more to have the prebuilt
html/images or to make all package builds force the xml toolchain to be
installed.  It used to seem like docbook conversion required a huge
amount of packages, but now xsltproc is not so big.

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.

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 ?

 - 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)

 - 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.)

 - 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.)

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

 - 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?

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

(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).

Greg


-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 194 bytes
Desc: not available
URL: <http://lists.osgeo.org/pipermail/postgis-devel/attachments/20120110/33ba8047/attachment.sig>