Thread: sgml cleanup

sgml cleanup

From
Brent Verner
Date:
Hi all,

  In trying to get the doc/ tree in cvs to build, I noticed a _lot_ of
empty closing tags when I ran

  sh$ nsgmls -s -wall ./book-decl.sgml ./reference.sgml

from doc/src/sgml.  I know little about docbook, so I fixed the
tags to see if that would fix my problems in making man.tar, but
I still haven't gotten the man.tar to make properly :-(  I have a
patch against head to fix the empty tags, but it is quite large and
touches a /lot/ of files (listed below).  If this is a real problem,
let me know, and I'll send the patch to -patches (the gzipped patch
is about 17k).

  I also have modifications to config/docbook.m4 and doc/src/Makefile.in
to allow docs to (almost) build on my debian box.  The last outstanding
problem is that the names of the generated man pages have whitespace
between the program name and the appended ".1"...

brent$ tar tvf man.tar
drwxr-sr-x brent/brent       0 2001-11-21 21:16:24 man1/
-rw-r--r-- brent/brent    3797 2001-11-21 21:16:21 man1/createdb.1
-rw-r--r-- brent/brent    3041 2001-11-21 21:16:21 man1/createlang.1
-rw-r--r-- brent/brent    3748 2001-11-21 21:16:21 man1/createuser.1
-rw-r--r-- brent/brent    2821 2001-11-21 21:16:21 man1/dropdb.1
-rw-r--r-- brent/brent    2573 2001-11-21 21:16:22 man1/droplang.1
-rw-r--r-- brent/brent    2887 2001-11-21 21:16:22 man1/dropuser.1
-rw-r--r-- brent/brent    5987 2001-11-21 20:39:25 man1/ecpg  .1
-rw-r--r-- brent/brent    4648 2001-11-21 21:16:23 man1/initdb.1
-rw-r--r-- brent/brent    1562 2001-11-21 21:16:23 man1/initlocation.1
-rw-r--r-- brent/brent    1721 2001-11-21 21:16:23 man1/ipcclean.1
-rw-r--r-- brent/brent    2832 2001-11-21 21:16:22 man1/pg_config.1
-rw-r--r-- brent/brent    6409 2001-11-21 21:16:23 man1/pg_ctl.1
-rw-r--r-- brent/brent   12585 2001-11-21 20:39:26 man1/pg_dump\n  .1
-rw-r--r-- brent/brent    3669 2001-11-21 21:16:22 man1/pg_dumpall.1
-rw-r--r-- brent/brent    2678 2001-11-21 21:16:23 man1/pg_passwd.1
-rw-r--r-- brent/brent   12277 2001-11-21 20:39:26 man1/pg_restore\n  .1
-rw-r--r-- brent/brent    3613 2001-11-21 21:16:22 man1/pgaccess.1
-rw-r--r-- brent/brent    1098 2001-11-21 20:39:27 man1/pgtclsh\n  .1
-rw-r--r-- brent/brent    1196 2001-11-21 20:33:55 man1/pgtksh\n  .1


  Anyone care to share the details of the patched docbook2man-spec.pl
file mentioned in doc/src/Makefile.in?  Do these modifications fix the
problems seen above?

cheers.
  brent

