Thread: Cannot build docs on Ubuntu 10.04?

Cannot build docs on Ubuntu 10.04?

From

Josh Berkus

Date:

12 January 2012, 19:05:06

What packages and versions do I need to install to build the docs on Ubuntu?

I tried 10.04's version of Openjade, which wasn't recognized, and with
"jade" I got:

postgres@31214-1-950145:/usr/local/src/test$ make docs
make -C doc all
make[1]: Entering directory `/usr/local/src/test/doc'
make -C src all
make[2]: Entering directory `/usr/local/src/test/doc/src'
make -C sgml all
make[3]: Entering directory `/usr/local/src/test/doc/src/sgml'
jade  -wall -wno-unused-param -wno-empty -wfully-tagged -D . -D .  -d
stylesheet.dsl -t sgml -i output-html -V html-index postgres.sgml
jade:E: unknown warning type "fully-tagged"
jade:postgres.sgml:3:55:W: cannot generate system identifier for public
text "-//OASIS//DTD DocBook V4.2//EN"
jade:postgres.sgml:12:0:E: reference to entity "BOOK" for which no
system identifier could be generated
jade:postgres.sgml:3:0: entity was defined here

... and lots of other errors, eventually fatal.

Requirements for building the docs are not documented in our docs.

--
Josh Berkus
PostgreSQL Experts Inc.
http://pgexperts.com

Re: Cannot build docs on Ubuntu 10.04?

From

"Kevin Grittner"

Date:

12 January 2012, 19:17:25

Josh Berkus <josh@agliodbs.com> wrote:

> What packages and versions do I need to install to build the docs
> on Ubuntu?
>
> I tried 10.04's version of Openjade, which wasn't recognized

> Requirements for building the docs are not documented in our docs.

I did find that getting the doc build going was a bit fussy, even
after reading the docs on it:

http://www.postgresql.org/docs/current/static/docguide.html

There were recently some posts that helped me clear up a lot of
warnings I was getting, which basically boiled down to the need to
install the opensp package.

-Kevin

Re: Cannot build docs on Ubuntu 10.04?

From

Josh Berkus

Date:

12 January 2012, 19:23:34

> http://www.postgresql.org/docs/current/static/docguide.html
>
> There were recently some posts that helped me clear up a lot of
> warnings I was getting, which basically boiled down to the need to
> install the opensp package.

Yeah, that guide isn't much help, because the named requirements don't
relate at all to debian/ubuntu packages.

We'd probably get more help on the docs if it wasn't a day-long effort
to build them.  Sphinx anyone?

--
Josh Berkus
PostgreSQL Experts Inc.
http://pgexperts.com

Re: Cannot build docs on Ubuntu 10.04?

From

Josh Berkus

Date:

12 January 2012, 19:28:45

To be more specific, having installed all of the requirements listed in
builddocs, I'm still getting a fatal error:

make[3]: Entering directory `/usr/local/src/test/doc/src/sgml'
{ \
      echo "<!ENTITY version \"9.2devel\">"; \
      echo "<!ENTITY majorversion \"9.2\">"; \
    } > version.sgml
'/usr/bin/perl' ./mk_feature_tables.pl YES
../../../src/backend/catalog/sql_feature_packages.txt
../../../src/backend/catalog/sql_features.txt > features-supported.sgml
'/usr/bin/perl' ./mk_feature_tables.pl NO
../../../src/backend/catalog/sql_feature_packages.txt
../../../src/backend/catalog/sql_features.txt > features-unsupported.sgml
'/usr/bin/perl' ./generate-errcodes-table.pl
../../../src/backend/utils/errcodes.txt > errcodes-table.sgml
jade  -wall -wno-unused-param -wno-empty -wfully-tagged -D . -D .  -d
stylesheet.dsl -t sgml -i output-html -V html-index postgres.sgml
jade:E: unknown warning type "fully-tagged"
LC_ALL=C '/usr/bin/perl' /bin/collateindex.pl -f -g -i 'bookindex' -o
bookindex.sgml HTML.index
Can't open perl script "/bin/collateindex.pl": No such file or directory
make[3]: *** [bookindex.sgml] Error 2


--
Josh Berkus
PostgreSQL Experts Inc.
http://pgexperts.com

Re: Cannot build docs on Ubuntu 10.04?

From

Josh Berkus

Date:

12 January 2012, 20:16:58

