Re: pgsql: Ship documentation without intermediate tarballs Documentation

Log Message:
-----------
Ship documentation without intermediate tarballs

Documentation files in HTML and man formats are now prepared for
distribution using the distprep make target, like everything else. They
are placed in doc/src/sgml/html and manX and installed from there by
make install, if present. The business with the tarballs in the tarball
is gone.

Modified Files:
--------------
pgsql:
GNUmakefile.in (r1.51 -> r1.52)
(http://anoncvs.postgresql.org/cvsweb.cgi/pgsql/GNUmakefile.in?r1=1.51&r2=1.52)
pgsql/doc:
Makefile (r1.38 -> r1.39)
(http://anoncvs.postgresql.org/cvsweb.cgi/pgsql/doc/Makefile?r1=1.38&r2=1.39)
pgsql/doc/src:
Makefile (r1.36 -> r1.37)
(http://anoncvs.postgresql.org/cvsweb.cgi/pgsql/doc/src/Makefile?r1=1.36&r2=1.37)
pgsql/doc/src/sgml:
Makefile (r1.121 -> r1.122)
(http://anoncvs.postgresql.org/cvsweb.cgi/pgsql/doc/src/sgml/Makefile?r1=1.121&r2=1.122)
docguide.sgml (r1.77 -> r1.78)
(http://anoncvs.postgresql.org/cvsweb.cgi/pgsql/doc/src/sgml/docguide.sgml?r1=1.77&r2=1.78)
stylesheet.dsl (r1.34 -> r1.35)
(http://anoncvs.postgresql.org/cvsweb.cgi/pgsql/doc/src/sgml/stylesheet.dsl?r1=1.34&r2=1.35)
stylesheet.xsl (r1.3 -> r1.4)
(http://anoncvs.postgresql.org/cvsweb.cgi/pgsql/doc/src/sgml/stylesheet.xsl?r1=1.3&r2=1.4)
pgsql/src:
Makefile.global.in (r1.256 -> r1.257)
(http://anoncvs.postgresql.org/cvsweb.cgi/pgsql/src/Makefile.global.in?r1=1.256&r2=1.257)

petere(at)postgresql(dot)org (Peter Eisentraut) writes:
> Ship documentation without intermediate tarballs

After this patch, "make clean" in the doc/src/sgml directory no longer
does anything useful. Even "make distclean" fails to remove all the
cruft left behind by a build. This needs to be rethought a bit,
else we are going to be shipping tarballs containing junk.

regards, tom lane

On Monday 10 August 2009 09:26:33 Tom Lane wrote:
> petere(at)postgresql(dot)org (Peter Eisentraut) writes:
> > Ship documentation without intermediate tarballs
>
> After this patch, "make clean" in the doc/src/sgml directory no longer
> does anything useful. Even "make distclean" fails to remove all the
> cruft left behind by a build. This needs to be rethought a bit,
> else we are going to be shipping tarballs containing junk.

make maintainer-clean is supposed to remove "everything". make distclean is
supposed to remove things that are not supposed to be in the distribution. If
you can identifiy something that should not be in the distribution and is not
removed by distclean, let me know.

Peter Eisentraut <peter_e(at)gmx(dot)net> writes:
> On Monday 10 August 2009 09:26:33 Tom Lane wrote:
>> After this patch, "make clean" in the doc/src/sgml directory no longer
>> does anything useful. Even "make distclean" fails to remove all the
>> cruft left behind by a build. This needs to be rethought a bit,
>> else we are going to be shipping tarballs containing junk.

> make maintainer-clean is supposed to remove "everything". make distclean is
> supposed to remove things that are not supposed to be in the distribution. If
> you can identifiy something that should not be in the distribution and is not
> removed by distclean, let me know.

After doing "make" then "make distclean" in doc/src/sgml, I see the
following undesirable files left behind:

-rw-rw-r-- 1 tgl tgl 58 Aug 10 11:51 version.sgml
-rw-rw-r-- 1 tgl tgl 38548 Aug 10 11:51 features-unsupported.sgml
-rw-rw-r-- 1 tgl tgl 42014 Aug 10 11:51 features-supported.sgml
-rw-rw-r-- 1 tgl tgl 345398 Aug 10 11:52 HTML.index
-rw-rw-r-- 1 tgl tgl 298859 Aug 10 11:52 bookindex.sgml
-rw-rw-r-- 1 tgl tgl 0 Aug 10 11:53 html-stamp

I would argue that both "make clean" and "make distclean" should remove
these.

Also, we seem to need .cvsignore entries for the html/ and manN/
subdirectories. IMO the policy for .cvsignore is that anything
intentionally left behind by make distclean is to be cvsignore'd.

regards, tom lane

Peter Eisentraut wrote:
> Log Message:
> -----------
> Ship documentation without intermediate tarballs
>
> Documentation files in HTML and man formats are now prepared for
> distribution using the distprep make target, like everything else. They
> are placed in doc/src/sgml/html and manX and installed from there by
> make install, if present. The business with the tarballs in the tarball
> is gone.

Hmm, I notice that this rule to install manpages is pretty slow:

for file in /pgsql/source/00head/doc/src/sgml/man1/*.1 /pgsql/source/00head/doc/src/sgml/man3/*.3 /pgsql/source/00head/doc/src/sgml/man7/*.7; do /bin/sh /pgsql/source/00head/config/install-sh -c -m 644 $file /pgsql/install/00head/share/man/`echo $file | sed 's,^/pgsql/source/00head/doc/src/sgml/,,'` || exit; done

Can we use "basename" here instead of the `echo | sed` hack?

Hmm, oh, I see it's stripping everything except the last directory level.
I guess I'd go for doing a simple cp inside each man directory.

--
Alvaro Herrera http://www.CommandPrompt.com/
The PostgreSQL Company - Command Prompt, Inc.

On Monday 10 August 2009 23:03:12 Alvaro Herrera wrote:
> Hmm, I notice that this rule to install manpages is pretty slow:
>
> for file in /pgsql/source/00head/doc/src/sgml/man1/*.1
> /pgsql/source/00head/doc/src/sgml/man3/*.3
> /pgsql/source/00head/doc/src/sgml/man7/*.7; do /bin/sh
> /pgsql/source/00head/config/install-sh -c -m 644 $file
> /pgsql/install/00head/share/man/`echo $file | sed
> 's,^/pgsql/source/00head/doc/src/sgml/,,'` || exit; done
>
> Can we use "basename" here instead of the `echo | sed` hack?
>
> Hmm, oh, I see it's stripping everything except the last directory level.
> I guess I'd go for doing a simple cp inside each man directory.

Yeah, that was really freakishly complicated. Fixed now.

Peter Eisentraut wrote:
> On Monday 10 August 2009 23:03:12 Alvaro Herrera wrote:
> > Hmm, I notice that this rule to install manpages is pretty slow:

> Yeah, that was really freakishly complicated. Fixed now.

It is much better now, thanks.

--
Alvaro Herrera http://www.CommandPrompt.com/
PostgreSQL Replication, Consulting, Custom Development, 24x7 support

On Monday 10 August 2009 18:59:51 Tom Lane wrote:
> After doing "make" then "make distclean" in doc/src/sgml, I see the
> following undesirable files left behind:
>
> -rw-rw-r-- 1 tgl tgl 58 Aug 10 11:51 version.sgml
> -rw-rw-r-- 1 tgl tgl 38548 Aug 10 11:51 features-unsupported.sgml
> -rw-rw-r-- 1 tgl tgl 42014 Aug 10 11:51 features-supported.sgml
> -rw-rw-r-- 1 tgl tgl 345398 Aug 10 11:52 HTML.index
> -rw-rw-r-- 1 tgl tgl 298859 Aug 10 11:52 bookindex.sgml
> -rw-rw-r-- 1 tgl tgl 0 Aug 10 11:53 html-stamp
>
> I would argue that both "make clean" and "make distclean" should remove
> these.

OK, I fixed that, but html-stamp has to stay to keep the dependencies
satisfied. (Well, there are alternatives. We could make the whole thing
depend on html/index.html or whatever.)

> Also, we seem to need .cvsignore entries for the html/ and manN/
> subdirectories. IMO the policy for .cvsignore is that anything
> intentionally left behind by make distclean is to be cvsignore'd.

Fixed.