brent$ grep '^Index: ' pgsql-doc.diff
Index: doc/src/sgml/protocol.sgml
Index: doc/src/sgml/ref/abort.sgml
Index: doc/src/sgml/ref/alter_group.sgml
Index: doc/src/sgml/ref/alter_table.sgml
Index: doc/src/sgml/ref/alter_user.sgml
Index: doc/src/sgml/ref/analyze.sgml
Index: doc/src/sgml/ref/begin.sgml
Index: doc/src/sgml/ref/close.sgml
Index: doc/src/sgml/ref/cluster.sgml
Index: doc/src/sgml/ref/comment.sgml
Index: doc/src/sgml/ref/commit.sgml
Index: doc/src/sgml/ref/copy.sgml
Index: doc/src/sgml/ref/create_aggregate.sgml
Index: doc/src/sgml/ref/create_constraint.sgml
Index: doc/src/sgml/ref/create_database.sgml
Index: doc/src/sgml/ref/create_function.sgml
Index: doc/src/sgml/ref/create_group.sgml
Index: doc/src/sgml/ref/create_index.sgml
Index: doc/src/sgml/ref/create_operator.sgml
Index: doc/src/sgml/ref/create_rule.sgml
Index: doc/src/sgml/ref/create_sequence.sgml
Index: doc/src/sgml/ref/create_table.sgml
Index: doc/src/sgml/ref/create_table_as.sgml
Index: doc/src/sgml/ref/create_type.sgml
Index: doc/src/sgml/ref/create_user.sgml
Index: doc/src/sgml/ref/create_view.sgml
Index: doc/src/sgml/ref/declare.sgml
Index: doc/src/sgml/ref/drop_aggregate.sgml
Index: doc/src/sgml/ref/drop_database.sgml
Index: doc/src/sgml/ref/drop_function.sgml
Index: doc/src/sgml/ref/drop_group.sgml
Index: doc/src/sgml/ref/drop_index.sgml
Index: doc/src/sgml/ref/drop_operator.sgml
Index: doc/src/sgml/ref/drop_rule.sgml
Index: doc/src/sgml/ref/drop_sequence.sgml
Index: doc/src/sgml/ref/drop_table.sgml
Index: doc/src/sgml/ref/drop_trigger.sgml
Index: doc/src/sgml/ref/drop_type.sgml
Index: doc/src/sgml/ref/drop_user.sgml
Index: doc/src/sgml/ref/drop_view.sgml
Index: doc/src/sgml/ref/ecpg-ref.sgml
Index: doc/src/sgml/ref/end.sgml
Index: doc/src/sgml/ref/explain.sgml
Index: doc/src/sgml/ref/fetch.sgml
Index: doc/src/sgml/ref/listen.sgml
Index: doc/src/sgml/ref/lock.sgml
Index: doc/src/sgml/ref/move.sgml
Index: doc/src/sgml/ref/notify.sgml
Index: doc/src/sgml/ref/pg_config-ref.sgml
Index: doc/src/sgml/ref/pg_dump.sgml
Index: doc/src/sgml/ref/pg_restore.sgml
Index: doc/src/sgml/ref/pg_upgrade.sgml
Index: doc/src/sgml/ref/pgtclsh.sgml
Index: doc/src/sgml/ref/pgtksh.sgml
Index: doc/src/sgml/ref/reindex.sgml
Index: doc/src/sgml/ref/rollback.sgml
Index: doc/src/sgml/ref/select.sgml
Index: doc/src/sgml/ref/select_into.sgml
Index: doc/src/sgml/ref/truncate.sgml
Index: doc/src/sgml/ref/unlisten.sgml
Index: doc/src/sgml/ref/update.sgml
Index: doc/src/sgml/ref/vacuum.sgml


--
"Develop your talent, man, and leave the world something. Records are
really gifts from people. To think that an artist would love you enough
to share his music with anyone is a beautiful thing."  -- Duane Allman

Re: sgml cleanup

From
Tom Lane
Date:
Brent Verner <brent@rcfile.org> writes:
>   In trying to get the doc/ tree in cvs to build, I noticed a _lot_ of
> empty closing tags when I ran

?? I'm not seeing any of these problems.  Are you using the recommended
docs toolchain?

            regards, tom lane

Re: sgml cleanup

From
Tom Lane
Date:
Brent Verner <brent@rcfile.org> writes:
> On 21 Nov 2001 at 23:11 (-0500), Tom Lane wrote:
> | ?? I'm not seeing any of these problems.  Are you using the recommended
> | docs toolchain?

> I have no clue about the recommended docs toolchain.

I don't claim to be excessively clued either ... all I know is what I
read in the PG docs:
http://www.ca.postgresql.org/users-lounge/docs/7.1/postgres/doc-toolsets.html

            regards, tom lane

Re: sgml cleanup

From
Brent Verner
Date:
On 21 Nov 2001 at 23:11 (-0500), Tom Lane wrote:
| Brent Verner <brent@rcfile.org> writes:
| >   In trying to get the doc/ tree in cvs to build, I noticed a _lot_ of
| > empty closing tags when I ran
|
| ?? I'm not seeing any of these problems.  Are you using the recommended
| docs toolchain?

I have no clue about the recommended docs toolchain.  I must not be,
since my docbook2man-spec.pl does not (seem to) accept command line
arguments.  I've built postgresql.tar, but man.tar is still giving
me fits. The built html files can be seen at
  http://rcfile.org/posthack/pgdocs/