On 1/12/12 12:28 PM, Josh Berkus wrote:
> To be more specific, having installed all of the requirements listed in
> builddocs, I'm still getting a fatal error:
>
> make[3]: Entering directory `/usr/local/src/test/doc/src/sgml'
> { \
>       echo "<!ENTITY version \"9.2devel\">"; \
>       echo "<!ENTITY majorversion \"9.2\">"; \
>     } > version.sgml
> '/usr/bin/perl' ./mk_feature_tables.pl YES
> ../../../src/backend/catalog/sql_feature_packages.txt
> ../../../src/backend/catalog/sql_features.txt > features-supported.sgml
> '/usr/bin/perl' ./mk_feature_tables.pl NO
> ../../../src/backend/catalog/sql_feature_packages.txt
> ../../../src/backend/catalog/sql_features.txt > features-unsupported.sgml
> '/usr/bin/perl' ./generate-errcodes-table.pl
> ../../../src/backend/utils/errcodes.txt > errcodes-table.sgml
> jade  -wall -wno-unused-param -wno-empty -wfully-tagged -D . -D .  -d
> stylesheet.dsl -t sgml -i output-html -V html-index postgres.sgml
> jade:E: unknown warning type "fully-tagged"
> LC_ALL=C '/usr/bin/perl' /bin/collateindex.pl -f -g -i 'bookindex' -o
> bookindex.sgml HTML.index
> Can't open perl script "/bin/collateindex.pl": No such file or directory
> make[3]: *** [bookindex.sgml] Error 2

So apparently I needed to do a "make distclean" and then ./configure
again after installing a couple of the missing packages.  Built now.

--
Josh Berkus
PostgreSQL Experts Inc.
http://pgexperts.com

Re: Cannot build docs on Ubuntu 10.04?

From

Alvaro Herrera

Date:

12 January 2012, 20:17:02

Excerpts from Josh Berkus's message of jue ene 12 17:28:28 -0300 2012:
> To be more specific, having installed all of the requirements listed in
> builddocs, I'm still getting a fatal error:
>
> make[3]: Entering directory `/usr/local/src/test/doc/src/sgml'
> { \
>       echo "<!ENTITY version \"9.2devel\">"; \
>       echo "<!ENTITY majorversion \"9.2\">"; \
>     } > version.sgml
> '/usr/bin/perl' ./mk_feature_tables.pl YES
> ../../../src/backend/catalog/sql_feature_packages.txt
> ../../../src/backend/catalog/sql_features.txt > features-supported.sgml
> '/usr/bin/perl' ./mk_feature_tables.pl NO
> ../../../src/backend/catalog/sql_feature_packages.txt
> ../../../src/backend/catalog/sql_features.txt > features-unsupported.sgml
> '/usr/bin/perl' ./generate-errcodes-table.pl
> ../../../src/backend/utils/errcodes.txt > errcodes-table.sgml
> jade  -wall -wno-unused-param -wno-empty -wfully-tagged -D . -D .  -d
> stylesheet.dsl -t sgml -i output-html -V html-index postgres.sgml
> jade:E: unknown warning type "fully-tagged"
> LC_ALL=C '/usr/bin/perl' /bin/collateindex.pl -f -g -i 'bookindex' -o
> bookindex.sgml HTML.index
> Can't open perl script "/bin/collateindex.pl": No such file or directory
> make[3]: *** [bookindex.sgml] Error 2

Did you re-run configure after installing everything?  It seems to me
the path to collateindex.pl is not correctly set -- looks like a
variable expanding to empty string.

The warning about "unknown warning type" means you're using the wrong
tool to me.  My toolchain here uses "openjade" which is a fork of the
earlier jade (so install opensp as Kevin suggested, and rerun configure
after that); my guess is that we're pretty much dependent on openjade
features that did not exist in plain jade.  Maybe we should just get rid
of our attempts to use the older tool.

--
Álvaro Herrera <alvherre@commandprompt.com>
The PostgreSQL Company - Command Prompt, Inc.
PostgreSQL Replication, Consulting, Custom Development, 24x7 support

Re: Cannot build docs on Ubuntu 10.04?

From

Josh Berkus

Date:

12 January 2012, 20:43:57