What I am seeing from a fresh update (at 11:19 EST) is this.

sleepy:~/pgsql/doc/src
brent$ grep '</>' sgml/*  |wc -l
grep: sgml/CVS: Is a directory
grep: sgml/ref: Is a directory
   1639
sleepy:~/pgsql/doc/src
brent$ grep -Hn '</>' sgml/xoper.sgml
sgml/xoper.sgml:116:     operators <literal><</> and <literal>></> for a particular data type are usually each
others'
sgml/xoper.sgml:117:     commutators, and operator <literal>+</> is usually commutative with itself.
sgml/xoper.sgml:118:     But operator <literal>-</> is usually not commutative with anything.
sgml/xoper.sgml:179:     For example, <literal><</> and <literal>>=</> are a negator pair for most data types.
sgml/xoper.sgml:242:    make sense if you think about it.  <literal>=</> will typically accept only
sgml/xoper.sgml:243:    a small fraction of the rows in a table; <literal><></> will typically reject
sgml/xoper.sgml:244:    only a small fraction.  <literal><</> will accept a fraction that depends on
sgml/xoper.sgml:248:    <literal><=</> will accept a slightly larger fraction than <literal><</> for the same
sgml/xoper.sgml:251:    rough guess anyhow.  Similar remarks apply to <literal>></> and <literal>>=</>.
sgml/xoper.sgml:359:     joins.  On machines that meet the <acronym>IEEE</> floating point standard, minus
sgml/xoper.sgml:389:     that can only succeed for pairs of values that fall at the <quote>same place</>
sgml/xoper.sgml:413:     In practice you should only write SORT clauses for an <literal>=</> operator,
sgml/xoper.sgml:414:     and the two referenced operators should always be named <literal><</>.  Trying
sgml/xoper.sgml:436:  There must be <literal><</> and <literal>></> ordering operators having the same left and
sgml/xoper.sgml:438:  operators <emphasis>must</emphasis> be named <literal><</> and <literal>></>; you do


confused,
  brent

--
"Develop your talent, man, and leave the world something. Records are
really gifts from people. To think that an artist would love you enough
to share his music with anyone is a beautiful thing."  -- Duane Allman

Re: sgml cleanup

From
Bruce Momjian
Date:
> Brent Verner <brent@rcfile.org> writes:
> > On 21 Nov 2001 at 23:11 (-0500), Tom Lane wrote:
> > | ?? I'm not seeing any of these problems.  Are you using the recommended
> > | docs toolchain?
>
> > I have no clue about the recommended docs toolchain.
>
> I don't claim to be excessively clued either ... all I know is what I
> read in the PG docs:
> http://www.ca.postgresql.org/users-lounge/docs/7.1/postgres/doc-toolsets.html

I think we use docbook 3.2 while 4.0 doesn't support </>, or something
like that.

--
  Bruce Momjian                        |  http://candle.pha.pa.us
  pgman@candle.pha.pa.us               |  (610) 853-3000
  +  If your life is a hard drive,     |  830 Blythe Avenue
  +  Christ can be your backup.        |  Drexel Hill, Pennsylvania 19026

Re: sgml cleanup

From
Brent Verner
Date:
On 22 Nov 2001 at 00:07 (-0500), Bruce Momjian wrote:
| > Brent Verner <brent@rcfile.org> writes:
| > > On 21 Nov 2001 at 23:11 (-0500), Tom Lane wrote:
| > > | ?? I'm not seeing any of these problems.  Are you using the recommended
| > > | docs toolchain?
| >
| > > I have no clue about the recommended docs toolchain.
| >
| > I don't claim to be excessively clued either ... all I know is what I
| > read in the PG docs:
| > http://www.ca.postgresql.org/users-lounge/docs/7.1/postgres/doc-toolsets.html
|
| I think we use docbook 3.2 while 4.0 doesn't support </>, or something
| like that.

ah, so "</>" _is_ a legal closing tag.  I suspected as much after
seeing how many there were, and the fact that I could get thru the
postgres.tar build.

  I found that I had to have the 0.7.0 version of docbook2man-spec.pl
instead of the version installed on my system (0.6.9).  After tweaking
the script to run, I finally got the man.tar made :-)

sorry for the noise.
  brent

Happy Thanksgiving to you all!
--
"Develop your talent, man, and leave the world something. Records are
really gifts from people. To think that an artist would love you enough
to share his music with anyone is a beautiful thing."  -- Duane Allman

Re: sgml cleanup

From
Peter Eisentraut
Date:
Brent Verner writes:

>   In trying to get the doc/ tree in cvs to build, I noticed a _lot_ of
> empty closing tags when I ran
>
>   sh$ nsgmls -s -wall ./book-decl.sgml ./reference.sgml

The -wall option isn't very useful.  Empty closing tags are perfectly
legal.  I don't know if they're good style, but as long as you don't
exaggerate I don't feel that they aren't.  They're not allowed in XML,
though.

>   Anyone care to share the details of the patched docbook2man-spec.pl
> file mentioned in doc/src/Makefile.in?  Do these modifications fix the
> problems seen above?

The man pages for release 7.1 where built with docbook2X 0.6.1 plus the
patch available on my web page[1].  7.2 is probably going to be the same.

[1] http://webmail.postgresql.org/~petere/docbook2man.html

--
Peter Eisentraut   peter_e@gmx.net


Re: sgml cleanup

From
Brent Verner
Date:
On 22 Nov 2001 at 18:21 (+0100), Peter Eisentraut wrote:
| Brent Verner writes:
|
| >   In trying to get the doc/ tree in cvs to build, I noticed a _lot_ of
| > empty closing tags when I ran
| >
| >   sh$ nsgmls -s -wall ./book-decl.sgml ./reference.sgml
|
| The -wall option isn't very useful.  Empty closing tags are perfectly
| legal.  I don't know if they're good style, but as long as you don't
| exaggerate I don't feel that they aren't.  They're not allowed in XML,
| though.

gotcha.  When I hit problems with the man.tar build, I started looking
for /any/ cause.  The '</>' was the first thing I noticed.

| >   Anyone care to share the details of the patched docbook2man-spec.pl
| > file mentioned in doc/src/Makefile.in?  Do these modifications fix the
| > problems seen above?
|
| The man pages for release 7.1 where built with docbook2X 0.6.1 plus the
| patch available on my web page[1].  7.2 is probably going to be the same.
|
| [1] http://webmail.postgresql.org/~petere/docbook2man.html

cool.  I ended up fixing up the newest (0.7.0) release of his script,
and finally did get man.tar built.  Is there any desire to distribute
a copy of the patched script in cvs?  This would make it much easier
for people who might want to package a given cvs snapshot...

I've attached a patch which adds a directory to search for docbook
stylesheets in the config/docbook.m4 if there is any interest in
supporting another platform for building the cvs docs.  This (in
addition to minor doc/src/Makefile mods[1]) allows me to build on
a debian (unstable) box.

[1] patch attached for this as well.

thanks.
  brent

--
"Develop your talent, man, and leave the world something. Records are
really gifts from people. To think that an artist would love you enough
to share his music with anyone is a beautiful thing."  -- Duane Allman

Attachment

Re: sgml cleanup

From
Peter Eisentraut
Date:
Brent Verner writes:

> This (in addition to minor doc/src/Makefile mods[1]) allows me to
> build on a debian (unstable) box.

I don't understand that patch.

--
Peter Eisentraut   peter_e@gmx.net


Re: sgml cleanup

From
Brent Verner
Date:
On 22 Nov 2001 at 19:44 (+0100), Peter Eisentraut wrote:
| Brent Verner writes:
|
| > This (in addition to minor doc/src/Makefile mods[1]) allows me to
| > build on a debian (unstable) box.
|
| I don't understand that patch.

I'm sorry, I wrote "doc/src/Makefile mods..."  That should have been
"doc/src/sgml/Makefile mods..."

On my system, collateindex.pl is not in $(DOCBOOKSTYLE)/bin. With
that patch applied I can do
  sh$ make man.tar COLLATEINDEX=/usr/bin/collateindex.pl D2MDIR=/usr/local/bin

IMO, these patches are not very important, which is why I didn't send
them to -patches. If you don't feel the changes are useful to others,
I won't mind keeping up with the changes locally.

cheers.
  brent

--
"Develop your talent, man, and leave the world something. Records are
really gifts from people. To think that an artist would love you enough
to share his music with anyone is a beautiful thing."  -- Duane Allman