> The warning about "unknown warning type" means you're using the wrong
> tool to me.  My toolchain here uses "openjade" which is a fork of the
> earlier jade (so install opensp as Kevin suggested, and rerun configure
> after that); my guess is that we're pretty much dependent on openjade
> features that did not exist in plain jade.  Maybe we should just get rid
> of our attempts to use the older tool.

Yeah, the problem is that if you install just "openjade" on
debian/ubuntu, it doesn't create the command "jade", which is what our
make script is looking for.


--
Josh Berkus
PostgreSQL Experts Inc.
http://pgexperts.com

Re: Cannot build docs on Ubuntu 10.04?

From

Euler Taveira de Oliveira

Date:

12 January 2012, 20:45:41

On 12-01-2012 17:28, Josh Berkus wrote:
> Can't open perl script "/bin/collateindex.pl": No such file or directory
> make[3]: *** [bookindex.sgml] Error 2
>
Did you install docbook-dsssl? It must contain that script.


--
   Euler Taveira de Oliveira - Timbira       http://www.timbira.com.br/
   PostgreSQL: Consultoria, Desenvolvimento, Suporte 24x7 e Treinamento

Re: Cannot build docs on Ubuntu 10.04?

From

Josh Berkus

Date:

12 January 2012, 20:51:11

On 1/12/12 1:43 PM, Euler Taveira de Oliveira wrote:
> On 12-01-2012 17:28, Josh Berkus wrote:
>> Can't open perl script "/bin/collateindex.pl": No such file or directory
>> make[3]: *** [bookindex.sgml] Error 2
>>
> Did you install docbook-dsssl? It must contain that script.

Per prior email, I needed to do a "make distclean" and re-configure.

--
Josh Berkus
PostgreSQL Experts Inc.
http://pgexperts.com

Re: Cannot build docs on Ubuntu 10.04?

From

Tom Lane

Date:

12 January 2012, 20:54:16

Josh Berkus <josh@agliodbs.com> writes:
> We'd probably get more help on the docs if it wasn't a day-long effort
> to build them.

[ shrug... ]  On Fedora, installing the "authoring/publishing tools"
package group has always gotten me everything needed.

            regards, tom lane

Re: Cannot build docs on Ubuntu 10.04?

From

Tom Lane

Date:

12 January 2012, 20:56:05

Josh Berkus <josh@agliodbs.com> writes:
> LC_ALL=C '/usr/bin/perl' /bin/collateindex.pl -f -g -i 'bookindex' -o
> bookindex.sgml HTML.index
> Can't open perl script "/bin/collateindex.pl": No such file or directory

On Fedora, that script comes in the docbook-style-dsssl package.  Don't
know how Ubuntu has chopped things up.

            regards, tom lane

Re: Cannot build docs on Ubuntu 10.04?

From

Alvaro Herrera

Date:

12 January 2012, 21:01:57

Excerpts from Josh Berkus's message of jue ene 12 18:43:39 -0300 2012:
>
> > The warning about "unknown warning type" means you're using the wrong
> > tool to me.  My toolchain here uses "openjade" which is a fork of the
> > earlier jade (so install opensp as Kevin suggested, and rerun configure
> > after that); my guess is that we're pretty much dependent on openjade
> > features that did not exist in plain jade.  Maybe we should just get rid
> > of our attempts to use the older tool.
>
> Yeah, the problem is that if you install just "openjade" on
> debian/ubuntu, it doesn't create the command "jade", which is what our
> make script is looking for.

BS.  You just neglected to rerun configure at that point.

# config/docbook.m4

# PGAC_PROG_JADE
# --------------
AC_DEFUN([PGAC_PROG_JADE],
[AC_CHECK_PROGS([JADE], [openjade jade])])



I think the main failure of the docs is to make it more prominent that
you need to rerun configure after you install stuff.

--
Álvaro Herrera <alvherre@commandprompt.com>
The PostgreSQL Company - Command Prompt, Inc.
PostgreSQL Replication, Consulting, Custom Development, 24x7 support

Re: Cannot build docs on Ubuntu 10.04?

From

Tom Lane

Date:

12 January 2012, 21:13:45

Alvaro Herrera <alvherre@commandprompt.com> writes:
> The warning about "unknown warning type" means you're using the wrong
> tool to me.  My toolchain here uses "openjade" which is a fork of the
> earlier jade (so install opensp as Kevin suggested, and rerun configure
> after that); my guess is that we're pretty much dependent on openjade
> features that did not exist in plain jade.  Maybe we should just get rid
> of our attempts to use the older tool.

Hm ... on my machine /usr/bin/jade is a symlink to openjade, anyway.

My recollection is that even with openjade, it won't work real well with
older versions because of assorted bugs in that tool that have been
fixed over time.  So original jade might be pretty hopeless by now.

            regards, tom lane

Re: Cannot build docs on Ubuntu 10.04?

From

Alvaro Herrera

Date:

12 January 2012, 21:37:42

Excerpts from Tom Lane's message of jue ene 12 18:55:41 -0300 2012:
> Josh Berkus <josh@agliodbs.com> writes:
> > LC_ALL=C '/usr/bin/perl' /bin/collateindex.pl -f -g -i 'bookindex' -o
> > bookindex.sgml HTML.index
> > Can't open perl script "/bin/collateindex.pl": No such file or directory
>
> On Fedora, that script comes in the docbook-style-dsssl package.  Don't
> know how Ubuntu has chopped things up.

$ dpkg -S collateindex.pl
docbook-dsssl: /usr/share/man/man1/collateindex.pl.1.gz
docbook-dsssl: /usr/bin/collateindex.pl

--
Álvaro Herrera <alvherre@commandprompt.com>
The PostgreSQL Company - Command Prompt, Inc.
PostgreSQL Replication, Consulting, Custom Development, 24x7 support

Re: Cannot build docs on Ubuntu 10.04?

From

Robert Haas

Date:

27 January 2012, 16:20:06

On Thu, Jan 12, 2012 at 4:50 PM, Josh Berkus <josh@agliodbs.com> wrote:
> On 1/12/12 1:43 PM, Euler Taveira de Oliveira wrote:
>> On 12-01-2012 17:28, Josh Berkus wrote:
>>> Can't open perl script "/bin/collateindex.pl": No such file or directory
>>> make[3]: *** [bookindex.sgml] Error 2
>>>
>> Did you install docbook-dsssl? It must contain that script.
>
> Per prior email, I needed to do a "make distclean" and re-configure.

So do we have a complete list of the packages needed on Ubuntu now,
that we could add to the documentation?  I grow weary of figuring this
out every time I set up a new machine.

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

Re: Cannot build docs on Ubuntu 10.04?

From

Peter Eisentraut

Date:

31 January 2012, 16:58:21

On fre, 2012-01-27 at 12:19 -0500, Robert Haas wrote:
> So do we have a complete list of the packages needed on Ubuntu now,
> that we could add to the documentation?  I grow weary of figuring this
> out every time I set up a new machine.

The list we have had in the documentation (under Debian) is correct.

Re: Cannot build docs on Ubuntu 10.04?

From

John Lumby

Date:

14 March 2012, 13:25:41

On 12-01-2012 17:28, Josh Berkus wrote:

> Can't open perl script "/bin/collateindex.pl": No such file or directory

On Thu, 12 Jan 2012 19:37:20 -0300 Alvaro Herrera wrote:
 >  dpkg -S collateindex.pl
docbook-dsssl:

 >  /usr/bin/collateindex.pl

I wonder if everyone noticed that the postgres sgml makefile is looking for the script in /bin
(see Josh's append)
but docbook-dssl puts it in /usr/bin
(see Alvaro's append).

I think this line in
postgresql-9.1.3/doc/src/sgml/Makefile

 COLLATEINDEX = $(DOCBOOKSTYLE)/bin/collateindex.pl

could be improved  -  maybe should read

COLLATEINDEX = `which collateindex.pl`

I fixed it by
 ln `which collateindex.pl` /bin/collateindex.pl

maybe this is what the "configure" that someone mentioned would have done?

Cheers,   John

Re: Cannot build docs on Ubuntu 10.04?

From

Alvaro Herrera

Date:

14 March 2012, 14:14:09

Excerpts from John Lumby's message of mié mar 14 10:25:19 -0300 2012:
>
> On 12-01-2012 17:28, Josh Berkus wrote:
>
> > Can't open perl script "/bin/collateindex.pl": No such file or directory
>
> On Thu, 12 Jan 2012 19:37:20 -0300 Alvaro Herrera wrote:
>  >  dpkg -S collateindex.pl
> docbook-dsssl:
>
>  >  /usr/bin/collateindex.pl
>
>
> I wonder if everyone noticed that the postgres sgml makefile is looking for the script in /bin
> (see Josh's append)
> but docbook-dssl puts it in /usr/bin
> (see Alvaro's append).
>
> I think this line in
> postgresql-9.1.3/doc/src/sgml/Makefile
>
>  COLLATEINDEX = $(DOCBOOKSTYLE)/bin/collateindex.pl
>
> could be improved  -  maybe should read
>
> COLLATEINDEX = `which collateindex.pl`
>
> I fixed it by
>  ln `which collateindex.pl` /bin/collateindex.pl
>
> maybe this is what the "configure" that someone mentioned would have done?

What configure would have done is put the correct value of the
DOCBOOKSTYLE variable in Makefile.global.  In Josh's case,
collateindex.pl was not found so the variable is empty, with the results
you see.

I think there's nothing to change here, except maybe to warn something
if DOCBOOKSTYLE is defined to empty.

--
Álvaro Herrera <alvherre@commandprompt.com>
The PostgreSQL Company - Command Prompt, Inc.
PostgreSQL Replication, Consulting, Custom Development, 24x7 support

Re: Cannot build docs on Ubuntu 10.04?

From

Tom Lane

Date:

14 March 2012, 14:22:18

John Lumby <johnlumby@hotmail.com> writes:
> On 12-01-2012 17:28, Josh Berkus wrote:
> I wonder if everyone noticed that the postgres sgml makefile is looking for the script in /bin
> (see Josh's append)

That means that configure failed to find it, and failed to determine
a setting for DOCBOOKSTYLE as well.

> I think this line in
> postgresql-9.1.3/doc/src/sgml/Makefile

> COLLATEINDEX = $(DOCBOOKSTYLE)/bin/collateindex.pl

> could be improved� -� maybe should read

> COLLATEINDEX = `which collateindex.pl`

No, that would not be an improvement.  If collateindex.pl were in your
PATH, then configure would have found it (cf PGAC_PATH_COLLATEINDEX),
and so COLLATEINDEX would be set and we'd not be here at all.

Maybe the Makefile should just error out if COLLATEINDEX isn't set,
rather than trying a "fallback" value that configure has already
determined isn't going to work.

            regards, tom lane

Re: Cannot build docs on Ubuntu 10.04?

From

John Lumby

Date:

14 March 2012, 17:47:38

Álvaro Herrera wrote :

> What configure would have done is put the correct value of the

> DOCBOOKSTYLE variable in Makefile.global.  In Josh's case,

> collateindex.pl was not found so the variable is empty, with the results
you see.


I see,  thanks.

Tom Lane wrote :


> No, that would not be an improvement.  If collateindex.pl were in your

> PATH, then configure would have found it (cf PGAC_PATH_COLLATEINDEX),

> and so COLLATEINDEX would be set and we'd not be here at all.


Ok

> Maybe the Makefile should just error out if COLLATEINDEX isn't set,

> rather than trying a "fallback" value that configure has already

> determined isn't going to work.


actually,  now I understand what happened,   I suggest adding an additional configure option
 --disable-docs

and configure should baulk if neither --disable-docs nor  collateindex.pl in the PATH.
That makes it explicit.

Cheers    John

Re: Cannot build docs on Ubuntu 10.04?

From

Tom Lane

Date:

22 March 2012, 04:13:10

I wrote:
> Maybe the Makefile should just error out if COLLATEINDEX isn't set,
> rather than trying a "fallback" value that configure has already
> determined isn't going to work.

I looked at this a bit closer, and figured out why the Makefile is
trying an apparently pointless case: the test implemented in configure
is wrong!  In at least some installations of docbook, for instance the
ancient one I've got in captivity on my HPUX box, collateindex.pl is
provided in $(DOCBOOKSTYLE)/bin/, but *it is not marked executable*.
This causes AC_PATH_PROGS to not consider it valid.  However, the docs
Makefile is coded to invoke the script via $(PERL) $(COLLATEINDEX),
which is presumably done precisely to be able to cope with
not-executable scripts.

So I think we should adjust the configure test to accept
$(DOCBOOKSTYLE)/bin/collateindex.pl if it is readable, whether or not it
is executable, and only use the Autoconf macro if we fall back to
searching PATH for collateindex.pl.  Having done that, it should be safe
to simplify the Makefile to throw error if COLLATEINDEX isn't set.

            regards, tom lane